第四次作业
MCP Web 智能助手（个人事务助手 Agent）
一个基于 MCP（Model Context Protocol）和 LangChain 的智能助手 Web 应用。通过 WebSocket 做流式对话，让大模型能自主调用本地或远程的 MCP 工具（待办事项、天气查询等），帮你处理个人事务。
本次作业隶属于：周子骞，谭铭昊。
| 项目 | 内容 |
|---|---|
| 所属课程 | https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS/ |
| 作业要求 | https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS/homework/16760 |
| 作业目标 | 使用 AI 工具，在本机运行一个基于自然语言交互执行工作的 agent |
| 学号 | 3124004077，31240068 |
| Github仓库 | https://github.com/qiyan5957/-agent- |
目录
- 一.项目主体解释
- 1.1 功能特性
- 1.2 系统架构
- 1.3 技术栈
- 1.4 项目结构
- 二.具体使用说明
- 2.1 快速开始
- 2.2 使用说明
- 2.3 MCP 工具说明
- 2.4 API 接口
- 三.配置环境
- 3.1 配置说明
- 四.可能出现的问题
- 4.1 常见问题
- 五.亟待完成的方向
- 5.1 路线图
一.项目主体解释
1.1 功能特性
- 流式对话：基于 WebSocket 实时推送，AI 回复逐字输出。
- MCP 工具调用：模型通过 MCP 协议动态发现并调用外部工具，能力可插拔扩展。
- 思考过程可视化：前端展示「思考内容 → 工具调用 → 最终回复」的完整链路。
- 待办事项管理：内置 todo MCP 服务器，支持增删改查。
- 天气查询：内置 weather MCP 服务器，支持实时天气和 1-3 天预报。
- 聊天历史记录：基于 SQLite 持久化，多会话隔离存储。
- 对话分享：一键生成只读分享链接。
- 工具列表可视化：自动从 MCP 服务器拉取工具清单，按服务器分组展示参数说明。
- 灵活配置：前后端分离，通过 config.json / .env 切换部署环境。
1.2 系统架构
┌─────────────────────┐ WebSocket / REST ┌──────────────────────────┐
│ 前端 (Browser) │ ─────────────────────────────────▶ │ 后端 FastAPI (main.py) │
│ index.html │ ◀───────────────────────────────── │ /ws/chat 流式对话接口 │
│ tools.html │ JSON 消息双向推送 │ /api/* REST API │
│ share.html │ └──────────┬───────────────┘
└─────────────────────┘ │
│ 调用
▼
┌───────────────────────────┐
│ MCP 智能体 (mcp_agent.py) │
│ LangChain + ChatOpenAI │
│ bind_tools → 自主推理调用 │
└──────────┬────────────────┘
│ MCP 协议 (stdio)
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ todo server │ │ weather server│ │ 更多 MCP 服务 │
│ 待办事项管理 │ │ 天气查询 │ │ 可插拔扩展 │
└──────────────┘ └──────────────┘ └──────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ todos.db │ │ wttr.in API │
└──────────────┘ └──────────────┘
核心流程：
- 用户在浏览器输入问题，前端通过 WebSocket 发送到后端。
- 后端 mcp_agent 把问题连同聊天历史交给模型推理。
- 模型判断是否需要调用工具，需要则通过 MCP 协议调用对应的 MCP 服务器。
- 工具返回结果后，模型进行下一轮推理，直到生成最终回复。
- 整个过程以流式事件（思考、工具调用、最终回复）实时推送给前端。
- 完整对话异步存入 SQLite 数据库。
1.3 技术栈
| 分类 | 技术 | 说明 |
|---|---|---|
| 后端框架 | FastAPI + Uvicorn | 提供 REST API 与 WebSocket 服务 |
| 通信协议 | WebSocket | 实时双向流式消息推送 |
| AI 框架 | LangChain | langchain-openai + langchain-mcp-adapters |
| 大模型 | OpenAI 兼容接口 | 默认 deepseek-chat，可配置任意兼容模型 |
| MCP 协议 | mcp + langchain-mcp-adapters | 标准模型上下文协议，工具可插拔 |
| 数据库 | SQLite (aiosqlite) | 聊天记录持久化，异步访问 |
| 前端 | 原生 HTML / CSS / JS | 轻量无框架，marked.js 渲染 Markdown |
| 配置管理 | python-dotenv / config.json | 后端 .env、前端 config.json |
1.4 项目结构
WebwithMCP
├── backend/ # 后端服务
│ ├── main.py # FastAPI 主入口（WebSocket + REST API）
│ ├── mcp_agent.py # MCP 智能体封装（LangChain + 流式处理）
│ ├── database.py # SQLite 聊天记录管理
│ ├── todo_mcp_server.py # MCP 服务器：待办事项管理
│ ├── weather_mcp_server.py # MCP 服务器：天气查询
│ ├── mcp.json # MCP 服务器配置
│ ├── test_mcp_client.py # MCP 客户端测试脚本
│ ├── requirements.txt # 后端依赖
│ ├── chat_history.db # 聊天记录数据库（运行时生成）
│ └── todos.db # 待办事项数据库（运行时生成）
├── frontend/ # 前端静态页面
│ ├── index.html # 聊天主界面
│ ├── tools.html # 工具列表页面
│ ├── share.html # 对话分享页面
│ ├── config.json # 前端配置文件（后端地址等）
│ ├── css/
│ │ ├── style.css
│ │ └── tools.css
│ └── js/
│ ├── config.js # 配置管理器
│ ├── ws.js # WebSocket 封装
│ ├── chat.js # 聊天主逻辑
│ ├── share.js # 分享页面逻辑
│ └── chat/
│ ├── thinking-flow.js # 思考过程流式渲染
│ └── share-module.js # 分享功能模块
├── requirements.txt # 依赖清单
├── .env.example # 环境变量示例
├── to-do-list.md # 开发任务清单
└── README.md # 本文档
二.具体使用说明
2.1 快速开始
环境要求：
| 依赖 | 版本 |
|---|---|
| Python | 3.9+ |
| Node.js | 不需要（纯静态前端） |
| 大模型 API | 任意 OpenAI 兼容接口（需 API Key） |
克隆项目：
git clone https://github.com/qiyan5957/-agent-.git
cd WebwithMCP
创建虚拟环境并安装依赖：
# 创建虚拟环境
python -m venv venv
# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux / macOS
source venv/bin/activate
# 安装后端依赖（推荐使用 backend/requirements.txt，更完整）
pip install -r backend/requirements.txt
配置环境变量。复制 .env.example 为 .env：
cp .env.example .env
编辑 .env：
OPENAI_API_KEY=sk-你的密钥
OPENAI_BASE_URL=https://api.deepseek.com
OPENAI_MODEL=deepseek-chat
OPENAI_TEMPERATURE=0.2
OPENAI_TIMEOUT=60
BACKEND_PORT=8003
配置 MCP 服务器。编辑 backend/mcp.json，把 command 指向你自己的 Python 解释器路径（这里以我的路径为例）：
{
"servers": {
"todo": {
"transport": "stdio",
"command": "D:/PythonProject/个人事务助手agent/venv/Scripts/python.exe",
"args": ["D:/PythonProject/个人事务助手agent/WebwithMCP/backend/todo_mcp_server.py"],
"env": { "PYTHONUTF8": "1" }
},
"weather": {
"transport": "stdio",
"command": "D:/PythonProject/个人事务助手agent/venv/Scripts/python.exe",
"args": ["D:/PythonProject/个人事务助手agent/WebwithMCP/backend/weather_mcp_server.py"],
"env": { "PYTHONUTF8": "1" }
}
}
}
也可以按需增删服务器，只需新增一个 MCP 服务器配置，后端会自动发现并加载它的工具。
启动后端：
cd backend
python main.py
启动成功后会看到类似输出：
🚀 启动 MCP Web 智能助手...
📁 数据库路径: ...\backend\chat_history.db
✅ 数据库表结构初始化完成
🔗 正在连接MCP服务器...
✅ 从 todo 获取到 4 个工具
✅ 从 weather 获取到 2 个工具
✅ MCP Web 智能助手启动成功
后端默认监听 http://localhost:8003 。
打开前端，直接用浏览器打开 frontend/index.html，或起一个静态服务器：
# 方式一：直接打开
# 双击 frontend/index.html
# 方式二：使用 Python 静态服务器
cd frontend
python -m http.server 8080
# 然后访问 http://localhost:8080
前端通过 frontend/config.json 指定后端地址，默认 http://localhost:8003 。如果后端部署在其他机器或端口，改这个文件即可。
2.2 使用说明
聊天对话：
- 打开主界面，等待右上角状态变成「在线」。
- 在输入框输入问题，例如：
- 「帮我创建一个待办：明天下午买牛奶」
- 「查询一下北京的天气」
- 「我有哪些未完成的待办？」
- 按 Enter 发送（Shift + Enter 换行）。
- 页面会实时展示 AI 的思考过程、工具调用与最终回复。
工具列表：点击右上角「工具列表」进入 tools.html，可以查看当前所有 MCP 服务器提供的工具、参数说明与必填项，支持按服务器分组折叠 / 展开。
分享对话：点击「分享对话」按钮生成只读分享链接，其他人可以通过链接查看当前会话的完整记录（不能继续对话）。
清空聊天：点击「清空聊天」按钮，清空当前会话的历史记录。
2.3 MCP 工具说明
todo —— 待办事项管理：
| 工具名 | 说明 | 主要参数 |
|---|---|---|
| create_todo | 创建一条待办事项 | title（必填）、description（可选） |
| list_todos | 列出待办事项 | filter：all / pending / completed |
| update_todo | 更新待办标题或完成状态 | todo_id（必填）、title、completed |
| delete_todo | 删除指定待办事项 | todo_id（必填） |
数据存储于 backend/todos.db。
weather —— 天气查询：
| 工具名 | 说明 | 主要参数 |
|---|---|---|
| query_weather | 查询指定城市实时天气 | city（必填，支持中英文） |
| query_forecast | 查询未来天气预报 | city（必填）、days（1-3，默认 3） |
天气数据来源于 wttr.in 开放接口。
2.4 API 接口
WebSocket：
| 路径 | 说明 |
|---|---|
| /ws/chat | 流式聊天接口，接收 / 推送 JSON 消息 |
后端推给前端的消息类型：
| 类型 | 说明 |
|---|---|
| session_info | 会话建立，返回 session_id |
| user_msg_received | 用户消息已接收 |
| ai_thinking_start / ai_thinking_chunk / ai_thinking_end | AI 思考过程流式推送 |
| tool_plan / tool_start / tool_end / tool_error | 工具调用计划与执行状态 |
| ai_response_start / ai_response_chunk / ai_response_end | 最终回复流式推送 |
| pong | 心跳响应 |
REST API：
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | / | 服务信息 |
| GET | /api/tools | 获取 MCP 工具列表（按服务器分组） |
| GET | /api/history | 获取聊天历史（limit、session_id、conversation_id） |
| DELETE | /api/history | 清空聊天历史（可选 session_id） |
| GET | /api/status | 获取系统运行状态与统计 |
| GET | /api/database/stats | 获取数据库详细统计 |
| GET | /api/share/ | 获取指定会话的只读分享记录 |
示例：
# 获取工具列表
curl http://localhost:8003/api/tools
# 获取系统状态
curl http://localhost:8003/api/status
# 获取聊天历史
curl "http://localhost:8003/api/history?limit=10"
三.配置环境
3.1 配置说明
后端环境变量（.env）：
| 变量 | 说明 | 默认值 |
|---|---|---|
| OPENAI_API_KEY | 大模型 API 密钥 | 无 |
| OPENAI_BASE_URL | API 基础地址 | 无 |
| OPENAI_MODEL | 模型名称 | deepseek-chat |
| OPENAI_TEMPERATURE | 采样温度 | 0.2 |
| OPENAI_TIMEOUT | 请求超时（秒） | 60 |
| BACKEND_PORT | 后端监听端口 | 8003 |
前端配置（frontend/config.json）：
{
"backend": {
"host": "localhost",
"port": 8003,
"protocol": "http",
"wsProtocol": "ws"
},
"api": {
"baseUrl": "http://localhost:8003",
"wsUrl": "ws://localhost:8003"
}
}
api.baseUrl / api.wsUrl 优先于 backend 自动构建的地址。部署在 HTTPS 环境时，把 protocol 改成 https、wsProtocol 改成 wss。
四.可能出现的问题
4.1 常见问题
-
启动后端提示「缺少 OPENAI_API_KEY」
在 .env 里正确配置 OPENAI_API_KEY，并确认 .env 位于后端可以加载的位置（load_dotenv(find_dotenv()) 会向上查找）。
-
前端一直显示「离线」/ 无法连接
检查 frontend/config.json 里的后端地址、端口是否与后端实际监听一致，同时看浏览器控制台有没有 CORS 报错。
-
工具列表为空或加载失败
检查 backend/mcp.json 里 command 和 args 的路径是否正确，确认 Python 解释器和脚本路径存在，且 mcp 相关依赖已安装。
-
HTTPS 环境下 WebSocket 连接失败
HTTPS 页面必须使用 wss://，同步修改 config.json 里的 protocol 和 wsProtocol。
-
Windows 下运行 MCP 服务器出现编码错误
mcp.json 里已经设置了 PYTHONUTF8=1，如果还有问题，可以参考 test_mcp_client.py 里 stdout 重配置的写法。
五.亟待完成的方向
5.1 路线图
小组介绍：
- 小组成员：周子骞，谭铭昊
- 小组分工：谭铭昊负责完成backend代码、WebSocket/REST API、数据库、依赖锁定、启动日志。周子骞负责前端页面和脚本，mcp server的编写，README的编写
- 个人感悟 周子骞：这次负责前端，业务函数编写以及 README，我最大的体会是：前端不是画页面，而是把 Agent 的思考、工具调用和流式回复准确呈现出来。接口契约、状态管理、联调用例和文档可复现，比样式更花时间，也更重要，同时，业务函数要做好接口，不然多人编程很容易乱。
- 个人感悟 谭铭昊：在本次智能体构建作业中，我深刻体会到"能说会做"背后的工程复杂性。自然语言对话看似简单，但当模型需要准确理解意图并调用MCP工具完成任务时，提示词设计、工具描述规范、参数校验每一环都不能马虎。通过小组协作，我学会了如何拆分Agent的规划层与执行层，也认识到清晰的接口约定比代码本身更重要。调试阶段反复出现的工具调用失败让我明白，容错与日志是智能体走向可用的关键。这次实践不仅提升了我的框架应用能力，更让我理解了从"对话"到"行动"之间需要多少严谨的设计与验证。
附：使用示例
浙公网安备 33010602011771号