FastAPI MCP 客户端

一个专门设计用于与实现模型上下文协议（MCP）的服务器进行交互的客户端库，该服务器通过服务器发送事件（SSE）实现。此库提供了一种无缝的方式与启用MCP的FastAPI服务进行交互。

安装

# 使用pip安装
pip install fastapi-mcp-client

# 或者使用UV
uv add fastapi-mcp-client

快速开始

import asyncio
from fastapi_mcp_client import MCPClient

async def main():
    async with MCPClient("http://localhost:8000") as client:
        # 调用非流式操作
        result = await client.call_operation("echo", {"message": "Hello, MCP!"})
        print(f"回声结果: {result}")
        
        # 调用流式操作，使用SSE
        stream = await client.call_operation(
            "generate_numbers", 
            {"count": 5},
            stream=True
        )
        
        async for event in stream:
            print(f"事件: {event}")

asyncio.run(main())

功能

• MCP协议支持：完全实现了模型上下文协议
• SSE流式传输：对服务器发送事件（SSE）流式传输的一级支持
• 异步优先设计：完全兼容异步，适用于高性能应用
• 无缝会话管理：处理MCP会话建立和消息传递
• 错误处理：全面的错误处理机制，包括回退机制
• 类型注解：完整的类型提示，以更好地集成IDE并进行验证

运行示例

仓库中包含了帮助您入门的示例。以下是运行它们的方法：

1. 克隆仓库

git clone https://github.com/RooseveltAdvisors/fastapi-mcp-client.git
cd fastapi-mcp-client

2. 设置环境

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate  # 在Windows上: .venv\Scripts\activate

# 安装所有依赖项，包括示例
uv sync --all-extras

3. 启动示例服务器

# 在一个终端中
cd examples/server
python simpler_server.py

这将启动一个具有多个MCP启用端点的FastAPI服务器：

• echo：返回您发送的消息
• generate_numbers：流式传输一系列数字
• search_documents：模拟带有流式传输结果的文档搜索
• calculate：评估简单的数学表达式

4. 运行SSE客户端示例

# 在另一个终端（激活虚拟环境）
cd examples
python sse_example.py

高级用法

自定义客户端配置

from fastapi_mcp_client import MCPClient, MCPClientConfig

config = MCPClientConfig(
    base_url="http://localhost:8000",
    timeout=60.0,
    log_level="DEBUG"
)

async with MCPClient("http://localhost:8000", config=config) as client:
    # 使用自定义配置调用流式工具
    stream = await client.call_operation(
        "generate_numbers", 
        {"count": 10},
        stream=True
    )
    
    async for event in stream:
        print(f"接收事件: {event}")

理解MCP/SSE流程

sequenceDiagram
    participant C as 客户端
    participant S as 服务器

    Note over C,S: 建立SSE连接
    C->>+S: GET /mcp (Accept: text/event-stream)
    S-->>-C: 200 OK (连接打开)
    S-->>C: SSE: data: /mcp/messages/?session_id=XXX

    Note over C: 解析session_id=XXX

    Note over C,S: MCP初始化
    C->>+S: POST /mcp/messages/?session_id=XXX <br> Payload: {method: "initialize", ...}
    S-->>-C: 202 已接受

    Note over C,S: MCP工具调用
    C->>+S: POST /mcp/messages/?session_id=XXX <br> Payload: {method: "tools/call", ...}
    S-->>-C: 202 已接受

    Note over C,S: 流式传输结果
    S-->>C: SSE: data: {result_part_1}
    S-->>C: SSE: data: {result_part_2}
    S-->>C: SSE: data: {final_result}
    Note over S: (关闭SSE连接或发送关闭事件)

示例

查看示例目录获取更多内容：

• 服务器示例：一个简单的FastAPI MCP服务器示例
• SSE示例：带有自定义配置的高级流式传输示例

贡献

欢迎贡献！请随时提交Pull Request。

开发设置

1. 克隆仓库

   git clone https://github.com/RooseveltAdvisors/fastapi-mmcp-client.git
   cd fastapi-mcp-client
   

2. 安装uv

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. 创建并激活虚拟环境

   uv venv
   source .venv/bin/activate  # 在Windows上: .venv\Scripts\activate
   

4. 安装开发依赖项

   uv sync --all-extras
   

5. 运行测试

   pytest
   

Pull Request过程

1. 创建您的功能分支 (git checkout -b feature/amazing-feature)
2. 进行更改并确保测试通过
3. 提交更改 (git commit -m '添加一些惊人的功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开Pull Request

许可证

本项目采用MIT许可证 - 查看LICENSE文件获取详情。

致谢

• 与FastAPI MCP一起构建 - 一个为您的API添加MCP支持的FastAPI扩展