unpkg-mcp

unpkg-mcp

A remote MCP server for UNPKG. It gives AIagents live npm and UNPKG data for direct UNPKG file lookups:https://unpkg.com/<package>@<version>/<file>.

Agents often recall npm details incorrectly — versions that don't exist, filepaths that were never published, Node entry points offered as browser modules.This server resolves versions, lists real package files, audits projects forUNPKG conversion, validates import maps, and checks packages for malware andCVEs, all from live data.

Deployed at https://mcp.unpkg.com (landing page at /, MCP endpoint at/mcp).

Tools

Package safety checks

Every package the server resolves can also be checked against Shield'ssecurity data, in two ways:

• Named packages. shield_check_packages takes exactpackage@version pairs and returns, for each one, a malware verdictwith its review state (confirmed or provisional), the CVEs thataffect that version, and the first patched version to upgrade to.Verdicts and CVE matches are computed for the exact version askedabout — a clean result never comes from checking a different version.
• Inside audits. audit_dependencies attaches the same verdict andCVE data to every version it resolves, so a flagged package isvisible in the audit result next to its conversion recommendation.

No account is needed for either: named-package checks are anonymous(25 per call), and audit enrichment works the same signed out. Aprovisional verdict is reported as provisional; it is not presented asconfirmed malicious.

With a Shield login, the checks extend to your own estate:shield_domain_packages (with threats enabled) returns the packagesobserved on your verified domains annotated with verdicts and CVEs,ranked by each domain's traffic, so the packages that matter mostsurface first.

Example prompts:

• "Is [email protected] safe to load? Check it for malware and CVEs,and tell me what to upgrade to."
• "Check the packages in this audit for known compromises or CVEsbefore we convert anything."
• (Shield login) "Which packages on my domains have CVEs or malwareverdicts, worst first?"

Shield login

The general tools are anonymous. With a Shield account approved from thebeta waitlist, your MCP client can also sign in via OAuth and theshield_* account tools unlock, scoped to your own organization.

Package-safety checks are not login-gated: shield_check_packages worksanonymously for packages you name, and audit_dependencies includesverdicts and CVEs either way. Signing in adds your own domains,watchlist, and edge simulation.

Prompts, resources, and skill

• Prompts: audit_project_for_unpkg, convert_this_page,find_browser_package.
• Resources: the conversion playbook and version-specifier policy(unpkg://guidance/…), also served at GET /playbook.md.
• Skill: skill/unpkg/SKILL.md provides the same guidance to agentswithout MCP.

Connect a client

Clients connect by URL. Per-client configuration is inexamples/clients.md and in the picker on thelanding page at https://mcp.unpkg.com/.

Claude Code:

claude mcp add --transport http unpkg https://mcp.unpkg.com/mcp

For agents without MCP, copy skill/unpkg/ into the client's skillsdirectory. At the project level, you can also pasteexamples/AGENTS.snippet.md into yourproject's AGENTS.md.

Try it out

With an agent connected, some useful prompts:

• "Resolve react@^18 with the UNPKG MCP — what's the resolved versionand browser entry point? Now try a version of react that doesn'texist."
• "List the files in [email protected]/dist, build a patch-policy URLfor the module file, and verify it resolves."
• "Audit this project for UNPKG conversion."
• "Check this import map with the UNPKG MCP: …" (paste a map)
• "Is [email protected] safe to load? Check it for malware and CVEs, andtell me what to upgrade to."
• "Based on the audit, estimate the migration impact for a site with1M page views a month at $0.09/GB."

The server reports what it can verify and declines what it can't:import maps are validated as a system, audits keep framework-managedpackages bundled, and estimates come back as ranges with assumptionsrather than a single figure.

MCP Registry

server.json in this repo is the listing manifest for the officialMCP Registry, under the namespace io.github.unpkg/unpkg-mcp.

Publishing (maintainers): install the mcp-publisher CLI from theMCP Registry project, then from this repo:

mcp-publisher login github
mcp-publisher publish

Note: the organization namespace requires an owner-level GitHubcredential — the interactive device flow only grants your personalnamespace. Use a classic PAT with read:org scope (see the MCPRegistry authentication docs), and revoke it afterwards.

Releasing

The server is a remote endpoint, so most channels update themselves:connected clients see new tools as soon as the Worker deploys, Glamare-crawls this repo and the endpoint, skills.sh serves the skill fromGitHub, and directory listings (awesome lists, mcp.so) are staticentries that only change if the URL or description changes.

For a version release:

1. Bump the version everywhere it appears, keeping all of them equal:package.json, src/version.ts, server.json,plugin/.claude-plugin/plugin.json, plugin/plugin.json,plugin/.codex-plugin/plugin.json, and the plugin entry in.claude-plugin/marketplace.json. (Tests fail if any of thesedrift.)
2. Deploy the Worker (wrangler deploy).
3. Tag the release on GitHub (vX.Y.Z with release notes).
4. Republish the registry manifest: mcp-publisher publish.Downstream directories (PulseMCP, Smithery, and others) ingestfrom the official MCP Registry, so this is the step that updatesthem.
5. If the plugin changed, publish the new plugin version in theClaude developer portal; marketplace users get it viaclaude plugin marketplace update.

Claude plugin

This repo is also a Claude Code plugin (and its own plugin marketplace).The plugin lives in plugin/ and bundles the MCP server above with theunpkg skill, so one install gives Claude Code both:

claude plugin marketplace add unpkg/unpkg-mcp
claude plugin install unpkg@unpkg

Connecting the plugin is the same anonymous-by-default server athttps://mcp.unpkg.com/mcp; Shield tools still sign in only when used.

Run it locally

pnpm install
pnpm dev          # HTTP Worker on http://localhost:8787

• Landing page: http://localhost:8787/
• Health: http://localhost:8787/health
• MCP endpoint: http://localhost:8787/mcp
• Server card: http://localhost:8787/.well-known/mcp.json

For local client setup, use the same configurations as above withhttp://localhost:8787/mcp in place of the production URL.

Develop

pnpm test         # unit, golden-project, and MCP protocol tests
pnpm typecheck    # tsc --noEmit
pnpm build        # wrangler deploy --dry-run (production bundle check)

Layout: src/clients/ (npm, UNPKG, and Shield API clients),src/domain/ (audit, import-map checking, estimation, guidance),src/server.ts (MCP wiring). Golden projects intest/fixtures/projects/ pin audit classification behavior.

Environment (wrangler.jsonc vars): UNPKG_ORIGIN, NPM_REGISTRY,SHIELD_API_ORIGIN, OAUTH_ISSUER, OAUTH_RESOURCE, OAUTH_ENABLED.

Estimating impact

audit_dependencies reports entry-file byte totals.estimate_migration_impact turns those, plus a traffic figure, into abandwidth-offload range (and a dollar range when a $/GB rate issupplied). It does not forecast latency: where a site already servesfrom a capable CDN, latency is usually unchanged, and the practicalgains are bundle size, cacheability, and how quickly patched versionsreach users.