# 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`)