内容
# 作业 4：构建 MCP 代理
**给定：** 2026 年 7 月 5 日
**截止日期：** 2026 年 7 月 12 日（1 周）
**分数：** 100
## 你将构建的内容
你将构建**自己的 MCP 服务器**和一个使用它的 **LangGraph 代理**。
该代理将同时连接到**三个 MCP 服务器**：你构建的服务器，以及其他人已经制作的两个公共服务器。代理将从正确的服务器选择正确的工具来回答问题。
这就是整个任务。你不是在构建一个大型应用程序。你正在学习如何制作 MCP 服务器，在 HTTP 上运行它，并将其插入到另一个服务器旁边的代理中。
## 它如何组合在一起
这样理解这张图：
- **用户**提出问题。
- **LangGraph 代理**思考。如果它需要工具，它会调用一个工具，获取结果，然后再次思考。当完成后，它会回答。
- `MultiServerMCPClient` 在程序启动时连接到所有三个服务器，并为代理提供每个工具。
- **蓝色服务器是你构建的服务器**。**绿色服务器是公共服务器**，你从目录中获取。
## 你需要构建的内容
### 第一部分：你的 MCP 服务器
使用 **FastMCP** 在 Python 中构建一个 MCP 服务器。它必须在 **可流式 HTTP**（不是 stdio）上运行。它必须具有：
- **至少 4 个工具**，一起执行完整的 **CRUD**：**C**reate、**R**ead、**U**pdate、**D**elete，操作一个小型数据存储（可以使用 SQLite）。
- **至少 1 个资源**（只读，有 URI）。
- **至少 1 个提示**（可重用的模板）。
使用 `mcp.run(transport="http", port=8000)` 运行它。它将在 `http://127.0.0.1:8000/mcp` 处生效。
### 第二部分：在检查器中测试它
在编写代理之前，打开 **MCP 检查器**并手动调用你的工具：
```bash
npx @modelcontextprotocol/inspector
```
选择 "Streamable HTTP" 并输入 `http://127.0.0.1:8000/mcp`。调用一个写入数据的工具，然后读回数据。**截取屏幕截图**。
### 第三部分：你的 LangGraph 代理
使用 `MultiServerMCPClient` 构建一个 LangGraph 代理。它必须连接到**三个服务器**：你的服务器和**两个公共服务器**，从目录中获取。
良好的公共服务器（不需要 API 密钥）：
- `fetch`（获取网页文本）：`uvx mcp-server-fetch`
- `time`（当前时间，时区）：`uvx mcp-server-time`
更多选项和确切配置请参见 **[public-servers.md](public-servers.md)**。服务器位置：`github.com/punkpeye/awesome-mcp-servers`，`registry.modelcontextprotocol.io`，`glama.ai/mcp/servers`，`smithery.ai`。
### 第四部分：展示其运行并录制视频
运行**三个示例问题**。每个问题都是你的项目的“输出”。至少一个问题必须**写入**你的服务器，至少一个问题必须使用**公共**服务器。保存答案（截图或文本文件）。
然后录制一个简短的**视频**（2 到 5 分钟），解释演示、架构、MCP 如何连接以及展示工具调用的过程。详细信息请参见下面的“提交内容”。
## 选择主题
你可以构建任何主题。**不能**是自然语言到 SQL（我们在课堂上已经做过了）。代理应该**更改和添加数据**，而不是运行自由 SQL 查询。
如果你想有一个现成的想法，可以构建一个**旅行规划器**（推荐）：
- **存储：** 行程，然后是行程中的目的地，然后是目的地中的活动。
- **你的 6 个工具：** `create_trip`、`add_destination`、`list_destinations`、`add_activity`、`toggle_activity_booked`、`delete_destination`。
- **公共服务器：** `time`（城市的当地时间）和 `fetch`（关于某个地方的事实）。
- **示例问题：** “在行程 1 中添加一个京都的 3 晚停留，并告诉我京都现在的当地时间。” 代理在一步中写入你的服务器并读取公共时间服务器。
其他好的主题：阅读清单、食谱和储藏室、费用跟踪器、习惯跟踪器。每个主题的简要描述在本文件的末尾。
在 **[starter/](starter/)** 中有一个现成的启动器。它是一个旅行规划器服务器，已经完成了 3 个工具，还有 3 个工具留给你。你可以使用它，也可以从头开始。
## 提交内容
你需要提交**两样东西**：你的**代码**和一个**视频**。
**1. 你的代码**（一个 GitHub 仓库或一个 zip 文件）：
```
your-project/
server.py 你的 MCP 服务器
agent.py 你的 LangGraph 代理
requirements.txt
.env.example 列出需要的密钥，不要提交实际密钥
README.md 参见下面
screenshots/
inspector.png 检查器调用其中一个工具
demo.png （或 demo.txt）你的 3 个示例问题和答案
```
你的 `README.md` 必须包含：
1. 你构建的主题。
2. 你的表格、工具、资源和提示。
3. 你使用的 2 个公共服务器以及原因。
4. 如何运行它（启动服务器，然后启动代理）。
5. 你的 3 个示例问题和答案。
6. **一段短段落：** 为什么将工具放在 MCP 服务器中比将它们作为代理内部的普通 Python 函数更好？使用你自己的话。这表明你理解了 MCP。
**2. 视频**（2 到 5 分钟）。这不仅仅是一个演示。我们希望看到你理解它是如何工作的。你的视频必须显示并解释：
- **演示：** 向你的代理提问并显示答案。
- **架构：** 使用你的图表（或我们的）解释各个部分如何组合：用户、LangGraph 代理、客户端和三个服务器。
- **MCP 如何连接：** 显示你的 `MultiServerMCPClient` 配置，并指出三个服务器及其传输方式（你的 HTTP 服务器和两个公共服务器）。
- **正在发生的工具调用：** 显示代理选择工具并获取结果。指向打印的工具调用（或 MCP 检查器）并解释正在传输的内容。显示至少一个调用你的服务器和一个调用**公共**服务器。
使用任何屏幕录制器录制。上传到 YouTube（可以是未列出的）、Google Drive 或 Loom，并在你的 `README.md` 中提供链接。
## 如何评分（100 分）
| 部分 | 分数 | 我们检查的内容 |
| --- | --- | --- |
| 你的 MCP 服务器 | 20 | 4+ CRUD 工具，1+ 资源，1 个提示，在 HTTP 上运行 |
| LangGraph 代理 | 20 | 连接你的服务器 + 2 个公共服务器，所有三个都有效 |
| 3 个示例问题 | 10 | 它们运行。 一个写入你的服务器。 一个使用公共服务器。 |
| **视频讲解** | **35** | 演示（5），架构解释（10），MCP 如何连接（10），工具调用实时显示和解释（10）。 技术性，不仅仅是演示。 |
| README 和“为什么使用 MCP”段落 | 15 | 清晰的步骤，段落有意义 |
**奖励（最多 +10）：**
- 在其中一个工具中调用免费的公共 API，例如 Open-Meteo 天气或 Open Library 书籍。 (+4)
- 从一个 FastAPI 应用程序提供 REST 和 MCP 服务。 (+3)
- 在工具中添加 `ctx.info(...)` 日志行并在检查器中显示。 (+3)
## 遵循的步骤
1. 选择你的主题并设计 2 或 3 个小表格。
2. 使用 FastMCP 编写 `server.py`。从一个工具开始，运行它，然后添加其余工具。查看工作坊仓库中的 `servers/analytics_server.py` 作为模型。
3. 在 HTTP 上运行服务器并在检查器中测试它。截取屏幕截图。
4. 编写 `agent.py`。连接你的服务器和 `time` 以及 `fetch`。
5. 运行你的 3 个示例问题。保存输出。
6. **录制你的视频**（2 到 5 分钟）。解释演示、架构、MCP 如何连接以及工具调用的过程。
7. 编写你的 `README.md`（包含视频链接）并在 7 月 12 日前推送到 GitHub。
## 需要记住的规则
- **在 stdio 服务器中永远不要使用 `print()`。** 它会破坏协议。使用 `ctx.info(...)`。
- **HTTP URL 必须以 `/mcp` 结尾。** 普通 URL 将不起作用。
- 你需要同时安装 **uv** 和 **Node**。一些公共服务器使用 `uvx`（Python），而一些使用 `npx`（Node）。参见 `public-servers.md`。
- 不要提交你的 API 密钥。使用 `.env`，只提交 `.env.example`。
## 可以查看的工作坊内容
- 构建服务器：`notebooks/03_build_your_own_server.ipynb`，`servers/analytics_server.py`
- HTTP 和 FastAPI：`servers/fastapi_integration.py`
- 代理：`notebooks/04_connect_langgraph_agent.ipynb`，`clients/03_langgraph_agent.py`
## 其他主题创意（简要）
- **阅读清单：** 你想读、正在读或已经读完的书籍。添加书籍、更改状态、评分、添加笔记、列出、删除的工具。公共服务器：`fetch` + `wikipedia`。最简单的主题。
- **食谱和储藏室：** 你有的食物和你想烹饪的食谱。添加或使用储藏室物品、保存或删除食谱、列出它们的工具。公共服务器：`fetch` + `time`。
- **费用跟踪器：** 你的支出。添加费用、设置预算、显示本月总数、列出、删除的工具。（仅限总数，不限自由 SQL。）公共服务器：`time` + `fetch`。
- **习惯跟踪器：** 习惯和每日签到。添加习惯、签到、显示连胜、列出、删除的工具。公共服务器：`time` + `fetch`。
