FastMCP Integration Application Demo

FastMCP 集成应用演示

中文说明（中文文档）

本项目演示了如何使用 FastMCP 构建模块化应用，集成 MCP 服务、FastAPI 接口和大模型 Agent 能力。

项目架构

项目采用模块化设计，将不同功能拆分到独立的软件包中：

app/
├── __init__.py
├── api/                 # FastAPI Application Layer
│   ├── __init__.py
│   ├── main.py          # FastAPI main application entry point
│   └── routers/         # API route definitions
│       ├── __init__.py
│       ├── agent.py       # Agent mode routes
│       ├── mcp_resources.py # MCP resource routes
│       └── mcp_tools.py     # MCP tool routes
├── llm/                 # LLM (Large Language Model) Processing Layer
│   ├── __init__.py
│   ├── base.py          # Base LLM class
│   └── openai.py        # OpenAI implementation
└── mcp_server/          # MCP Server Definition Layer
    ├── __init__.py
    ├── base.py          # Base MCP Server class
    ├── run.py           # Script for internal Client connection or direct execution
    └── simple.py        # Simple MCP Server implementation (with tools & resources)
main.py                  # Main entry point (runs API or MCP server)

核心工作流（API 模式）：

1. 独立运行 MCP 服务：使用 python main.py --mode mcp 启动独立的 MCP 服务进程，通过 SSE 传输在指定端口（默认：8001）上监听。
2. 运行 API 服务：使用 python main.py --mode api 启动 FastAPI 服务（监听端口为 8080）。
3. 连接：FastAPI 服务中的 mcp_client 通过 SSE 连接到独立运行的 MCP 服务。
4. 请求处理：前端或其他客户端通过 FastAPI 提供的 HTTP API 与应用交互。
5. 工具/资源/Agent 调用：FastAPI 路由将请求转发给 mcp_client（与 MCP 服务通信）或 llm 模块（与大模型 API 通信）。

功能特性

• 模块化设计：清晰划分职责（API、LLM、MCP），便于扩展和维护。
• 双运行模式：
  • api 模式：运行 FastAPI 服务，需要单独运行 MCP 服务。
  • mcp 模式：直接运行 MCP 服务，供测试或其他客户端连接。
• 大模型集成：支持使用 OpenAI（或其他可扩展的大模型）处理工具输出，或以 Agent 模式执行任务。
• Agent 模式：提供 /api/agent/process 端点，让大模型自主选择并调用 MCP 工具。
• 完整 API：通过 FastAPI 为 MCP 工具、资源和 Agent 功能提供 RESTful 端点。
• 持久连接：API 服务与 MCP 服务保持长期 SSE 连接，以提高效率。

安装

1. 克隆仓库（如有需要）。

2. 安装依赖项（使用 uv 或 pip）：

   # 推荐：使用 uv
   uv pip install -e .
   
   # 或者，使用 pip
   # pip install -e .
   

3. 设置环境变量：

   • 使用大模型功能需要设置 OPENAI_API_KEY 环境变量。
   • 可以在项目根目录中创建 .env 文件并在其中定义该变量：

     OPENAI_API_KEY=sk-...
     

使用方法

运行 API 服务（推荐）

此模式需要先启动独立运行的 MCP 服务。

1. 启动 MCP 服务（在一个终端中）：

   # 使用 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 服务（在另一个终端中）：

   # 监听 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 服务

如果只需运行 MCP 服务（例如，供其他 FastMCP 客户端直接连接）：

# Default: Use SSE transport, listening on 127.0.0.1:8001
python main.py --mode mcp

# Use Standard I/O (stdio) transport
# 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": "Explain the result"}
• MCP 资源（/api/resources）：
  • GET /：列出所有可用资源 URI 及其类型。
  • GET /{resource_path:path}：获取指定资源的内容（例如，GET /api/resources/example/greeting）。
• Agent 模式（/api/agent）：
  • POST /process：让大模型自主处理用户请求，并可能调用工具。请求正文示例：{"prompt": "What is 5 plus 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 中导入并实例化它。

添加新的大模型提供商

1. 在 app/llm/ 目录中创建新的 Python 文件（例如，anthropic.py）。
2. 创建一个继承自 app.llm.base.BaseLLM 的新类。
3. 实现 generate 和 generate_with_tools 方法。
4. 根据需要导入并使用新的大模型类（例如，在 agent.py 中）。

开发

开发时运行 API 服务，可启用热重载：

# Ensure the standalone MCP server is still running
python main.py --mode api --reload