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": "一個與示例服務整合的 MCP 伺服器（替換為清晰的一句話描述）。",
  "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”（版本已存在）

  • 每個服務器名稱的版本必須唯一
  • 使用新版本號或預發佈標籤

下一步

發佈指南
學習完整的服務器發佈流程
GitHub Actions
設置自動化發佈工作流
server.json 規範
深入瞭解 server.json 格式
Registry API
查看完整的 API 文檔
專業提示: 使用 --dry-run 選項在實際發佈之前驗證您的 server.json 配置。