第四次作业

第四次作业：基于 MCP 的”能说会做”智能体开发

这个作业属于哪个课程	Class56-Grade2024-CS
这个作业要求在哪里	作业要求
这个作业的目标	构建一个基于 MCP 框架的智能体，实现自然语言交互与工具调用，并形成结构清晰的说明文档
学号	3124005969 邓子航，3124005969 郭敏哲

个人 Agent 助手说明文档

• 项目名称：智能待办管家（Todo MCP Agent）
• 项目类型：本地 CLI Agent
• 仓库位置：https://github.com/what-sup/3124005969/tree/my-mcp-agent
• 技术栈：Python 3.12、MCP (Model Context Protocol)、OpenAI SDK (兼容 DeepSeek)、JSON 本地存储
• 使用方式：命令行终端运行

一、需求描述

1.1 项目定位

本项目是一个面向大学生日常学习与生活场景的”能说会做”的 AI 智能体。核心目标是：

接收用户自然语言输入 → LLM 解析意图 → 调用本地 MCP 工具读写文件 → 返回自然语言结果。

项目重点拆解并实现以下能力： - 接入大模型（DeepSeek-Chat）进行自然语言理解与推理 - 构建 ReAct 工具调用循环（Agent Loop） - 基于 MCP 协议实现 Server 端与 Client 端的分离 - 实现待办事项的增删改查（CRUD）与持久化存储 - 保证工具执行的安全性与数据的原子写入

1.2 功能需求

编号	需求	说明
F1	自然语言交互	支持日常口语表达，如”下周三交高数作业”
F2	MCP 工具调用	基于官方 MCP SDK，将 Python 函数暴露为工具
F3	模糊时间解析	利用 LLM 结合当前时间，推断具体的 due 日期
F4	数据持久化	读写本地 data/todos.json 文件，重启不丢失
F5	多步推理	删除前先查询匹配，支持复杂指令拆解
F6	安全校验	限制文件操作目录，使用原子写防止数据损坏

二、业务流描述

2.1 整体架构

┌──────────────────────┐
│ 用户 (终端 CLI) │
└──────────┬───────────┘
│ 自然语言输入
▼
┌──────────────────────┐
│ Agent Client │
│ (agent.py / LLM Loop)│
└──────────┬───────────┘
│ JSON-RPC (stdio)
▼
┌──────────────────────┐
│ MCP Server │
│ (todo_server.py) │
└──────────┬───────────┘
│ 执行 Python 函数
▼
┌──────────────────────┐
│ 本地 JSON 数据 │
│ (data/todos.json) │
└──────────────────────┘

2.2 启动流程

python client/agent.py
│
▼
Client 初始化
│
├─ 加载 .env 配置 (API Key)
├─ 以子进程方式拉起 MCP Server (stdio 传输)
├─ MCP 握手 (initialize)
├─ 获取工具列表 (list_tools)
└─ 进入 REPL 循环 (你 >)

2.3 单轮对话主流程

用户输入
│
▼
Agent 调用 LLM (附带 tools schema)
│
├─ 无 tool_calls → 直接输出自然语言回复
│
└─ 有 tool_calls
├─ 解析工具名与参数 (如 add_todo)
├─ 通过 MCP Client 发送执行请求
├─ Server 执行并返回结果
├─ 结果以 role:tool 回填给 LLM
└─ 继续下一轮推理

三、实现说明

3.1 目录结构

todo-mcp-agent/
├── client/
│ └── agent.py # Agent 主循环 + LLM 接入
├── server/
│ └── todo_server.py # MCP Server（工具定义）
├── data/
│ └── todos.json # 本地数据文件（自动生成）
├── requirements.txt # 依赖清单
├── .env.example # 环境变量模板
└── README.md # 部署说明

3.2 核心模块职责

模块	职责
agent.py	组装 System Prompt、执行 ReAct 循环、维护 messages 历史、调度 MCP 工具
todo_server.py	使用 @mcp.tool() 装饰器暴露工具，负责 JSON 文件读写与安全校验

3.3 工具接口设计

Server 端的所有工具均通过官方 SDK 的装饰器定义：

@mcp.tool()
def add_todo(title: str, due: str = "", category: str = "其他", priority: str = "medium") -> str:
"""添加一条待办事项。due 格式如 2026-05-22 15:00"""
# 执行写入逻辑...
return f"已添加：{title}"

关键设计点：函数的 docstring 是 LLM 判断”何时调用该工具”的唯一依据，参数的类型注解会自动生成 JSON Schema。

3.4 关键技术决策与踩坑记录

在开发过程中，我们解决了以下棘手问题：

问题	原因与解决方案
Windows 下 stdio 通信失败	报错 ExceptionGroup: unhandled errors。原因是 Windows 默认的 Asyncio 事件循环策略与子进程通信不兼容。通过设置 asyncio.WindowsSelectorEventLoopPolicy() 解决。
SDK 版本导致 API 报错	报错 ModuleNotFoundError: mcp.server.fastmcp。原因是安装了 MCP 2.x，API 发生重命名。通过 pip install "mcp<2" 降级解决。
属性名大小写问题	报错 AttributeError: 'Tool' object has no attribute 'inputSchema'。不同版本 SDK 属性命名不同，需改为蛇形命名 input_schema。
OpenAI 底层库冲突	报错 TypeError: process() takes no keyword arguments。原因是 openai 3.x 的底层 HTTP 库兼容性 Bug。通过 pip install "openai<3" 降级解决。

四、使用示例（功能演示）

4.1 安装与启动

# 1. 安装依赖
pip install -r requirements.txt

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，填入你的真实 API Key (如 DeepSeek)

# 3. 启动智能体
python client/agent.py

4.2 智能添加待办

输入： > 帮我记一下，下周三前交软件工程作业，挺急的

Agent 内部执行： 1. 调用 add_todo，解析出 title="软件工程作业", due="2026-05-27 23:59", priority="high"。 2. 返回结果给 LLM。

最终输出： > 好的，已为你添加： > 📌 软件工程作业 > ⏰ 截止：2026-05-27（下周三） > 🔴 优先级：高

4.3 多步推理与状态变更

输入： > 英语作业写完了，帮我标记成完成

Agent 内部执行： 1. 先调用 list_todos(status="pending")，找到”英语作业”的 id。 2. 再调用 complete_todo(todo_id=2)。

最终输出： > ✅ 已标记”英语作业”为完成。剩余 1 项待办。

总结

本项目成功实现了一个基于 MCP 框架的智能体。它不仅能与用户进行自然语言交互，还能通过调用工具真实地操作本地文件，实现了”会说”与”会做”的统一。

通过本次作业，我们深入理解了 Agent 的 ReAct 循环原理、MCP 协议通信机制，以及大模型工具调用的底层逻辑。虽然开发过程中遇到了不少环境与版本兼容性的”坑”，但这让我们积累了宝贵的工程排错经验，为后续大项目的开发打下了坚实基础。