第23篇-将你的Server发布到MCP-Registry

【MCP 全栈教程】第 23 篇：将你的 Server 发布到 MCP Registry

本系列定位：从协议原理到 Server 开发、Client 开发、再到各大平台实战集成，系统化掌握 MCP（Model Context Protocol）全栈技术体系。

本篇你将学到

• server.json清单文件的完整格式与字段含义
• namespace 命名规范（reverse DNS 格式）
• GitHub Actions 自动发布流程
• 语义化版本管理策略
• Package Types（npm / PyPI / Docker）配置
• Registry 审核流程与最佳实践

学完本篇，你将能将自己的 MCP Server 发布到 Registry，让全球开发者搜索、安装和使用。

一、MCP Registry 是什么

MCP Registry 是 MCP Server 的集中式注册中心，类似于 npm registry 或 PyPI。开发者将自己的 Server 发布到 Registry 后，其他用户可以通过统一的命令搜索和安装。

Registry 的价值

Registry 核心功能

二、server.json 格式详解

每个发布的 MCP Server 必须包含一个server.json清单文件，描述 Server 的身份、功能和安装方式。

完整示例

{"$schema":"https://cdn.jsdelivr.net/npm/@modelcontextprotocol/sdk/schema/server.json","id":"io.github.travelassistant/weather-server","name":"weather-server","description":"查询全球城市天气和未来 7 天预报，支持中文城市名。","version":"1.2.0","author":{"name":"TravelAssistant Team","email":"dev@travelassistant.io"},"homepage":"https://weather-server.travelassistant.io","repository":{"type":"git","url":"https://example.com/weather-server"},"license":"MIT","categories":["weather","travel","utilities"],"keywords":["weather","forecast","temperature","天气","天气预报"],"capabilities":{"tools":{"listChanged":true},"resources":{},"prompts":{}},"tools":[{"name":"get_weather","description":"查询指定城市的当前天气"},{"name":"get_forecast","description":"获取未来 7 天天气预报"}],"packages":[{"registryType":"pypi","identifier":"weather-mcp-server","version":"1.2.0"},{"registryType":"npm","identifier":"@travelassistant/weather-mcp-server","version":"1.2.0"},{"registryType":"docker","identifier":"travelassistant/weather-server","version":"1.2.0"}],"runtime":{"command":"weather-server","args":[],"env":{"API_KEY":"${WEATHER_API_KEY}"}},"requirements":{"python":">=3.10","node":">=18"}}

字段详解

三、namespace 命名规范

Reverse DNS 格式

Server 的id字段使用 reverse DNS（反向域名）格式，确保全局唯一性：

io.github.{用户名}/{server名}

命名规则

常见错误

// ❌ 错误：没有 namespace 前缀"id":"weather-server"// ❌ 错误：用驼峰命名"id":"io.github.Alice/WeatherServer"// ❌ 错误：用下划线"id":"io.github.alice/weather_server"// ✅ 正确"id":"io.github.alice/weather-server"

四、Package Types 配置

packages数组定义 Server 的分发方式。一个 Server 可以同时发布到多个包管理器。

支持的 Registry 类型

Python（PyPI）包配置

{"registryType":"pypi","identifier":"weather-mcp-server","version":"1.2.0","runtime":{"command":"weather-server","args":[],"env":{"API_KEY":"${WEATHER_API_KEY}"}}}

对应pyproject.toml：

[project] name = "weather-mcp-server" version = "1.2.0" description = "查询全球城市天气的 MCP Server" [project.scripts] weather-server = "weather_mcp.server:main" [build-system] requires = ["hatchling"] build-backend = "hatchling.build"

[project.scripts]定义了命令行入口——安装后用户可以直接运行weather-server命令。

TypeScript（npm）包配置

{"registryType":"npm","identifier":"@travelassistant/weather-mcp-server","version":"1.2.0","runtime":{"command":"npx","args":["-y","@travelassistant/weather-mcp-server"],"env":{"API_KEY":"${WEATHER_API_KEY}"}}}

对应package.json：

{"name":"@travelassistant/weather-mcp-server","version":"1.2.0","type":"module","bin":{"weather-mcp-server":"dist/index.js"},"files":["dist"],"scripts":{"build":"tsc","prepublishOnly":"npm run build"}}

bin字段定义了可执行命令，files指定发布时包含的文件。

Docker 包配置

{"registryType":"docker","identifier":"travelassistant/weather-server","version":"1.2.0","runtime":{"command":"docker","args":["run","--rm","-i","-e","API_KEY","travelassistant/weather-server:1.2.0"],"env":{"API_KEY":"${WEATHER_API_KEY}"}}}

多包分发对比

建议：至少发布一个包管理器版本（PyPI 或 npm）。如果 Server 依赖复杂（系统库、数据库），额外提供 Docker 版本。

五、版本管理策略

语义化版本（SemVer）

版本号格式：MAJOR.MINOR.PATCH

版本变更决策

预发布版本

六、GitHub Actions 自动发布

Python Server 发布流程

在仓库.github/workflows/publish.yml中配置：

name:Publish MCP Serveron:push:tags:-"v*"jobs:publish-pypi:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-name:Setup Pythonuses:actions/setup-python@v5with:python-version:"3.12"-name:Install uvrun:pip install uv-name:Build packagerun:uv build-name:Publish to PyPIrun:uv publishenv:UV_PUBLISH_TOKEN:${{secrets.PYPI_TOKEN}}publish-registry:needs:publish-pypiruns-on:ubuntu-lateststeps:-uses:actions/checkout@v4-name:Publish to MCP Registryuses:modelcontextprotocol/publish-action@v1with:server-json:./server.jsonregistry-token:${{secrets.MCP_REGISTRY_TOKEN}}

TypeScript Server 发布流程

name:Publish MCP Serveron:push:tags:-"v*"jobs:publish-npm:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-name:Setup Node.jsuses:actions/setup-node@v4with:node-version:"20"registry-url:"https://registry.npmjs.org"-name:Install dependenciesrun:npm ci-name:Buildrun:npm run build-name:Publish to npmrun:npm publish--access publicenv:NODE_AUTH_TOKEN:${{secrets.NPM_TOKEN}}publish-registry:needs:publish-npmruns-on:ubuntu-lateststeps:-uses:actions/checkout@v4-name:Publish to MCP Registryuses:modelcontextprotocol/publish-action@v1with:server-json:./server.jsonregistry-token:${{secrets.MCP_REGISTRY_TOKEN}}

Docker 发布流程

publish-docker:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-name:Setup Docker Buildxuses:docker/setup-buildx-action@v3-name:Login to Docker Hubuses:docker/login-action@v3with:username:${{secrets.DOCKER_USERNAME}}password:${{secrets.DOCKER_TOKEN}}-name:Extract versionid:versionrun:echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT-name:Build and pushuses:docker/build-push-action@v5with:context:.push:truetags:|travelassistant/weather-server:latest travelassistant/weather-server:${{ steps.version.outputs.VERSION }}

发布流程总结

1. 更新代码和 server.json 中的版本号 2. 提交代码 3. 创建 Git 标签：git tag v1.2.0 4. 推送标签：git push origin v1.2.0 5. GitHub Actions 自动触发： a. 构建包 b. 发布到 PyPI / npm / Docker Hub c. 提交 server.json 到 MCP Registry 6. Registry 审核（自动化 + 人工） 7. 审核通过后上线

七、Registry 审核流程

审核阶段

审核结果

提升审核通过率的建议

八、维护与迭代

发布后的维护清单

废弃处理

如果 Server 不再维护，应正式标记废弃：

{"id":"io.github.alice/old-server","version":"1.5.0","deprecated":true,"deprecationMessage":"此 Server 已停止维护，请使用 io.github.alice/new-server 替代。","successor":"io.github.alice/new-server"}

九、完整发布检查清单

本篇小结

下篇预告

第 24 篇：MCP Client 架构——Host 应用如何管理多个 Server 连接
进入模块四"Client 开发实战"。深入 Host 应用的架构设计——多 Client 管理、连接池、健康检查、工具命名空间隔离。

如果本篇内容对你有帮助，欢迎点赞收藏！有任何疑问，欢迎在评论区交流。