UNPKG

unpkg-mcp

面向 UNPKG 的远程 MCP 服务。它为 AI Agent 提供实时 npm 和 UNPKG 数据，以便直接查询 UNPKG 文件： https://unpkg.com/<package>@<version>/<file>。

Agent 经常会记错 npm 详情——不存在的版本、从未发布过的文件路径，以及作为浏览器模块提供的 Node 入口点。此服务会解析版本、列出实际的包文件、审查项目的 UNPKG 转换情况、验证导入映射，并根据实时数据检查包是否含有恶意软件和 CVE。

部署于 https://mcp.unpkg.com（落地页位于 /，MCP 端点位于 /mcp）。

工具

工具	用途
resolve_package	将精确版本、标签或范围解析为实际版本及其浏览器入口点
search_packages	搜索 npm，并标注结果是否适用于浏览器
list_files	通过 ?meta API 列出指定版本包中的实际文件
build_file_url	使用版本策略（preserve、exact、patch 或 range）构建规范文件 URL
audit_dependencies	对 package.json 依赖映射进行分类（convert_now / convert_carefully / keep_bundled / needs_review / not_found），并提供建议的 URL、导入映射和框架检测结果；已从 UNPKG 加载的包会与转换候选项分开报告
verify_url	检查 UNPKG URL 是否可解析
generate_importmap	根据裸说明符生成导入映射
check_importmap	验证完整的导入映射：解析情况、文件是否存在、版本一致性以及框架管理的包
estimate_migration_impact	在注明假设条件的情况下，以范围形式估算迁移的带宽分流量
shield_check_packages	检查精确包版本的恶意软件判定和 CVE。匿名用户每次调用限 25 个；登录 Shield 后上限为 200 个
shield_whoami	（Shield 登录） 已连接用户的账户、组织和权益
shield_domain_packages	（Shield 登录） 在已验证域名上观察到的包，可按流量排名并选择性标注恶意软件判定和 CVE
shield_simulate_request	（Shield 登录） 预览 Shield 对某个包版本的固定或拦截决策
shield_watchlist_status	（Shield 登录） 你监控的包、拦截列表和固定策略

软件包安全检查

服务器解析的每个软件包都可以通过两种方式对照 Shield 的安全数据进行检查：

• 指定软件包。 shield_check_packages 接受精确的 package@version 对，并为每个软件包返回恶意软件判定及其审核状态（已确认或暂定）、影响该版本的 CVE，以及建议升级到的首个已修复版本。判定和 CVE 匹配均针对所查询的确切版本计算，干净的结果绝不会来自对其他版本的检查。
• 审计中的检查。 audit_dependencies 会将相同的判定和 CVE 数据附加到其解析的每个版本，因此被标记的软件包会与其转换建议一同显示在审计结果中。

这两种方式都不需要账号：指定软件包检查可匿名进行（每次调用 25 个），审计信息补充在未登录时也同样有效。暂定判定会标记为暂定，不会被表述为已确认的恶意软件。

登录 Shield 后，检查范围可扩展到你自己的资产： shield_domain_packages（启用威胁后）会返回在你已验证域名上观察到的软件包，并标注判定和 CVE；结果按各域名的流量排序，让最重要的软件包优先显示。

示例提示词：

• “[email protected] 加载起来安全吗？请检查它是否包含恶意软件或 CVE，并告诉我应该升级到哪个版本。”
• “在转换任何内容之前，请检查此审计中的软件包是否存在已知的安全漏洞或 CVE。”
• （已登录 Shield）“我域名上的哪些软件包存在 CVE 或恶意软件判定？请按风险从高到低排列。”

Shield 登录

通用工具可匿名使用。使用通过 Beta 候补名单审核的 Shield 账号后，你的 MCP 客户端还可以通过 OAuth 登录，并使用限定于你所在组织的 shield_* 账号工具。

软件包安全检查不要求登录：shield_check_packages 可匿名检查你指定的软件包，audit_dependencies 无论是否登录都会包含判定和 CVE。登录后还可使用你自己的域名、监控列表和边缘模拟。

提示词、资源和技能

• 提示词：audit_project_for_unpkg、convert_this_page、find_browser_package。
• 资源：转换指南和版本说明符策略（unpkg://guidance/…），也可通过 GET /playbook.md 获取。
• 技能：skill/unpkg/SKILL.md 为不使用 MCP 的 Agent 提供相同的指南。

连接客户端

客户端通过 URL 连接。各客户端的配置见 examples/clients.md，也可在主页的客户端选择器中查看：https://mcp.unpkg.com/。

Claude Code：

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

对于不使用 MCP 的 Agent，请将 skill/unpkg/ 复制到客户端的技能目录中。在项目级别，你也可以将 examples/AGENTS.snippet.md 粘贴到项目的 AGENTS.md 中。

试用

连接 Agent 后，可以尝试以下提示词：

• “使用 UNPKG MCP 解析 react@^18——解析出的版本和浏览器入口点是什么？再试试一个不存在的 react 版本。”
• “列出 [email protected]/dist 中的文件，为模块文件构建一个补丁策略 URL，并验证它能否解析。”
• “审计此项目是否适合转换为 UNPKG。”
• “使用 UNPKG MCP 检查此导入映射：……”（粘贴映射）
• “[email protected] 加载起来安全吗？请检查它是否包含恶意软件或 CVE，并告诉我应该升级到哪个版本。”
• “根据审计结果，估算一个每月有 1M 次页面浏览量、费用为 $0.09/GB 的网站所受的迁移影响。”

服务器会报告可验证的内容，并拒绝无法验证的请求： 导入映射会作为一个整体进行验证，审计会将由框架管理的软件包保留为捆绑包，而估算结果会以区间形式返回，并附上假设，而不是给出单一数值。

MCP 注册表

此仓库中的 server.json 是官方 MCP Registry 在命名空间 io.github.unpkg/unpkg-mcp 下的条目清单。

发布（维护者）：从 MCP Registry 项目安装 mcp-publisher CLI，然后在此仓库中运行：

mcp-publisher login github
mcp-publisher publish

注意：组织命名空间需要所有者级别的 GitHub 凭据——交互式设备授权流程只会授予你的个人命名空间权限。请使用具有 read:org 权限范围的经典 PAT（参见 MCP Registry 身份验证文档），并在之后撤销该 PAT。

发布版本

此服务是远程端点，因此大多数渠道会自动更新：连接的客户端会在 Worker 部署后立即看到新工具；Glama 会重新抓取此仓库和端点；skills.sh 会从 GitHub 提供该技能；目录列表（awesome lists、mcp.so）则是静态条目，只有 URL 或描述发生变化时才会更新。

发布新版本时：

1. 在所有出现版本号的地方更新版本号，并确保它们一致： package.json、src/version.ts、server.json、 plugin/.claude-plugin/plugin.json、plugin/plugin.json、 plugin/.codex-plugin/plugin.json，以及 .claude-plugin/marketplace.json 中的插件条目。（如果其中任何一项不一致，测试就会失败。）
2. 部署 Worker（wrangler deploy）。
3. 在 GitHub 上为发布版本打标签（vX.Y.Z，并附上发布说明）。
4. 重新发布注册表清单：mcp-publisher publish。 下游目录（PulseMCP、Smithery 等）会从官方 MCP Registry 获取数据，因此这一步会更新它们。
5. 如果插件有更改，请在 Claude 开发者门户中发布新版本的插件；市场用户可通过 claude plugin marketplace update 获取。

Claude 插件

此仓库也是一个 Claude Code 插件（并拥有自己的插件市场）。 插件位于 plugin/，其中捆绑了上述 MCP 服务和 unpkg 技能，因此只需安装一次，Claude Code 就能同时获得：

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

连接插件时使用的服务与默认匿名访问的服务相同，即 https://mcp.unpkg.com/mcp；Shield 工具仍然只会在使用时要求登录。

本地运行

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

• 着陆页：http://localhost:8787/
• 健康检查：http://localhost:8787/health
• MCP 端点：http://localhost:8787/mcp
• 服务卡片：http://localhost:8787/.well-known/mcp.json

配置本地客户端时，请使用与上文相同的配置，并将生产环境 URL 替换为 http://localhost:8787/mcp。

开发

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

目录结构：src/clients/（npm、UNPKG 和 Shield API 客户端）、 src/domain/（审计、import-map 检查、估算、指导）、 src/server.ts（MCP 接线）。test/fixtures/projects/ 中的黄金项目用于固定审计分类行为。

环境变量（wrangler.jsonc vars）：UNPKG_ORIGIN、NPM_REGISTRY、 SHIELD_API_ORIGIN、OAUTH_ISSUER、OAUTH_RESOURCE、OAUTH_ENABLED。

估算影响

audit_dependencies 会报告入口文件的字节总量。 estimate_migration_impact 会结合这些数据和流量数值，计算带宽卸载范围（若提供每 GB 费率，还会计算金额范围）。它不会预测延迟：对于已经通过高性能 CDN 提供服务的网站，延迟通常不会改变；实际收益体现在包体积、缓存能力以及修补版本触达用户的速度上。