Registry CLI 工具

MCP Publisher CLI 工具

mcp-publisher 是用于与 MCP Registry 交互的官方命令行工具，提供服务器发布、身份验证和管理功能。

安装

Homebrew（推荐）

在 macOS/Linux 上使用 Homebrew：

brew install mcp-publisher

预构建二进制文件

macOS/Linux/WSL:

curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/

Windows PowerShell:

$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }
Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"
tar xf mcp-publisher.tar.gz mcp-publisher.exe
rm mcp-publisher.tar.gz

从源码构建 

git clone https://github.com/modelcontextprotocol/registry
cd registry
make publisher
# 二进制文件位于 bin/mcp-publisher

全局选项

所有命令都支持以下选项：

  • --help, -h - 显示命令帮助
  • --registry - Registry URL（默认：https://registry.modelcontextprotocol.io）

命令参考

mcp-publisher init

生成包含自动检测的 server.json 模板。

用法：

mcp-publisher init [options]

行为：

  • 在当前目录创建 server.json
  • 自动检测包管理器（package.json、setup.py 等）
  • 尽可能预填字段
  • 提示输入缺失的必填字段

示例输出：

{
  "name": "io.github.username/server-name",
  "description": "TODO: 添加服务器描述",
  "version": "1.0.0",
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "detected-package-name",
      "version": "1.0.0"
    }
  ]
}

mcp-publisher login <方法>

向 Registry 进行身份验证。

GitHub 交互式登录 

mcp-publisher login github [--registry=URL]
  • 打开浏览器进行 GitHub OAuth 流程
  • 授予对 io.github.{username}/* 和 io.github.{org}/* 命名空间的访问权限

GitHub OIDC（CI/CD） 

mcp-publisher login github-oidc [--registry=URL]
  • 自动使用 GitHub Actions OIDC 令牌
  • 需要工作流中的 id-token: write 权限
  • 无需浏览器交互
有关从 GitHub Actions 发布的详细信息，请参阅 GitHub Actions 自动化发布指南。

DNS 验证 

mcp-publisher login dns --domain=example.com --private-key=HEX_KEY [--registry=URL]
  • 通过 DNS TXT 记录验证域名所有权
  • 授予对 com.example.* 命名空间的访问权限
  • 需要 Ed25519 私钥（64 字符十六进制）

设置步骤：

# 生成 Ed25519 密钥对
openssl genpkey -algorithm Ed25519 -out key.pem
# 获取用于 DNS 记录的公钥
openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64
# 添加 DNS TXT 记录：
example.com. IN TXT "v=MCPv1; k=ed25519; p=PUBLIC_KEY"
# 提取用于登录的私钥
openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n'

HTTP 验证 

mcp-publisher login http --domain=example.com --private-key=HEX_KEY [--registry=URL]
  • 通过 HTTPS 端点验证域名所有权
  • 授予对 com.example.* 命名空间的访问权限
  • 需要 Ed25519 私钥（64 字符十六进制）

设置：

# 生成密钥对（与 DNS 相同）
openssl genpkey -algorithm Ed25519 -out key.pem

# 在以下位置托管公钥：
# https://example.com/.well-known/mcp-registry-auth
# 内容：v=MCPv1; k=ed25519; p=PUBLIC_KEY

匿名（测试） 

mcp-publisher login none [--registry=URL]
  • 无身份验证 - 仅用于本地测试
  • 仅适用于本地 Registry 实例

mcp-publisher publish

将服务器发布到 Registry。

用法：

mcp-publisher publish [options]

选项：

  • --file=PATH - server.json 路径（默认：./server.json）
  • --registry=URL - Registry URL 覆盖
  • --dry-run - 验证而不发布

处理流程：

  1. 根据 schema 验证 server.json
  2. 验证包所有权（参见 官方 Registry 要求）
  3. 检查命名空间身份验证
  4. 发布到 Registry

示例：

# 基本发布
mcp-publisher publish

# 试运行验证
mcp-publisher publish --dry-run

# 自定义文件位置
mcp-publisher publish --file=./config/server.json

mcp-publisher logout

清除存储的身份验证凭据。

用法：

mcp-publisher logout

行为：

  • 删除 ~/.mcp_publisher_token
  • 不会在服务器端撤销令牌

配置

令牌存储

身份验证令牌以 JSON 格式存储在 ~/.mcp_publisher_token 中：

{
  "token": "jwt-token-here",
  "registry_url": "https://registry.modelcontextprotocol.io",
  "expires_at": "2024-12-31T23:59:59Z"
}

命名空间和安全性

命名空间格式

所有服务器名称遵循反向 DNS 格式：

  • io.github.alice/weather-server - GitHub 用户 alice
  • com.acme/internal-tool - 公司域名 acme.com
  • org.nonprofit.research/data-analyzer - 子域名 research.nonprofit.org

所有权验证

发布到命名空间需要证明您控制相应的身份：

GitHub 命名空间 (io.github.*):

  • 对 GitHub 账户/组织进行 OAuth 登录
  • GitHub Actions 工作流中的 OIDC 令牌

域名命名空间 (com.company.*):

  • DNS 验证：在 company.com 的 TXT 记录
  • HTTP 验证：在 https://company.com/.well-known/mcp-registry-auth 的文件

命名空间作用域

不同的身份验证方法授予不同的命名空间访问权限：

GitHub OAuth/OIDC:

  • io.github.username/*（个人账户）
  • io.github.orgname/*（组织）

DNS 验证:

  • com.domain/* 和 com.domain.*/*（域名 + 所有子域名）

HTTP 验证:

  • com.domain/* 仅（确切域名，无子域名）

版本控制最佳实践

语义版本控制

服务器作者应该使用 语义版本，遵循 MAJOR.MINOR.PATCH 格式：

{
  "version": "1.2.3"
}

与包版本对齐

服务器作者应该使用与其底层包对齐的版本以减少混乱：

{
  "version": "1.2.3",
  "packages": [{
    "registry_type": "npm",
    "identifier": "@myorg/my-server",
    "version": "1.2.3"
  }]
}

多个 Registry 版本

如果需要为同一包版本发布多个 Registry 版本，应该使用预发布标签：

{
  "version": "1.2.3-1",
  "packages": [{
    "registry_type": "npm", 
    "identifier": "@myorg/my-server",
    "version": "1.2.3"
  }]
}

常见用例

基本工作流 

# 1. 初始化 server.json
mcp-publisher init

# 2. 编辑生成的 server.json

# 3. 身份验证
mcp-publisher login github

# 4. 发布
mcp-publisher publish

CI/CD 工作流 

# 在 GitHub Actions 中
mcp-publisher login github-oidc
mcp-publisher publish

版本更新 

# 更新 server.json 中的版本
# 然后重新发布
mcp-publisher publish

故障排除

“Authentication failed”（身份验证失败）

  • 对于 OIDC，确保设置了 id-token: write 权限
  • 检查密钥或令牌

“Package validation failed”（包验证失败）

  • 验证您的包已成功发布到包注册中心（NPM、PyPI 等）
  • 确保您已完成必要的验证步骤

“Namespace not authorized”（命名空间未授权）

  • 您的身份验证方法与选择的命名空间格式不匹配

“Version already exists”（版本已存在）

  • 每个服务器名称的版本必须唯一
  • 使用新版本号或预发布标签

下一步

学习完整的服务器发布流程 设置自动化发布工作流 深入了解 server.json 格式 查看完整的 API 文档
专业提示: 使用 --dry-run 选项在实际发布之前验证您的 server.json 配置。