HelloAgents 实战Weather MCP Server 发布 Smithery 的完整检查清单与全流程指南【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents导读本文围绕weather-mcp-server这一基于 HelloAgents 框架开发的真实天气查询 MCP Server系统讲解将其发布到 Smithery 平台MCP Server 的官方发布平台类似 Python 生态的 PyPI前必须完成的全部检查项与提交流程。你将掌握七类发布文件的验收标准、pyproject.toml与smithery.yaml的版本一致性校验方法、GitHub 标签与 Release 的准备步骤以及发布成功后通过 Smithery CLI、Claude Desktop 和 HelloAgentsMCPTool三种方式接入该服务的完整方案。一、为什么需要一份发布检查清单在第十章 智能体通信协议中我们已经通过hello_agents.protocols.MCPServer构建了一个可提供真实天气数据查询能力的 MCP Server项目位于 code/chapter10/weather-mcp-server/。但能本地运行与能稳定交付给全球开发者使用之间还有一段距离Smithery 会拉取你的仓库、读取配置、构建镜像、启动服务并对外提供访问地址任何一环配置错误都可能导致审核失败或运行时故障。因此仓库中的 PUBLISH_CHECKLIST.md 以清单形式梳理了发布前的全部验收项本文将该清单逐条展开并结合 server.py、pyproject.toml、smithery.yaml、Dockerfile 等真实文件说明每一项为什么重要、如何检查、怎样算达标。二、文件检查七个必备文件的验收标准发布前项目目录应当整理为标准发布结构。以本仓库为例weather-mcp-server/ ├── README.md # 项目文档要求完整清晰 ├── LICENSE # 开源许可证要求存在 ├── Dockerfile # Docker 构建配置推荐提供 ├── pyproject.toml # Python 项目配置Smithery 必需 ├── requirements.txt # Python 依赖清单 ├── smithery.yaml # Smithery 平台配置必需 └── server.py # MCP 服务器主文件1. README.md完整且清晰README.md 是开发者了解该 Server 的第一入口必须包含功能特性说明实时天气查询、支持 12 个中国主要城市、基于 wttr.in API 无需密钥、基于 HelloAgents 框架、安装命令、直接运行方法与 Claude Desktop / HelloAgents 两种集成示例、全部 API 工具的参数与返回示例、支持的城市列表以及许可证信息。发布后 Smithery 页面会直接展示该文档内容质量直接影响使用者的采纳意愿。2. LICENSE必须存在仓库提供了 LICENSEMIT 协议。Smithery 与多数开源分发平台都会检查许可证文件缺少 LICENSE 会降低项目可信度甚至被平台拒绝收录。注意pyproject.toml中的license {text MIT}与smithery.yaml中的license: MIT应与实际 LICENSE 文件保持一致。3. Dockerfile配置正确推荐虽然 Smithery 会自动生成 Dockerfile但提供自定义 Dockerfile 能确保部署成功。本项目的 Dockerfile 采用多阶段构建FROM python:3.12-slim-bookworm as base WORKDIR /app COPY pyproject.toml requirements.txt ./ COPY server.py ./ RUN pip install --no-cache-dir --upgrade pip \ pip install --no-cache-dir -r requirements.txt ENV PYTHONUNBUFFERED1 ENV PORT8081 EXPOSE 8081 HEALTHCHECK --interval30s --timeout3s --start-period5s --retries3 \ CMD python -c import sys; sys.exit(0) CMD [python, server.py]要点解读基础镜像python:3.12-slim-bookworm为轻量级 Python 镜像减小构建体积与启动时间端口ENV PORT8081与EXPOSE 8081声明 Smithery 平台标准端口而 server.py 通过os.getenv(PORT, 8081)读取该环境变量——Dockerfile 与代码中的端口约定必须对齐健康检查HEALTHCHECK每 30 秒探测一次容器存活状态帮助平台判断服务是否就绪启动命令CMD [python, server.py]与本地运行方式完全一致。4. pyproject.toml配置正确必需pyproject.toml 是 Python 项目标准配置Smithery 要求提供该文件因为它将用于后续的服务打包。检查重点name weather-mcp-server项目名称应全小写、以连字符分隔version 1.0.0版本号遵循语义化版本requires-python 3.10明确 Python 版本要求dependencies完整声明依赖hello-agents0.2.2、requests2.31.0否则容器内将因缺少依赖而无法启动[tool.setuptools] py-modules [server]指定将server.py作为打包模块。5. requirements.txt包含所有依赖requirements.txt 内容为hello-agents0.2.2 requests2.31.0它与pyproject.toml的dependencies保持一致Dockerfile 构建阶段即通过pip install -r requirements.txt安装。两份清单若出现不一致可能出现本地能跑、容器内报 ModuleNotFoundError的典型事故。6. smithery.yaml配置正确必需smithery.yaml 是 Smithery 平台的专属配置name: weather-mcp-server displayName: Weather MCP Server description: Real-time weather query MCP server based on HelloAgents framework version: 1.0.0 author: HelloAgents Team homepage: https://github.com/yourusername/weather-mcp-server license: MIT categories: - weather - data tags: - weather - real-time - helloagents - wttr runtime: container build: dockerfile: Dockerfile dockerBuildPath: . startCommand: type: http tools: - name: get_weather description: Get current weather for a city - name: list_supported_cities description: List all supported cities - name: get_server_info description: Get server information7. server.py可以正常运行server.py 是服务核心。它基于from hello_agents.protocols import MCPServer创建服务器实例weather_server MCPServer(nameweather-server, description真实天气查询服务)定义三个工具函数后通过weather_server.add_tool(...)注册server.py最后以 HTTP transport 启动weather_server.run(transporthttp, hosthost, portport)。注意 Smithery 要求 HTTP 传输方式因此本地测试也要确保能以python server.py直接拉起服务。三、功能测试上线前的最后一公里清单要求发布前完成四项功能验证服务器可以正常启动本地执行python server.py观察终端输出 Transport: HTTP、 Endpoint: http://0.0.0.0:8081/mcp等日志确认进程稳定驻留所有工具都能正常调用逐一调用get_weather、list_supported_cities、get_server_info确认返回结果符合预期错误处理完善server.py 中get_weather通过try/except捕获异常并返回{error: ..., city: ...}JSON而非让进程崩溃get_weather_data对 wttr.in 请求设置了timeout10并调用response.raise_for_status()网络异常时能给出明确错误返回结果格式正确所有工具函数均返回json.dumps(..., ensure_asciiFalse, indent2)格式化的 JSON 字符串保证中文可读、结构稳定。若使用 MCP Client 侧验证可参考 02_Connect2MCP.py 中的MCPClient用法await client.list_tools()发现工具、await client.call_tool(get_weather, {city: 北京})调用工具以此端到端确认协议互通。四、配置检查版本一致性、唯一性与元数据这是最容易踩坑的一环Smithery 平台会读取pyproject.toml与smithery.yaml两份元数据pyproject.toml的name与version正确本项目为weather-mcp-server/1.0.0smithery.yaml的name全局唯一Smithery 上不允许重名发布前可在平台搜索确认两份文件的version保持一致pyproject.toml与smithery.yaml中版本号不一致会导致构建或展示异常version遵循语义化版本采用主版本.次版本.修订号如1.0.0破坏性变更递增主版本新增功能递增次版本修复递增修订号tools列表完整smithery.yaml中声明的三个工具get_weather、list_supported_cities、get_server_info必须与 server.py 中add_tool注册的工具一一对应漏报会导致平台展示的工具与真实能力不符homepageURL 正确指向你自己的仓库地址示例中的yourusername需替换为真实 GitHub 用户名。五、文档检查与最终检查安装说明清晰README 中给出pip install hello-agents requests与python server.py两条最简路径使用示例完整包含 Claude Desktop 配置 JSONmacOS 的~/Library/Application Support/Claude/claude_desktop_config.json或 Windows 的%APPDATA%\Claude\claude_desktop_config.json与 HelloAgents 接入代码API 文档详细README 对get_weather的入参city支持中英文与返回字段temperature、feels_like、humidity、condition、wind_speed、visibility、timestamp逐一给出示例支持的功能列表完整明确列出 12 个支持的中文城市并说明也支持英文城市名查询全球任意城市。最终检查阶段应回归三项本地全流程测试通过、文档无拼写错误、所有仓库内链接可访问例如pyproject.toml中readme README.md指向的文件必须真实存在。六、GitHub 准备推送、标签与 Release发布前的代码托管环节有四项硬性要求代码已推送到 GitHub将整理好的weather-mcp-server项目推送到自己的公开仓库本地Fork参考的hello-agents源码位于本仓库 code/chapter10/weather-mcp-server/创建v1.0.0标签标签命名与版本号对应例如git tag v1.0.0创建 Release在 GitHub Releases 页面基于该标签创建发布说明描述功能特性与变更内容仓库设为 PublicSmithery 需要拉取公开仓库才能完成构建与索引。七、提交步骤从提交到审核按以下顺序操作完整步骤说明见第十章文档的 10.5.2 节在浏览器中访问 Smithery 官方网站使用 GitHub 账号登录授权平台读取你的公开仓库信息点击页面上的 Submit Server / Publish Server 按钮输入仓库 URLhttps://github.com/yourusername/weather-mcp-serveryourusername替换为你的 GitHub 用户名确认展示的项目信息与配置无误后提交等待审核通常 13 天。八、审核通过后的验证与三种使用方式收到审核通过邮件后依次确认在 Smithery 上可以搜索到该服务、测试安装与使用、再分享给社区。发布成功后用户有三种接入方式方式一Smithery CLI# 安装 Smithery CLI npm install -g smithery/cli # 安装你的 server smithery install weather-mcp-server方式二配置到 Claude Desktop{ mcpServers: { weather: { command: smithery, args: [run, weather-mcp-server] } } }方式三在 HelloAgents 中使用from hello_agents import SimpleAgent, HelloAgentsLLM from hello_agents.tools.builtin.protocol_tools import MCPTool agent SimpleAgent(nameWeather Assistant, llmHelloAgentsLLM()) # 使用 Smithery 安装的 server weather_tool MCPTool( server_command[smithery, run, weather-mcp-server] ) agent.add_tool(weather_tool) response agent.run(北京今天天气怎么样)发布成功后Smithery 页面会展示服务的唯一标识形如用户名/weather-mcp-server、状态信息、已发布的 Tools 列表以及 Connect 区域的服务访问 URL 地址和多语言/多环境的配置代码片段供全球开发者直接复制接入。九、总结一张可复用的发布自检表将清单浓缩为一条可复用的发布主路径文件完备7 个文件→ 功能自测启动/工具/异常/格式→ 元数据对齐name 唯一、version 一致、tools 对应→ GitHub 就绪推送/标签/Release/Public→ 提交等待审核13 天→ 发布后验证搜索/安装/使用。这套流程不仅适用于weather-mcp-server也可作为任何基于 HelloAgents 框架开发的 MCP Server 发布到 Smithery 的标准模板——对照 PUBLISH_CHECKLIST.md 逐项打勾即可最大程度避免发布失败与线上事故。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考