基于 HelloAgents 框架构建真实天气查询 MCP 服务器从源码实现到 Claude Desktop 与 Smithery 发布全指南【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents本文以仓库中code/chapter10/weather-mcp-server/目录下开源的 Weather MCP Server 为对象完整拆解一个真实天气查询 MCP 服务器的设计与实现它基于 HelloAgents 框架的MCPServer抽象通过无需密钥的 wttr.in 公共 API 提供 12 个中国主要城市的实时天气查询能力并支持在 Claude Desktop、HelloAgents Agent 以及容器化云端环境Smithery中运行。读完本文你将掌握 MCP 工具服务器从写一个普通 Python 函数到注册为 Agent 可调用工具再到容器化发布的完整链路可直接复刻同款方案构建自己的 MCP 服务。1. 项目概览一个零密钥、零配置的天气工具服务器Weather MCP Server 是一个真实天气查询 MCPModel Context Protocol服务器位于 code/chapter10/weather-mcp-server属于《从零开始构建智能体》一书第十章 智能体通信协议的配套实战代码。其核心特性如下️ 实时天气查询调用外部天气数据源获取当前天气 支持 12 个中国主要城市北京、上海、广州、深圳、杭州、成都、重庆、武汉、西安、南京、天津、苏州 使用 wttr.in API无需申请 API Key无需付费 基于 HelloAgents 框架的MCPServer组件开发。整个服务端只有一个核心文件 server.py约 90 行外加pyproject.toml、requirements.txt、Dockerfile、smithery.yaml等工程化配套文件是一个小而完整的 MCP 服务范本。1.1 为什么选择 wttr.in从 server.py 的get_weather_data函数可以看到服务端直接请求https://wttr.in/{city_en}?formatj1j1表示以 JSON 格式返回完整天气数据。wttr.in 是一个面向命令行与脚本的免费天气服务无需注册与密钥因此该服务器天然具备零配置开箱即用的特性——这正是一个合格演示项目所追求的极低使用门槛。2. 环境准备与安装2.1 依赖清单根据 requirements.txt 与 pyproject.toml项目依赖非常简单hello-agents0.2.2提供MCPServer服务端抽象与MCPClient客户端抽象requests2.31.0用于向 wttr.in 发起 HTTP 请求。同时pyproject.toml中声明了 Python 版本要求requires-python 3.10即需要 Python 3.10 及以上版本项目 Dockerfile 则使用 Python 3.12-slim 作为运行镜像。2.2 安装命令在项目目录下执行pip install hello-agents requests若使用项目的pyproject.toml管理依赖也可以直接pip install -e .3. 源码深度解析90 行代码如何成为一个 MCP 服务器要理解这个项目关键在于看懂 server.py 的四个部分服务实例创建、城市映射、天气数据获取、工具注册与启动。3.1 创建 MCP 服务器实例from hello_agents.protocols import MCPServer weather_server MCPServer(nameweather-server, description真实天气查询服务)MCPServer是 HelloAgents 框架提供的服务端抽象位于hello_agents.protocols模块它会自动处理 MCP 协议层的握手、工具列表暴露tools/list与工具调用分发tools/call开发者只需关注业务逻辑本身。3.2 中文城市名 → 英文城市名映射CITY_MAP { 北京: Beijing, 上海: Shanghai, 广州: Guangzhou, 深圳: Shenzhen, 杭州: Hangzhou, 成都: Chengdu, 重庆: Chongqing, 武汉: Wuhan, 西安: Xian, 南京: Nanjing, 天津: Tianjin, 苏州: Suzhou }该映射表解决了中文城市名查询的需求wttr.in 接受英文城市名而中文用户在对话中更习惯说中文城市名。映射逻辑在get_weather_data中体现city_en CITY_MAP.get(city, city)即若传入的城市在映射表中则转换为英文名若不在例如用户输入英文城市名或全球任意城市则原样透传给 wttr.in。这就是 README 中也支持使用英文城市名查询全球任意城市的源码依据。3.3 天气数据获取与字段加工def get_weather_data(city: str) - Dict[str, Any]: city_en CITY_MAP.get(city, city) url fhttps://wttr.in/{city_en}?formatj1 response requests.get(url, timeout10) response.raise_for_status() data response.json() current data[current_condition][0] ...关键实现细节超时控制timeout10防止网络异常导致服务挂起错误抛出raise_for_status()在 HTTP 非 2xx 时抛出异常交由上层捕获处理字段加工wttr.in 返回的风速单位为 km/h源码中通过round(float(current[windspeedKmph]) / 3.6, 1)换算为 m/s 并保留一位小数时间戳使用datetime.now().strftime(%Y-%m-%d %H:%M:%S)生成本地时间戳。最终返回的字段包括city、temperature、feels_like、humidity、condition、wind_speed、visibility、timestamp与 README 中的返回示例一一对应。3.4 工具定义与注册函数即工具MCP 服务器中的每个工具就是一个普通 Python 函数。项目定义了三个工具函数def get_weather(city: str) - str: 获取指定城市的当前天气 try: weather_data get_weather_data(city) return json.dumps(weather_data, ensure_asciiFalse, indent2) except Exception as e: return json.dumps({error: str(e), city: city}, ensure_asciiFalse) def list_supported_cities() - str: 列出所有支持的中文城市 result {cities: list(CITY_MAP.keys()), count: len(CITY_MAP)} return json.dumps(result, ensure_asciiFalse, indent2) def get_server_info() - str: 获取服务器信息 info { name: Weather MCP Server, version: 1.0.0, tools: [get_weather, list_supported_cities, get_server_info] } return json.dumps(info, ensure_asciiFalse, indent2) # 注册工具到服务器 weather_server.add_tool(get_weather) weather_server.add_tool(list_supported_cities) weather_server.add_tool(get_server_info)值得注意的两个设计函数返回值统一为 JSON 字符串ensure_asciiFalse保证中文正常显示这是为了让工具结果能够被 LLM 直接解析为结构化文本get_weather内置了 try/except 错误处理当网络异常或城市无法解析时返回包含error字段的 JSON 而非直接抛错避免 MCP 调用链路中断。3.5 服务启动stdio 与 HTTP 两种传输方式仓库中实际上存在两个版本的天气 MCP 服务器weather-mcp-server/server.py发布版默认以HTTP 传输启动通过环境变量PORT默认 8081与HOST默认0.0.0.0控制监听地址并在启动时打印传输类型、Host、Port 与端点http://{host}:{port}/mcpif __name__ __main__: port int(os.getenv(PORT, 8081)) host os.getenv(HOST, 0.0.0.0) ... weather_server.run(transporthttp, hosthost, portport)14_weather_mcp_server.py章节教学版使用默认的stdio标准输入输出传输即weather_server.run()用于本地进程间通信如 Claude Desktop 与 HelloAgents Agent 的子进程调用。两者业务逻辑完全一致区别仅在于 MCP 的传输层。这正好呼应了 MCP 协议中同一份工具定义可以适配多种传输方式的设计思想——stdio 适合桌面端本地进程HTTP 适合云端容器部署这也是 Smithery 平台要求 HTTP transport 的原因见源码注释 Smithery requires HTTP transport on PORT environment variable。4. API 工具详解以下三个工具即为该 MCP 服务器对外暴露的全部能力来自 README 的 API 章节并结合源码参数补充说明。4.1 get_weather —— 获取指定城市当前天气参数参数类型说明citystring城市名称支持中文和英文请求示例{ city: 北京 }返回示例{ city: 北京, temperature: 10.0, feels_like: 9.0, humidity: 94, condition: Light rain, wind_speed: 1.7, visibility: 10.0, timestamp: 2025-10-09 13:25:03 }其中wind_speed单位为 m/s由 wttr.in 的 km/h 换算而来condition为英文天气描述wttr.in 原始返回。当查询失败时返回形如{error: 异常信息, city: 北京}的错误 JSON。4.2 list_supported_cities —— 列出所有支持的中文城市无参数返回支持的中文城市列表及其数量{ cities: [北京, 上海, 广州, 深圳, 杭州, 成都, 重庆, 武汉, 西安, 南京, 天津, 苏州], count: 12 }4.3 get_server_info —— 获取服务器信息无参数返回服务器名称、版本与工具清单便于客户端做能力发现与自检{ name: Weather MCP Server, version: 1.0.0, tools: [get_weather, list_supported_cities, get_server_info] }5. 直接运行服务器在 code/chapter10/weather-mcp-server 目录下执行python server.py发布版服务器将启动 HTTP 传输服务默认监听0.0.0.0:8081MCP 端点为/mcp。可通过环境变量调整端口与主机PORT9090 HOST127.0.0.1 python server.py若使用章节教学版stdio 传输python code/chapter10/14_weather_mcp_server.py6. 在 Claude Desktop 中使用将服务器接入 Claude Desktop 需要在配置文件claude_desktop_config.json中声明一个mcpServers条目macOS 路径~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 路径%APPDATA%\Claude\claude_desktop_config.json{ mcpServers: { weather: { command: python, args: [/path/to/server.py] } } }Claude Desktop 会以python /path/to/server.py的子进程方式启动该服务器stdio 传输随后即可在对话中通过get_weather、list_supported_cities等工具查询天气。注意command字段需为环境变量PATH中可解析的 Python 解释器路径args中的路径建议使用服务器脚本的绝对路径。7. 在 HelloAgents 框架中使用让 Agent 学会查天气这是本项目的核心使用场景。README 给出的最小接入代码如下from hello_agents import SimpleAgent, HelloAgentsLLM from hello_agents.tools import MCPTool agent SimpleAgent(name天气助手, llmHelloAgentsLLM()) weather_tool MCPTool(server_command[python, server.py]) agent.add_tool(weather_tool) response agent.run(北京今天天气怎么样)MCPTool是 HelloAgents 框架提供的 MCP 客户端工具封装通过server_command以子进程方式拉起 MCP 服务器并将服务器暴露的工具自动桥接为 Agent 可调用的工具。7.1 章节示例显式展开 MCP 子工具仓库在 14_weather_agent.py 中提供了一个更完整的实战写法。其关键步骤是显式展开并注册 MCP 子工具llm HelloAgentsLLM() assistant SimpleAgent( name天气助手, llmllm, system_prompt你是天气助手可以查询城市天气。 使用 mcp_get_weather 工具查询天气支持中文城市名。 ) server_script os.path.join(os.path.dirname(__file__), 14_weather_mcp_server.py) weather_tool MCPTool(server_command[python, server_script]) # 显式展开并注册 MCP 子工具 expanded_tools weather_tool.get_expanded_tools() if not expanded_tools: raise RuntimeError(未发现天气 MCP 子工具请检查服务脚本、依赖和启动日志。) for expanded_tool in expanded_tools: assistant.add_tool(expanded_tool)这里有两个值得学习的工程细节get_expanded_tools()展开机制MCPTool可以一次暴露服务器上的多个子工具通过展开后逐个add_tool注册到 Agent工具名会带上mcp_前缀如mcp_get_weathersystem prompt 中需使用该前缀名引导 LLM 调用空结果防御若 MCP 服务器启动失败或未暴露任何工具expanded_tools为空列表此时显式抛出RuntimeError并提示检查服务脚本、依赖和启动日志避免 Agent 在无工具可用的状态下静默运行。运行该脚本可进入交互模式python code/chapter10/14_weather_agent.py或执行单次演示python code/chapter10/14_weather_agent.py demo7.2 自动化测试验证仓库还提供了 14_test_weather_server.py使用MCPClient以编程方式对服务器做端到端验证可作为任何 MCP 服务的冒烟测试模板async with client: # 测试1: 获取服务器信息 info json.loads(await client.call_tool(get_server_info, {})) print(f服务器: {info[name]} v{info[version]}) # 测试2: 列出支持的城市 cities json.loads(await client.call_tool(list_supported_cities, {})) print(f支持城市: {cities[count]} 个) # 测试3: 查询北京天气 weather json.loads(await client.call_tool(get_weather, {city: 北京})) if error not in weather: print(f\n北京天气: {weather[temperature]}°C, {weather[condition]})该测试覆盖了服务器信息、城市列表、多个城市天气查询四类场景并针对get_weather返回中是否包含error字段做了断言式校验——这正是上一节提到的错误处理约定的实际验证用例。8. 容器化与云端发布Smithery 部署指南weather-mcp-server不仅是本地演示项目还配备了完整的容器化与发布配置可在 MCP 服务器注册平台 Smithery 上发布供全球用户安装使用。8.1 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精简镜像镜像体积可控通过环境变量固定PORT8081与server.py中os.getenv(PORT, 8081)的默认值一致也与 Smithery 约定的端口一致内置HEALTHCHECK健康检查指令便于容器编排平台如 Kubernetes探测服务存活状态启动命令CMD [python, server.py]运行 HTTP 传输模式的服务器。8.2 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 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 information注意runtime: container表示以容器方式运行startCommand.type: http对应server.py的 HTTP 传输模式tools列表则提前声明了服务器暴露的三个工具——这三处配置必须与源码保持一致否则会导致平台能力发现与实际不符。8.3 发布前自检清单仓库中的 PUBLISH_CHECKLIST.md 提供了一份完整的发布检查清单核心条目包括文件检查README、LICENSE、Dockerfile推荐、pyproject.toml必需、requirements.txt、smithery.yaml、server.py 是否齐备且可运行功能测试服务器能否正常启动、所有工具能否正常调用、错误处理是否完善、返回格式是否正确配置一致性pyproject.toml与smithery.yaml的name与version保持一致均需为1.0.0、version遵循语义化版本、homepageURL 正确GitHub 准备代码推送、创建v1.0.0标签与 Release、仓库设为 Public提交步骤登录 Smithery 后点击 Submit Server输入仓库 URL 并提交等待平台审核。这份清单同样适用于任何 MCP 服务器的发布流程可作为通用模板复用。9. 许可证与工程规范项目以 MIT License 开源仓库目录下包含独立的 LICENSE 文件同时 pyproject.toml 中声明license {text MIT}作者为 HelloAgents Team。这说明该项目定位为可自由复制、修改与再分发的教学范本。10. 小结与扩展思路本文从源码层面完整还原了 Weather MCP Server 的实现链路普通 Python 函数 →MCPServer.add_tool()注册 → stdio/HTTP 双传输模式启动 → Claude Desktop 配置接入 → HelloAgentsMCPTool桥接为 Agent 工具 → Dockerfile 容器化 → smithery.yaml 平台发布。其中贯穿始终的三个核心方法论值得复用函数即工具MCP 服务器开发不需要理解复杂协议细节只需把业务逻辑写成返回 JSON 字符串的 Python 函数并注册错误处理前置工具函数内部捕获异常并返回error字段保证 Agent 调用链路的健壮性配置与代码保持一致端口、工具清单、版本号在server.py、Dockerfile、pyproject.toml、smithery.yaml之间保持对齐是项目可发布、可被平台自动发现的前提。参考本仓库中的 14_weather_mcp_server.py 与 14_weather_agent.py你可以轻松将get_weather替换为任何外部 API 调用股票行情、新闻检索、数据库查询等在十分钟内构建出属于你自己的真实 MCP 服务器。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考