基于 AIToolkit 模板构建 Weather MCP Server：环境配置、Agent Builder 与 MCP Inspector 双链路调试实战

• 教程
• 文档
• 人工智能

本文以开源仓库mcp-for-beginners的 Lab 3 实战模块为背景，围绕 Weather MCP Server 模板文档 展开，讲解如何用 Python 快速搭建一个基于 Model Context Protocol（MCP）的天气服务脚手架，并借助 Microsoft Foundry Toolkit（AI Toolkit）的 Agent Builder 与 MCP Inspector 完成两种主流调试链路。读完本文，你将掌握 MCP 服务器的目录结构、FastMCP工具注册与 SSE/stdio 双传输原理、虚拟环境两种安装方式，以及一键式断点调试的完整工作流。

模板概览：一个可复用的 Weather MCP Server 脚手架

该模板在仓库中对应的完整代码位于 lab3/code/weather_mcp，本质上是一个用 Python 编写、返回mock（模拟）天气数据的 MCP Server 样例，官方定位是 "a scaffold for your own MCP Server"——即可以作为你自己 MCP Server 的脚手架起点。它包含三类核心特性：

源码级骨架：FastMCP 与工具注册

模板的最小可运行核心只有两个文件。src/server.py中通过mcp.server.fastmcp.FastMCP创建服务器实例，并用@server.tool()装饰器注册了一个名为get_weather的异步工具：

# 10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/lab3/code/weather_mcp/src/server.py import json import random from mcp.server.fastmcp import FastMCP # Initialize FastMCP server server = FastMCP("weather_mcp") @server.tool() async def get_weather(location: str) -> str: """Get weather for a location. Args: location: Location to get weather for, e.g., city name, state, or coordinates """ if not location: return "Location is required." # mock weather data conditions = [ "Sunny", "Rainy", "Cloudy", "Snowy" ] weather = { "location": location, "temperature": f"{random.randint(10, 90)}°F", "condition": random.choice(conditions), } return json.dumps(weather, ensure_ascii=False)

从实现看，该工具具备三个值得复用的设计点：参数校验（空location直接返回提示）、mock 数据生成（温度在 10–90°F 之间随机、天气条件在 Sunny/Rainy/Cloudy/Snowy 中随机选取）、结构化返回（用json.dumps序列化结果，并指定ensure_ascii=False以保留非 ASCII 字符）。若后续接入真实天气 API，只需替换weather字典的构造逻辑即可，工具签名与调用链无需改动。

入口文件 src/init.py 则负责传输方式与运行时配置的分发：

import os import sys from server import server if __name__ == "__main__": """Main entry point""" transport_type = sys.argv[1] if len(sys.argv) > 1 else None server.settings.log_level = os.environ.get("LOG_LEVEL", "DEBUG") if transport_type == "sse": port = int(os.environ.get("PORT", 3001)) server.settings.port = port server.settings.host = "127.0.0.1" server.run(transport="sse") elif transport_type == "stdio": server.run(transport="stdio") else: print("Invalid transport type. Use 'sse' or 'stdio'.") sys.exit(1)

这里可以看到两个关键事实：传输方式由命令行参数决定（传入sse走 HTTP 流式传输、传入stdio走标准输入输出传输，两者均是 MCP 协议支持的传输层）；SSE 模式的端口与主机可通过环境变量覆盖（PORT默认 3001、host固定为127.0.0.1），日志级别也可通过LOG_LEVEL环境变量调整，默认DEBUG。这些默认值正是下文中调试端口约定的源头。

环境准备：uv 与 pip 两套安装路径

模板文档给出了明确的前置条件与两套等价的依赖安装方式。运行该 MCP Server 需要：

• Python（>=3.10，见 pyproject.toml 中requires-python声明）；
• （可选，若偏好 uv）uv包管理器；
• Python Debugger Extension（VS Code 的ms-python.debugpy扩展，断点调试依赖它）。

安装依赖时，两种方式任选其一，推荐在项目根目录创建独立虚拟环境：

注意：创建虚拟环境后，请重新加载 VS Code 或重启终端，确保后续命令使用虚拟环境中的 Python 解释器，否则可能出现依赖装到了全局环境、调试器找不到包的问题。

从 pyproject.toml 的声明可以看到依赖细节：运行依赖为mcp>=1.26.0，可选开发依赖dev组固定为debugpy==1.8.8。--extra dev/[dev]的作用就是把debugpy一并装好——它是 VS Code 附加调试（attach）模式下断点生效的基础。仓库配套的 Module 3 实验文档 也提到其教学基线使用 MCP SDK 1.9.3 与 Inspector 0.14.0，而模板代码目录中的依赖已按最新版本演进，安装时以你实际拉取的pyproject.toml/uv.lock为准即可。

模板目录结构：每一层的职责

模板文档给出了一级目录的职责划分，结合 Module 3 实验文档 中的完整结构树，模板实际包含以下内容：

其中inspector/package.json值得注意——它本身只是一个占位项目，核心脚本只有一行"dev:inspector": "mcp-inspector"，并声明了对@modelcontextprotocol/inspector的依赖，作用是在本地拉起 MCP Inspector 服务，供调试配置中的浏览器启动任务使用。

说明：.vscode与.aitk属于模板生成项，仓库中未提交这两个目录；Module 3 实验文档 的 "Step 5: Configure VS Code Debugging" 章节给出了launch.json与tasks.json的完整内容，本地生成模板后按该章节拷贝覆盖即可。

通过 Agent Builder 运行：以 LLM 客户端完成端到端测试

环境就绪后，最直接的验证方式是把 MCP Server 作为被调用的工具，经由 Microsoft Foundry Toolkit 的 Agent Builder 以自然语言触发。操作步骤如下：

1. 打开 VS Code 调试面板（Debug panel），选择Debug in Agent Builder调试配置，或直接按F5启动调试。
2. 在 Microsoft Foundry Toolkit 的 Agent Builder 中，选择一个有效的 Foundry 部署（deployment），例如gpt-5.1，然后输入：What is the weather in Shanghai?
3. 点击Run，Agent 会自动发现并连接该 MCP Server，调用get_weather工具并返回模拟天气结果。

完成上述操作即代表 "You have successfully run the Weather MCP Server in your local dev machine via Agent Builder as the MCP Client"。

这条链路的自动化原理可以从 Module 3 实验文档 的tasks.json配置中看出：名为Open Agent Builder的 VS Code 任务通过输入参数ai-mlstudio.agentBuilder启动 Agent Builder，并传入"initialMCPs": ["local-server-weather_mcp"]，从而把本地运行的 MCP Server 预置为 Agent 可用的工具列表；同时Start MCP Server任务以python -m debugpy --listen 127.0.0.1:5678 src/__init__.py sse在后台启动服务器并监听 5678 端口等待附加调试。也就是说，按 F5 后 VS Code 会自动完成"起服务 → 开 Agent Builder → 附加调试器"三步串联。

调试结果示例：Agent 收到工具返回的 JSON（位置、温度、天气条件）后，会组织成自然语言回复给用户。

通过 MCP Inspector 调试：面向开发者的可视化测试台

MCP Inspector 是 MCP 生态中面向开发者（而非终端用户）的可视化调试工具，适合在没有大模型客户端参与的情况下，直接对服务器注册的工具做"点对点"验证。模板文档给出了完整步骤：

1. 安装 Node.js（Inspector 为 Node 生态工具）；
2. 初始化 Inspector：cd inspector&&npm install；
3. 打开 VS Code 调试面板，选择Debug SSE in Inspector (Edge)或Debug SSE in Inspector (Chrome)，按 F5 启动调试；
4. 浏览器中打开 MCP Inspector 页面后，点击Connect按钮连接该 MCP Server；
5. 之后即可List Tools（列出服务器注册的工具）、选中get_weather、填入location参数，再Run Tool直接调用并查看返回，借此逐行调试你的服务器代码。

注意：所有调试模式（Agent Builder 与 Inspector）都支持断点。你可以在工具实现代码（例如src/server.py的get_weather函数体内）添加断点，当 Inspector 或 Agent 触发工具调用时，VS Code 会停在断点处，便于观察中间变量与数据流。

从配置层面看（见 Module 3 实验文档 的launch.json），Inspector 调试是由一个复合配置（compound）完成的：Debug in Inspector (Edge/Chrome)同时拉起"启动浏览器并打开 Inspector 地址"与"附加到本地 MCP 服务"两个子配置，前置任务Start MCP Inspector负责在inspector目录下执行npm run dev:inspector（即mcp-inspector）并设置CLIENT_PORT=6274、SERVER_PORT=6277，而浏览器地址中通过serverUrl=http://localhost:3001/sse#tools指向本机 SSE 服务器端点。这也是为什么按 F5 一次就能得到"Inspector 页面 + 可断点服务器"的完整调试环境。

默认端口约定与定制方式

模板文档对两种调试模式的端口做了明确约定：

理解这些端口的"来源"有助于按需定制：

• 3001：SSE 传输下 MCP Server 的监听端口。它由 src/init.py 中的os.environ.get("PORT", 3001)读取，同时 Module 3 实验文档 的tasks.json通过"env": { "PORT": "3001" }注入该值。修改端口时两端必须同步（环境变量 +launch.json中的serverUrl），否则浏览器无法连上服务器。
• 5173 / 3000：Inspector 自身 Web 界面与代理服务的默认端口。模板文档以 Agent Builder 教程的旧版约定给出；仓库内 Module 3 实验文档 则使用了6274（Inspector 客户端端口）与6277（代理端口）的新版配置，并明确提示其 Inspector 地址基于 legacy/sse端点、依赖被固定为 MCP SDK 1.9.3 与 Inspector 0.14.0。因此，端口具体取值以你本地tasks.json/launch.json实际内容为准，两个文档版本间存在演进差异是正常的。
• 5678：debugpy附加调试的监听端口（--listen 127.0.0.1:5678），由launch.json中Attach to Local MCP配置的connect.port与之对应，用于断点调试通道，一般无需修改。

常见问题与向真实服务器的演进路径

围绕模板使用，有几个高频问题值得提前说明：

• 虚拟环境未生效：创建.venv后没有重载 VS Code/终端，导致python指向全局解释器。解决办法是执行 "Python: Select Interpreter" 手动选择虚拟环境 Python，或关闭重开终端。
• 传输参数错误：src/__init__.py只接受sse与stdio两个合法传输参数，其它输入会打印Invalid transport type. Use 'sse' or 'stdio'.并退出（退出码 1）。调试配置中默认传sse，即 HTTP 流式传输。
• 断点不生效：确认已安装debugpy==1.8.8（--extra dev/[dev]安装组）以及 VS Code 的 Python Debugger 扩展，并确认选择的是虚拟环境解释器。
• 从 mock 到真实数据：从源码结构看，get_weather与外部世界唯一的耦合点是"构造weather字典"这段逻辑；将其替换为对真实天气 API 的异步调用（如httpx请求 + 结果映射），即可把脚手架演化为生产级天气服务，工具对外暴露的location参数与 JSON 返回结构均可保持不变。

至此，你已经走通了"模板生成 → 环境安装 → 双链路调试 → 定制端口"的完整 MCP Server 开发闭环。下一步可以在 Module 4 中看到同一套工作流如何被用于构建生产化的 GitHub 仓库克隆 MCP Server，进一步验证该脚手架在真实业务场景下的扩展能力。

• 教程
• 文档
• 人工智能