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

【MCP 全栈教程】第 23 篇将你的 Server 发布到 MCP Registry本系列定位从协议原理到 Server 开发、Client 开发、再到各大平台实战集成系统化掌握 MCPModel Context Protocol全栈技术体系。本篇你将学到server.json清单文件的完整格式与字段含义namespace 命名规范reverse DNS 格式GitHub Actions 自动发布流程语义化版本管理策略Package Typesnpm / PyPI / Docker配置Registry 审核流程与最佳实践学完本篇你将能将自己的 MCP Server 发布到 Registry让全球开发者搜索、安装和使用。一、MCP Registry 是什么MCP Registry 是 MCP Server 的集中式注册中心类似于 npm registry 或 PyPI。开发者将自己的 Server 发布到 Registry 后其他用户可以通过统一的命令搜索和安装。Registry 的价值角色价值Server 作者让作品被发现、被使用、建立声誉Server 用户一键搜索安装无需手动配置Host 应用自动发现可用 Server简化集成生态标准化分发渠道促进生态繁荣Registry 核心功能功能说明注册Server 作者提交 Server 元信息搜索按名称、描述、标签搜索 Server安装自动安装到 Host 应用的配置中版本管理追踪版本历史支持升级回滚评分反馈用户评价和反馈二、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:devtravelassistant.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}}字段详解字段类型必填说明idstring是唯一标识reverse DNS 格式namestring是Server 名称展示用descriptionstring是简短描述建议 100 字以内versionstring是语义化版本号authorobject否作者信息homepagestring否项目主页repositoryobject否代码仓库licensestring是开源许可证categoriesarray否分类标签keywordsarray否搜索关键词capabilitiesobject是能力声明同 discover 响应toolsarray否工具列表预览packagesarray是分发包信息runtimeobject是运行时配置requirementsobject否运行环境要求三、namespace 命名规范Reverse DNS 格式Server 的id字段使用 reverse DNS反向域名格式确保全局唯一性io.github.{用户名}/{server名}格式示例说明GitHub 托管io.github.alice/weather-server最常见组织域名com.company.team/server-name企业项目个人域名io.personal/my-tool个人项目命名规则规则说明示例全小写ID 全部小写io.github.alice/weather-server✓短横线分词多词用短横线weather-server✓唯一用户名使用你的实际用户名不要冒用他人语义化名称名称反映功能db-query✓tool1✗常见错误// ❌ 错误没有 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 类型registryType平台适用语言安装命令pypiPyPIPythonpip install weather-mcp-servernpmnpmTypeScript/JavaScriptnpm install weather-mcp-serverdockerDocker Hub通用docker pull weather-serverPythonPyPI包配置{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命令。TypeScriptnpm包配置{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}}}}多包分发对比维度PyPInpmDocker目标用户Python 开发者JS/TS 开发者所有用户安装速度快快首次较慢环境隔离依赖虚拟环境依赖 node_modules完全隔离推荐场景Python 生态项目前端/全栈项目生产部署建议至少发布一个包管理器版本PyPI 或 npm。如果 Server 依赖复杂系统库、数据库额外提供 Docker 版本。五、版本管理策略语义化版本SemVer版本号格式MAJOR.MINOR.PATCH版本变更触发条件示例MAJOR (x.0.0)不兼容的 API 变更工具名改变、参数结构变化MINOR (1.x.0)向后兼容的新功能新增工具、新增可选参数PATCH (1.0.x)向后兼容的修复Bug 修复、性能优化版本变更决策变更类型版本升级理由新增工具MINOR新功能不影响现有调用删除工具MAJOR已有调用会失败工具改名MAJOR破坏性变更新增可选参数MINOR兼容老调用仍有效新增必填参数MAJOR老调用会缺少参数修改返回格式MAJORClient 可能依赖返回结构修复 BugPATCH行为更正确接口不变性能优化PATCH无接口变化预发布版本格式含义示例1.0.0-alpha.1早期内测功能不完整1.0.0-beta.1公测功能完整可能有 Bug1.0.0-rc.1发布候选基本确定最后验证六、GitHub Actions 自动发布Python Server 发布流程在仓库.github/workflows/publish.yml中配置name:Publish MCP Serveron:push:tags:-v*jobs:publish-pypi:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-name:Setup Pythonuses:actions/setup-pythonv5with: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/checkoutv4-name:Publish to MCP Registryuses:modelcontextprotocol/publish-actionv1with: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/checkoutv4-name:Setup Node.jsuses:actions/setup-nodev4with:node-version:20registry-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/checkoutv4-name:Publish to MCP Registryuses:modelcontextprotocol/publish-actionv1with:server-json:./server.jsonregistry-token:${{secrets.MCP_REGISTRY_TOKEN}}Docker 发布流程publish-docker:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-name:Setup Docker Buildxuses:docker/setup-buildx-actionv3-name:Login to Docker Hubuses:docker/login-actionv3with: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-actionv5with: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. 审核通过后上线密钥用途配置位置PYPI_TOKENPyPI 发布令牌GitHub SecretsNPM_TOKENnpm 发布令牌GitHub SecretsDOCKER_TOKENDocker Hub 令牌GitHub SecretsMCP_REGISTRY_TOKENMCP Registry 发布令牌GitHub Secrets七、Registry 审核流程审核阶段阶段检查内容自动/人工格式校验server.json 格式正确自动命名检查namespace 合规、无冲突自动安全扫描依赖漏洞扫描、代码静态分析自动包验证发布的包可正常安装和运行自动内容审核描述准确、无恶意行为人工重复检查与现有 Server 不高度重复人工审核结果结果说明后续操作通过满足所有要求自动上线需修改有小问题通知作者修改后重新提交拒绝严重问题或违规通知原因修复后重新申请提升审核通过率的建议建议说明描述清晰准确description 真实反映功能命名规范遵守 reverse DNS 格式版本合理不跳版本号遵循 SemVer测试充分发布前完整测试文档完善README 包含使用说明无安全风险通过依赖扫描不重复发布搜索确认没有同类 Server八、维护与迭代发布后的维护清单维护项频率说明修复 Bug及时用户反馈的问题更新依赖定期安全补丁版本升级按需新功能迭代回复反馈及时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}九、完整发布检查清单检查项说明server.json 格式正确通过 schema 校验id 符合 reverse DNSio.github.{用户名}/{server名}版本号语义化遵循 MAJOR.MINOR.PATCHpackages 配置完整至少一个包管理器runtime 配置可运行command args 正确capabilities 声明准确与实际实现一致描述和关键词完善便于搜索发现已通过本地测试MCP Inspector 自动化测试CI/CD 配置就绪GitHub Actions 可自动发布密钥已配置PyPI/npm/Docker/Registry 令牌README 完整安装和使用说明本篇小结知识点核心内容MCP RegistryServer 的集中注册中心类似 npm/PyPIserver.jsonServer 清单文件描述身份、功能、安装方式namespaceReverse DNS 格式io.github.{用户名}/{server名}Package TypesPyPIPython、npmTS、Docker通用版本管理SemVerMAJOR破坏性/ MINOR新功能/ PATCH修复自动发布Git tag 触发 GitHub Actions自动构建发布注册审核流程格式校验 → 安全扫描 → 包验证 → 内容审核维护及时修复、更新依赖、处理废弃下篇预告第 24 篇MCP Client 架构——Host 应用如何管理多个 Server 连接进入模块四Client 开发实战。深入 Host 应用的架构设计——多 Client 管理、连接池、健康检查、工具命名空间隔离。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。