内容
# FastMCP 集成应用演示
**[中文说明 (Chinese Documentation)](README_zh.md)**
本项目演示了一个基于 FastMCP 构建的模块化应用，集成了 MCP 服务器、FastAPI 接口和 LLM Agent 功能。
## 项目架构
该项目采用模块化设计，将不同的功能分离到不同的包中：
```
app/
├── __init__.py
├── api/ # FastAPI 应用层
│ ├── __init__.py
│ ├── main.py # FastAPI 主应用入口
│ └── routers/ # API 路由定义
│ ├── __init__.py
│ ├── agent.py # 代理模式路由
│ ├── mcp_resources.py # MCP 资源路由
│ └── mcp_tools.py # MCP 工具路由
├── llm/ # LLM（大型语言模型）处理层
│ ├── __init__.py
│ ├── base.py # 基础 LLM 类
│ └── openai.py # OpenAI 实现
└── mcp_server/ # MCP 服务器定义层
├── __init__.py
├── base.py # 基础 MCP 服务器类
├── run.py # 内部客户端连接或直接执行的脚本
└── simple.py # 简单的 MCP 服务器实现（带工具和资源）
main.py # 主入口（运行 API 或 MCP 服务器）
```
**核心工作流程（API 模式）：**
1. **独立运行 MCP 服务器**：使用 `python main.py --mode mcp` 启动一个独立的 MCP 服务器进程，监听指定端口（默认：8001），使用 SSE 传输。
2. **运行 API 服务器**：使用 `python main.py --mode api` 启动 FastAPI 服务器（监听 8080）。
3. **连接**：FastAPI 服务器中的 `mcp_client` 通过 SSE 连接到独立运行的 MCP 服务器。
4. **请求处理**：前端或其他客户端通过 FastAPI 提供的 HTTP API 与应用进行交互。
5. **工具/资源/代理调用**：FastAPI 路由将请求转发给 `mcp_client`（与 MCP 服务器通信）或 `llm` 模块（与 LLM API 通信）。
## 特性
- **模块化设计**：清晰的关注点分离（API、LLM、MCP），便于扩展和维护。
- **双运行模式**：
- `api` 模式：运行 FastAPI 服务器，需要 **单独运行** 的 MCP 服务器。
- `mcp` 模式：直接运行 MCP 服务器，便于测试或其他客户端连接。
- **LLM 集成**：支持使用 OpenAI（或其他可扩展的 LLM）处理工具输出或以 Agent 模式执行。
- **Agent 模式**：提供 `/api/agent/process` 端点，让 LLM 自主选择和调用 MCP 工具。
- **完整 API**：通过 FastAPI 提供 MCP 工具、资源和 Agent 功能的 RESTful 端点。
- **持久连接**：API 服务器与 MCP 服务器保持长时间的 SSE 连接，以提高效率。
## 安装
1. **克隆仓库**（如果需要）。
2. **安装依赖**（使用 uv 或 pip）：
```bash
# 推荐：使用 uv
uv pip install -e .
# 或者，使用 pip
# pip install -e .
```
3. **设置环境变量**：
- `OPENAI_API_KEY` 环境变量是使用 LLM 功能所必需的。
- 您可以在项目根目录创建一个 `.env` 文件并在其中定义：
```dotenv
OPENAI_API_KEY=sk-...
```
## 使用方法
### 运行 API 服务器（推荐）
此模式需要**首先启动独立的 MCP 服务器**。
1. **启动 MCP 服务器（在一个终端中）**：
```bash
# 使用 SSE 传输，监听 127.0.0.1:8001（默认）
python main.py --mode mcp
# 或指定不同的主机和端口
# python main.py --mode mcp --mcp-host 0.0.0.0 --mcp-port 8002
```
2. **启动 API 服务器（在另一个终端中）**：
```bash
# 监听 0.0.0.0:8080（默认）
python main.py --mode api
# 使用不同的端口或启用热重载（用于开发）
# python main.py --mode api --port 9000 --reload
```
现在可以通过 `http://localhost:8080`（或您指定的端口）访问 API 服务器。它将自动连接到步骤 1 中启动的 MCP 服务器（默认连接：`http://localhost:8001/sse`）。
### 直接运行 MCP Server
如果您只需要运行 MCP Server（例如，供其他 FastMCP 客户端直接连接）：
```bash
```
# 默认：使用 SSE 传输，监听 127.0.0.1:8001
python main.py --mode mcp
# 使用标准输入/输出 (stdio) 传输
# python main.py --mode mcp --mcp-transport stdio
```
## API 端点（通过 API 服务器访问）
API 服务器运行在 `http://localhost:8080`（默认）。
- **MCP 工具** (`/api/tools`):
- `GET /`: 列出所有可用工具及其参数。
- `POST /{tool_name}`: 调用特定工具。示例请求体：`{"params": {"a": 5, "b": 3}, "use_llm": true, "system_message": "解释结果"}`
- **MCP 资源** (`/api/resources`):
- `GET /`: 列出所有可用资源的 URI 及其类型。
- `GET /{resource_path:path}`: 获取特定资源的内容（例如，`GET /api/resources/example/greeting`）。
- **代理模式** (`/api/agent`):
- `POST /process`: 让 LLM 自主处理用户请求，可能会调用工具。示例请求体：`{"prompt": "5 加 3 等于多少？"}`
- **健康检查**:
- `GET /health`: 检查 API 服务器是否正在运行。
- `GET /api/tools/health`: 检查 API 服务器与 MCP 服务器之间的连接状态。
## 扩展应用程序
### 添加新工具
1. 在 `app/mcp_server/simple.py` 中扩展 `BaseMCPServer`（或创建一个新的服务器文件）。
2. 在 `_register_tools` 方法中使用 `@self.mcp.tool()` 装饰器定义新工具。
3. 如果你创建了一个新的服务器文件，请在 `app/mcp_server/run.py` 中导入并实例化它。
### 添加新的 LLM 提供者
1. 在 `app/llm/` 目录中创建一个新的 Python 文件（例如，`anthropic.py`）。
2. 创建一个继承自 `app.llm.base.BaseLLM` 的新类。
3. 实现 `generate` 和 `generate_with_tools` 方法。
4. 在需要的地方导入并使用新的 LLM 类（例如，在 `agent.py` 中）。
## 开发
在运行API服务器进行开发时启用热重载：
```bash
# 确保独立的 MCP Server 仍在运行
python main.py --mode api --reload
```
MCP 市场