12.4 官方注册表 Registry

🎯 学习目标：理解官方注册表在生态中的位置，并把一个服务器按规范发布上去 ⏱️ 预计时间：35 分钟 📊 难度等级：⭐⭐⭐（操作为主）

📌 一句话结论：MCP Registry 是官方集中式元数据仓库，只存元数据、不存代码/二进制。它用反向 DNS 命名空间做归属认证，把"服务器"映射到 npm / PyPI / NuGet / Cargo / OCI 里的真实包。

⚠️ 当前状态：preview（预览）。正式发布前可能出现破坏性变更或数据重置。遇到问题请到 registry issues 反馈。

🎯 它是什么，解决什么问题

MCP Registry 是面向公开可访问 MCP 服务器的官方集中式元数据仓库，由 Anthropic、GitHub、PulseMCP、Microsoft 等生态核心贡献者共同支撑。

它提供四件事：

服务器作者的统一发布入口（发布自己服务器的元数据）
通过 DNS 验证做命名空间管理
供客户端与聚合器发现服务器的 REST API
标准化的安装与配置信息

📄 `server.json`：元数据的载体

服务器元数据以标准化的 server.json 格式存储，包含：

服务器的唯一名称（如 io.github.user/server-name）
去哪找这个服务器（如 npm 包名、远程服务器 URL）
执行说明（如命令行参数、环境变量）
其他发现信息（描述、能力等）

json

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.my-username/weather",
  "description": "An MCP server for weather information.",
  "repository": {
    "url": "https://github.com/my-username/mcp-weather-server",
    "source": "github"
  },
  "version": "1.0.1",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/mcp-weather-server",
      "version": "1.0.1",
      "transport": { "type": "stdio" }
    }
  ]
}

🌐 它在生态里的位置

与包注册表的关系

注册表	存什么
包注册表（npm / PyPI / Docker Hub…）	代码与二进制
MCP Registry	指向这些包的元数据

例如 weather-mcp 包托管在 npm，MCP Registry 的元数据把"weather v1.2.0"这个服务器映射到 npm:weather-mcp。

与服务器开发者的关系

支持开源与闭源服务器
只要安装方式公开可得（公开 npm 包 / 公开 Docker 镜像），或服务器本身公开可访问（非私网限制的远程服务器），即可发布
❌ 不支持私有服务器：仅对少数用户可见的（如私网 mcp.acme-corp.internal、私有包注册表）不能发布。想收录私有服务器，建议自建私有注册表

与下游聚合器的关系

Registry 主要面向下游聚合器（如 MCP 服务器市场）消费，本身刻意保持无观点（unopinionated）——策展、社区评分等交给聚合器。预期聚合器会以低频但规律（例如每小时一次）的节奏通过 API 拉取新元数据。

与其他 MCP 注册表的关系

除公开 REST API 外，Registry 还定义了 OpenAPI 规范，其他 MCP 注册表可以按其实现，为宿主应用提供标准接口。私有注册表也可实现该接口以获得既有宿主应用的兼容。

⚠️ 官方 Registry 代码库不是为自托管设计的，维护者不为该用例提供支持。若你 fork，需独立维护运营。

与宿主应用的关系

Registry 不打算被宿主应用直接消费。宿主应用应消费下游注册表（市场），通过符合官方 OpenAPI 规范的 REST API 接入。

🛡️ 信任与安全

服务器真实性验证

用命名空间认证保证服务器来自其声称的来源。服务器名用反向 DNS 格式（如 io.github.username/server、com.example/server），绑定到已验证的 GitHub 账号或域名——只有该账号/域名的合法拥有者才能在其命名空间下发布。

安全扫描

Registry 把安全扫描委托出去：

底层包注册表（npm / PyPI / Docker Hub…）各自做扫描与漏洞检测
下游聚合器/市场可加额外安全检查、评分、策展

Registry 自身聚焦命名空间认证与元数据托管，依赖生态完成对实际服务器代码的安全扫描。

反垃圾

命名空间认证要求：必须通过 GitHub / DNS / HTTP 挑战验证所有权
字符限制与校验：自由字段有严格长度限制与正则校验
人工下架：维护者可移除垃圾或恶意服务器

📦 六种包类型与各自的归属验证

每种包类型有不同的归属验证方式——这是发布时最容易踩坑的地方。

包类型	`registryType`	验证方式
npm	`npm`	`package.json` 里的 `mcpName` 必须等于 `server.json` 里的服务器名
PyPI	`pypi`	README（即 PyPI 描述）里含 `mcp-name: $SERVER_NAME` 字符串，可藏在注释里
NuGet	`nuget`	README 里含 `mcp-name: $SERVER_NAME` 字符串
Cargo（Rust）	`cargo`	README 里含 `mcp-name: $SERVER_NAME`，但必须是可见文本（见下）
Docker/OCI	`oci`	镜像含 `io.modelcontextprotocol.server.name` 注解（Dockerfile `LABEL`）
MCPB	`mcpb`	`identifier` URL 必须含 "mcp" 字符串 + 元数据须带 `fileSha256`

npm 示例：

json

{
  "name": "@username/email-integration-mcp",
  "version": "1.0.0",
  "mcpName": "io.github.username/email-integration-mcp"
}

Cargo 的坑（重要）： 与 PyPI/NuGet 不同，crates.io 在 markdown→HTML 转换时会剥掉 HTML 注释。所以对 PyPI/NuGet 有效的  隐藏注释写法对 Cargo 无效——验证器检查的渲染 HTML 里不会出现该 token。Cargo 作者必须把 mcp-name: 作为可见 markdown 文本（推荐在 Links 区块加一条 bullet）。

OCI 示例：

dockerfile

LABEL io.modelcontextprotocol.server.name="io.github.username/kubernetes-manager-mcp"

MCPB 校验：

identifier URL 必须含 "mcp"（.mcpb 扩展名或仓库名带 mcp 均可）
元数据必须含 fileSha256（用 openssl dgst -sha256 image-processor.mcpb 计算）
Registry 不校验该哈希，但 MCP 客户端在安装前会校验文件完整性

💡 Cargo vs MCPB（Rust 作者二选一）：Cargo 是源码分发（用户需 rustup 才能 cargo install）；MCPB 是预编译二进制（用户无需工具链）。追求"零工具链"就选 MCPB。

🚀 发布流程（`mcp-publisher`）

以下以 TypeScript + npm 为例，用官方 mcp-publisher CLI 走完六步。

前置条件：Node.js、npm 账号（Registry 只托管元数据，包要先发到 npm）、GitHub 账号（用 GitHub 认证）。

第 1 步：给包加验证信息

npm 包需要在 package.json 里加 mcpName：

diff

 {
   "name": "@my-username/mcp-weather-server",
   "version": "1.0.1",
+  "mcpName": "io.github.my-username/weather",
   "main": "index.js",

mcpName 的值就是你在 Registry 里的服务器名。用 GitHub 认证时，它必须以 io.github.my-username/ 开头。

第 2 步：发布包到 npm

Registry 只存元数据，所以先发包：

bash

npm install
npm run build
npm adduser
npm publish --access public

第 3 步：安装 `mcp-publisher`

bash

brew install mcp-publisher
# 或从 GitHub Releases 下载预编译二进制
mcp-publisher --help

第 4 步：生成 `server.json`

bash

mcp-publisher init

它会依据你的项目生成模板，按需修改。server.json 里的 name 必须与 package.json 里的 mcpName 一致。

第 5 步：登录认证

bash

mcp-publisher login github

按提示到 https://github.com/login/device 输入终端里打印的验证码并授权。

第 6 步：发布

bash

mcp-publisher publish

验证是否发布成功：

bash

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.my-username/weather"

🔧 常见报错

报错	处理
`Registry validation failed for package`	确认包里有必需的验证信息（如 `package.json` 的 `mcpName`）
`Invalid or expired Registry JWT token`	重新运行 `mcp-publisher login github`
`You do not have permission to publish this server`	认证方式与命名空间格式不匹配。GitHub 认证下服务器名必须以 `io.github.your-username/` 开头

其他认证方式：除 GitHub 外还支持 DNS 认证（可启用自定义域名的服务器名前缀）等；也可用 GitHub Actions 自动发布。

📖 官方资料

👉 下一小节：12.5 MCP Inspector 工具链

12.4 官方注册表 Registry ​

🎯 它是什么，解决什么问题 ​

📄 server.json：元数据的载体 ​

🌐 它在生态里的位置 ​

与包注册表的关系 ​

与服务器开发者的关系 ​

与下游聚合器的关系 ​

与其他 MCP 注册表的关系 ​

与宿主应用的关系 ​

🛡️ 信任与安全 ​

服务器真实性验证 ​

安全扫描 ​

反垃圾 ​

📦 六种包类型与各自的归属验证 ​

🚀 发布流程（mcp-publisher） ​

第 1 步：给包加验证信息 ​

第 2 步：发布包到 npm ​

第 3 步：安装 mcp-publisher ​

第 4 步：生成 server.json ​

第 5 步：登录认证 ​

第 6 步：发布 ​

🔧 常见报错 ​

📖 官方资料 ​

12.4 官方注册表 Registry

🎯 它是什么，解决什么问题

📄 `server.json`：元数据的载体

🌐 它在生态里的位置

与包注册表的关系

与服务器开发者的关系

与下游聚合器的关系

与其他 MCP 注册表的关系

与宿主应用的关系

🛡️ 信任与安全

服务器真实性验证

安全扫描

反垃圾

📦 六种包类型与各自的归属验证

🚀 发布流程（`mcp-publisher`）

第 1 步：给包加验证信息

第 2 步：发布包到 npm

第 3 步：安装 `mcp-publisher`

第 4 步：生成 `server.json`

第 5 步：登录认证

第 6 步：发布

🔧 常见报错

📖 官方资料