From 4968b18b2c14f021a08c4a0d55157c123c87c130 Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 10:48:01 +0000 Subject: [PATCH] docs: make Chinese README the default --- README.md | 312 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 251 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 789ea7c..76a9362 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,54 @@ -

fastapi-to-mcp

+ +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/tadata-org/fastapi_mcp) · [上游 README](https://github.com/tadata-org/fastapi_mcp/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 -
- Built by Tadata -
- -

- FastAPI-MCP -

- -
-tadata-org%2Ffastapi_mcp | Trendshift -
- -

Expose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!

+

fastapi-to-mcp

+

FastAPI-MCP

+

一个零配置工具，用于自动将 FastAPI 端点公开为模型上下文协议（MCP）工具。

-[![PyPI version](https://img.shields.io/pypi/v/fastapi-mcp?color=%2334D058&label=pypi%20package)](https://pypi.org/project/fastapi-mcp/) +[![PyPI version](https://badge.fury.io/py/fastapi-mcp.svg)](https://pypi.org/project/fastapi-mcp/) [![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-mcp.svg)](https://pypi.org/project/fastapi-mcp/) [![FastAPI](https://img.shields.io/badge/FastAPI-009485.svg?logo=fastapi&logoColor=white)](#) +![](https://badge.mcpx.dev?type=dev 'MCP Dev') [![CI](https://github.com/tadata-org/fastapi_mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/tadata-org/fastapi_mcp/actions/workflows/ci.yml) -[![Coverage](https://codecov.io/gh/tadata-org/fastapi_mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/tadata-org/fastapi_mcp) +[![codecov](https://codecov.io/gh/tadata-org/fastapi_mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/tadata-org/fastapi_mcp)
+

fastapi-mcp-usage

-

fastapi-mcp-usage

+> 注意：最新版本请参阅 [README.md](README.md). +## 特点 -## Features +- **直接集成** - 直接将 MCP 服务器挂载到您的 FastAPI 应用 +- **零配置** - 只需指向您的 FastAPI 应用即可工作 +- **自动发现** - 所有 FastAPI 端点并转换为 MCP 工具 +- **保留模式** - 保留您的请求模型和响应模型的模式 +- **保留文档** - 保留所有端点的文档，就像在 Swagger 中一样 +- **灵活部署** - 将 MCP 服务器挂载到同一应用，或单独部署 +- **ASGI 传输** - 默认使用 FastAPI 的 ASGI 接口直接通信，提高效率 -- **Authentication** built in, using your existing FastAPI dependencies! +## 安装 -- **FastAPI-native:** Not just another OpenAPI -> MCP converter - -- **Zero/Minimal configuration** required - just point it at your FastAPI app and it works - -- **Preserving schemas** of your request models and response models - -- **Preserve documentation** of all your endpoints, just as it is in Swagger - -- **Flexible deployment** - Mount your MCP server to the same app, or deploy separately - -- **ASGI transport** - Uses FastAPI's ASGI interface directly for efficient communication - - -## Hosted Solution - -If you prefer a managed hosted solution check out [tadata.com](https://tadata.com). - -## Installation - -We recommend using [uv](https://docs.astral.sh/uv/), a fast Python package installer: +我们推荐使用 [uv](https://docs.astral.sh/uv/)，一个快速的 Python 包安装器： ```bash uv add fastapi-mcp ``` -Alternatively, you can install with pip: +或者，您可以使用 pip 安装： ```bash pip install fastapi-mcp ``` -## Basic Usage +## 基本用法 -The simplest way to use FastAPI-MCP is to add an MCP server directly to your FastAPI application: +使用 FastAPI-MCP 的最简单方法是直接将 MCP 服务器添加到您的 FastAPI 应用中： ```python from fastapi import FastAPI @@ -74,44 +58,250 @@ app = FastAPI() mcp = FastApiMCP(app) -# Mount the MCP server directly to your FastAPI app +# 直接将 MCP 服务器挂载到您的 FastAPI 应用 mcp.mount() ``` -That's it! Your auto-generated MCP server is now available at `https://app.base.url/mcp`. +就是这样！您的自动生成的 MCP 服务器现在可以在 `https://app.base.url/mcp` 访问。 -## Documentation, Examples and Advanced Usage +## 工具命名 -FastAPI-MCP provides [comprehensive documentation](https://fastapi-mcp.tadata.com/). Additionaly, check out the [examples directory](examples) for code samples demonstrating these features in action. +FastAPI-MCP 使用 FastAPI 路由中的`operation_id`作为 MCP 工具的名称。如果您不指定`operation_id`，FastAPI 会自动生成一个，但这些名称可能比较晦涩。 -## FastAPI-first Approach +比较以下两个端点定义： -FastAPI-MCP is designed as a native extension of FastAPI, not just a converter that generates MCP tools from your API. This approach offers several key advantages: +```python +# 自动生成的 operation_id（类似于 "read_user_users__user_id__get"） +@app.get("/users/{user_id}") +async def read_user(user_id: int): + return {"user_id": user_id} -- **Native dependencies**: Secure your MCP endpoints using familiar FastAPI `Depends()` for authentication and authorization +# 显式 operation_id（工具将被命名为 "get_user_info"） +@app.get("/users/{user_id}", operation_id="get_user_info") +async def read_user(user_id: int): + return {"user_id": user_id} +``` -- **ASGI transport**: Communicates directly with your FastAPI app using its ASGI interface, eliminating the need for HTTP calls from the MCP to your API +为了获得更清晰、更直观的工具名称，我们建议在 FastAPI 路由定义中添加显式的`operation_id`参数。 -- **Unified infrastructure**: Your FastAPI app doesn't need to run separately from the MCP server (though [separate deployment](https://fastapi-mcp.tadata.com/advanced/deploy#deploying-separately-from-original-fastapi-app) is also supported) +要了解更多信息，请阅读 FastAPI 官方文档中关于 [路径操作的高级配置](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/) 的部分。 -This design philosophy ensures minimum friction when adding MCP capabilities to your existing FastAPI services. +## 高级用法 +FastAPI-MCP 提供了多种方式来自定义和控制 MCP 服务器的创建和配置。以下是一些高级用法模式： -## Development and Contributing +### 自定义模式描述 -Thank you for considering contributing to FastAPI-MCP! We encourage the community to post Issues and create Pull Requests. +```python +from fastapi import FastAPI +from fastapi_mcp import FastApiMCP -Before you get started, please see our [Contribution Guide](CONTRIBUTING.md). +app = FastAPI() -## Community +mcp = FastApiMCP( + app, + name="我的 API MCP", + describe_all_responses=True, # 在工具描述中包含所有可能的响应模式 + describe_full_response_schema=True # 在工具描述中包含完整的 JSON 模式 +) -Join [MCParty Slack community](https://join.slack.com/t/themcparty/shared_invite/zt-30yxr1zdi-2FG~XjBA0xIgYSYuKe7~Xg) to connect with other MCP enthusiasts, ask questions, and share your experiences with FastAPI-MCP. +mcp.mount() +``` -## Requirements +### 自定义公开的端点 -- Python 3.10+ (Recommended 3.12) +您可以使用 Open API 操作 ID 或标签来控制哪些 FastAPI 端点暴露为 MCP 工具： + +```python +from fastapi import FastAPI +from fastapi_mcp import FastApiMCP + +app = FastAPI() + +# 仅包含特定操作 +mcp = FastApiMCP( + app, + include_operations=["get_user", "create_user"] +) + +# 排除特定操作 +mcp = FastApiMCP( + app, + exclude_operations=["delete_user"] +) + +# 仅包含具有特定标签的操作 +mcp = FastApiMCP( + app, + include_tags=["users", "public"] +) + +# 排除具有特定标签的操作 +mcp = FastApiMCP( + app, + exclude_tags=["admin", "internal"] +) + +# 结合操作 ID 和标签（包含模式） +mcp = FastApiMCP( + app, + include_operations=["user_login"], + include_tags=["public"] +) + +mcp.mount() +``` + +关于过滤的注意事项： +- 您不能同时使用`include_operations`和`exclude_operations` +- 您不能同时使用`include_tags`和`exclude_tags` +- 您可以将操作过滤与标签过滤结合使用（例如，使用`include_operations`和`include_tags`） +- 当结合过滤器时，将采取贪婪方法。匹配任一标准的端点都将被包含 + +### 与原始 FastAPI 应用分开部署 + +您不限于在创建 MCP 的同一个 FastAPI 应用上提供 MCP 服务。 + +您可以从一个 FastAPI 应用创建 MCP 服务器，并将其挂载到另一个应用上： + +```python +from fastapi import FastAPI +from fastapi_mcp import FastApiMCP + +# 您的 API 应用 +api_app = FastAPI() +# ... 在 api_app 上定义您的 API 端点 ... + +# 一个单独的 MCP 服务器应用 +mcp_app = FastAPI() + +# 从 API 应用创建 MCP 服务器 +mcp = FastApiMCP(api_app) + +# 将 MCP 服务器挂载到单独的应用 +mcp.mount(mcp_app) + +# 现在您可以分别运行两个应用： +# uvicorn main:api_app --host api-host --port 8001 +# uvicorn main:mcp_app --host mcp-host --port 8000 +``` + +### 在 MCP 服务器创建后添加端点 + +如果您在创建 MCP 服务器后向 FastAPI 应用添加端点，您需要刷新服务器以包含它们： + +```python +from fastapi import FastAPI +from fastapi_mcp import FastApiMCP + +app = FastAPI() +# ... 定义初始端点 ... + +# 创建 MCP 服务器 +mcp = FastApiMCP(app) +mcp.mount() + +# 在 MCP 服务器创建后添加新端点 +@app.get("/new/endpoint/", operation_id="new_endpoint") +async def new_endpoint(): + return {"message": "Hello, world!"} + +# 刷新 MCP 服务器以包含新端点 +mcp.setup_server() +``` + +### 与 FastAPI 应用的通信 + +FastAPI-MCP 默认使用 ASGI 传输，这意味着它直接与您的 FastAPI 应用通信，而不需要发送 HTTP 请求。这样更高效，也不需要基础 URL。 + +如果您需要指定自定义基础 URL 或使用不同的传输方法，您可以提供自己的 `httpx.AsyncClient`： + +```python +import httpx +from fastapi import FastAPI +from fastapi_mcp import FastApiMCP + +app = FastAPI() + +# 使用带有特定基础 URL 的自定义 HTTP 客户端 +custom_client = httpx.AsyncClient( + base_url="https://api.example.com", + timeout=30.0 +) + +mcp = FastApiMCP( + app, + http_client=custom_client +) + +mcp.mount() +``` + +## 示例 + +请参阅 [examples](examples) 目录以获取完整示例。 + +## 使用 SSE 连接到 MCP 服务器 + +一旦您的集成了 MCP 的 FastAPI 应用运行，您可以使用任何支持 SSE 的 MCP 客户端连接到它，例如 Cursor： + +1. 运行您的应用。 + +2. 在 Cursor -> 设置 -> MCP 中，使用您的 MCP 服务器端点的URL（例如，`http://localhost:8000/mcp`）作为 sse。 + +3. Cursor 将自动发现所有可用的工具和资源。 + +## 使用 [mcp-proxy stdio](https://github.com/sparfenyuk/mcp-proxy?tab=readme-ov-file#1-stdio-to-sse) 连接到 MCP 服务器 + +如果您的 MCP 客户端不支持 SSE，例如 Claude Desktop： + +1. 运行您的应用。 + +2. 安装 [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy?tab=readme-ov-file#installing-via-pypi)，例如：`uv tool install mcp-proxy`。 + +3. 在 Claude Desktop 的 MCP 配置文件（`claude_desktop_config.json`）中添加： + +在 Windows 上： +```json +{ + "mcpServers": { + "my-api-mcp-proxy": { + "command": "mcp-proxy", + "args": ["http://127.0.0.1:8000/mcp"] + } + } +} +``` +在 MacOS 上： +```json +{ + "mcpServers": { + "my-api-mcp-proxy": { + "command": "/Full/Path/To/Your/Executable/mcp-proxy", + "args": ["http://127.0.0.1:8000/mcp"] + } + } +} +``` +通过在终端运行`which mcp-proxy`来找到 mcp-proxy 的路径。 + +4. Claude Desktop 将自动发现所有可用的工具和资源 + +## 开发和贡献 + +感谢您考虑为 FastAPI-MCP 做出贡献！我们鼓励社区发布问题和拉取请求。 + +在开始之前，请参阅我们的 [贡献指南](CONTRIBUTING.md)。 + +## 社区 + +加入 [MCParty Slack 社区](https://join.slack.com/t/themcparty/shared_invite/zt-30yxr1zdi-2FG~XjBA0xIgYSYuKe7~Xg)，与其他 MCP 爱好者联系，提问，并分享您使用 FastAPI-MCP 的经验。 + +## 要求 + +- Python 3.10+（推荐3.12） - uv -## License +## 许可证 -MIT License. Copyright (c) 2025 Tadata Inc. +MIT License. Copyright (c) 2024 Tadata Inc.