sun
feb1a0b280
- 实现了基于LangChain的MCP Agent，支持连接MCP服务器调用工具 - 添加了环境配置文件(.env)，包含LLM模型和API配置信息 - 创建了完整的工具系统，包括BaseTool基类和Bash、Terminate、Add等工具 - 集成了天气查询工具，支持通过中国气象局API获取天气预报信息 - 实现了交互式对话功能，支持多轮工具调用和结果处理 - 添加了详细的CLAUDE.md开发指导文档
107 lines
3.6 KiB
Markdown
107 lines
3.6 KiB
Markdown
# CLAUDE.md
|
||
|
||
此文件为 Claude Code（claude.ai/code）在处理此存储库中的代码时提供指导。
|
||
|
||
# 交互规则（优先级最高）
|
||
1. 所有与本仓库相关的沟通、文档编辑、代码注释、解释说明均使用**中文**
|
||
2. 技术术语以及命令保留英文原词（如 Langchain、Deepagents），但解释说明必须用中文
|
||
3. 代码本身的语法/关键字保持英文（符合编程规范），但注释、文档、交互回复全部使用中文
|
||
4. 当前项目为技术验证项目，目前使用Langchain、Deepagents等框架，遇到框架相关问题需要首先参考官方技术文档，链接：
|
||
```text
|
||
[Langchain](https://docs.langchain.com/oss/python/langchain/overview)、[Deepagents](https://docs.langchain.com/oss/python/deepagents/overview)
|
||
```
|
||
|
||
## 项目概述
|
||
|
||
TestMCP 是一个 MCP (Model Context Protocol) 服务器实现，带有 OpenAI 兼容的客户端，用于构建 AI Agent 系统。该项目是 "OpenManus" 的简化/修改版本 - 一个支持工具调用的 AI Agent 框架。
|
||
|
||
## 命令
|
||
|
||
### 运行 Demo MCP 服务器 (FastMCP 带天气工具)
|
||
```bash
|
||
python main.py
|
||
```
|
||
运行 SSE 服务器，默认端口，包含 `add()` 和 `get_weather_by_location()` 工具。
|
||
|
||
### 运行 OpenManus 风格的 MCP 服务器
|
||
```bash
|
||
python -m app.mcp_server.server --transport stdio
|
||
```
|
||
|
||
### 运行客户端
|
||
```bash
|
||
python client.py
|
||
```
|
||
通过 SSE 连接到 `http://127.0.0.1:8000/sse` 的 MCP 服务器。
|
||
|
||
### 启动Agent调用本地工具
|
||
```bash
|
||
python tool_call_agent.py
|
||
```
|
||
|
||
### 包管理
|
||
项目使用 `uv` 作为包管理器：
|
||
```bash
|
||
uv sync # 安装依赖
|
||
uv add <package> # 添加新依赖
|
||
```
|
||
|
||
## 架构
|
||
|
||
### 核心组件
|
||
|
||
```
|
||
app/
|
||
├── mcp_server/
|
||
│ └── server.py # MCPServer 类，包含 FastMCP 和工具注册系统
|
||
├── tools/
|
||
│ ├── base.py # BaseTool (抽象类), ToolResult, CLIResult
|
||
│ ├── bash.py # Bash 命令执行工具
|
||
│ └── terminate.py # 终止工具
|
||
├── utils/
|
||
│ └── logger.py # 基于 Loguru 的日志系统，支持文件轮转
|
||
└── exceptions.py # ToolError, OpenManusError, TokenLimitExceeded
|
||
```
|
||
|
||
### 入口点
|
||
|
||
1. **`client.py`** - 主客户端入口
|
||
- `AutoToolChatSession`: 通过 SSE 连接 MCP 服务器，调用 LLM，执行工具
|
||
- 支持 OpenAI 兼容模型 (DashScope, Ollama 等)
|
||
|
||
2. **`main.py`** - 使用 FastMCP 的 Demo 服务器
|
||
- 工具：`add()`, `get_weather_by_location()`
|
||
- 资源：`greeting://{name}`
|
||
- 提示词：`greet_user()`
|
||
|
||
3. **`app/mcp_server/server.py`** - OpenManus 风格的 MCP 服务器
|
||
- `MCPServer` 类，支持动态工具注册
|
||
- 内置工具：bash, terminate
|
||
|
||
### 工具系统
|
||
|
||
所有工具继承自 `BaseTool` (位于 `app/tools/base.py`):
|
||
- 必须实现 `async execute(self, **kwargs) -> ToolResult`
|
||
- 工具参数通过 `parameters` 字典定义 (JSON Schema 格式)
|
||
- 结果通过 `ToolResult` 返回，包含 `output`, `error`, `base64_image` 字段
|
||
|
||
### 环境变量配置
|
||
|
||
通过 `.env` 文件配置必需的环境变量：
|
||
```bash
|
||
LLM_API_KEY=<your-api-key>
|
||
APIHZ_ID=<apihz-user-id> # 用于天气 API
|
||
APIHZ_KEY=<apihz-user-key> # 用于天气 API
|
||
```
|
||
|
||
客户端配置 (位于 `client.py`):
|
||
- `LLM_MODEL`: 模型名称 (默认：deepseek-v3)
|
||
- `LLM_BASE_URL`: OpenAI 兼容的 API 端点
|
||
|
||
### 关键设计模式
|
||
|
||
- **MCP Protocol**: 使用 Model Context Protocol 暴露工具
|
||
- **SSE Transport**: 客户端通过 Server-Sent Events 连接
|
||
- **Async Design**: 使用 `asyncio` 进行并发工具执行
|
||
- **Pydantic Models**: 用于数据验证 (`ToolResult`, `BaseTool`)
|