# https://github.com/PrefectHQ/fastmcp 项目说明书

生成时间：2026-06-21 09:14:58 UTC

## 目录

- [Framework Overview & Provider Architecture](#page-1)
- [Authentication, OAuth Providers & Authorization](#page-2)
- [Middleware, Tools, Tasks & Request Lifecycle](#page-3)
- [Transports, Proxy Clients, Schemas, Apps & Transforms](#page-4)

<a id='page-1'></a>

## Framework Overview & Provider Architecture

### 相关页面

相关主题：[Authentication, OAuth Providers & Authorization](#page-2), [Middleware, Tools, Tasks & Request Lifecycle](#page-3), [Transports, Proxy Clients, Schemas, Apps & Transforms](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/PrefectHQ/fastmcp/blob/main/README.md)
- [fastmcp_slim/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/README.md)
- [fastmcp_slim/fastmcp/server/providers/__init__.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/__init__.py)
- [fastmcp_slim/fastmcp/server/providers/base.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/base.py)
- [fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py)
- [fastmcp_slim/fastmcp/server/providers/aggregate.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/aggregate.py)
- [fastmcp_slim/fastmcp/server/providers/fastmcp_provider.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/fastmcp_provider.py)
- [fastmcp_slim/fastmcp/server/providers/openapi/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/openapi/README.md)
- [fastmcp_slim/fastmcp/contrib/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/README.md)
- [fastmcp_slim/fastmcp/contrib/component_manager/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/component_manager/README.md)
- [fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md)
- [fastmcp_slim/fastmcp/cli/run.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/cli/run.py)
- [examples/fastmcp_config_demo/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/examples/fastmcp_config_demo/README.md)
- [examples/apps/qr_server/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/examples/apps/qr_server/README.md)

</details>

# 框架总览与 Provider 架构

## 一、FastMCP 框架定位与核心能力

FastMCP 是一个用于构建 Model Context Protocol（MCP）服务器与客户端的 Python 框架，目标是让开发者能够将普通的 Python 函数、REST/OpenAPI 服务或远程 MCP 服务器统一封装为对大语言模型友好的工具、资源与提示词（prompts）。根据 [README.md](https://github.com/PrefectHQ/fastmcp/blob/main/README.md) 的描述，框架同时提供三个面向用户的核心层：

- **Servers（服务器层）**：将 Python 函数包装为符合 MCP 规范的 tools、resources、prompts；
- **Clients（客户端层）**：连接任何 MCP 服务器，完整支持协议；
- **Apps（应用层）**：为工具提供可交互的 UI，直接在对话窗口中渲染。

`fastmcp_slim` 是核心包的精简版，与完整版共享同一套 API，但只包含运行时所必需的最少依赖（参见 [fastmcp_slim/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/README.md)）。框架的整体目标可以概括为：让 MCP 服务器的开发像写普通 Python 函数一样简单，同时保持协议层面的完整性与生产可用性。

## 二、Provider 体系结构

FastMCP 的 Provider 体系是框架内部最关键的抽象之一，它将"组件来源"与"组件消费方"解耦，使得同一个 `FastMCP` 服务器可以同时挂载多种类型的工具来源（本地函数、远端 MCP 服务器、OpenAPI 接口、Aggregate 聚合等）。根据 [fastmcp_slim/fastmcp/server/providers/__init__.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/__init__.py) 中导出的内容可知，Provider 是模块级别的核心抽象之一。

### 1. Provider 基类与契约

[fastmcp_slim/fastmcp/server/providers/base.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/base.py) 定义了所有 Provider 必须实现的接口契约，包括组件枚举、生命周期管理以及与 `FastMCP` 引擎的回调钩子。任何 Provider 子类都必须遵循这一契约，从而确保新增 Provider 不需要修改核心引擎代码。

### 2. 核心 Provider 类型

框架内置了多种 Provider 实现，覆盖最常见的使用场景：

| Provider | 主要职责 | 关键源文件 |
| --- | --- | --- |
| `LocalProvider` | 暴露以装饰器（`@tool`、`@resource`、`@prompt`）注册的本地 Python 函数 | [fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py) |
| `FastMCPProvider` | 把一个完整的 `FastMCP` 实例以 Provider 形式接入到上层服务器中，便于嵌套组合 | [fastmcp_slim/fastmcp/server/providers/fastmcp_provider.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/fastmcp_provider.py) |
| `AggregateProvider` | 组合多个 Provider，统一对外暴露组件集合 | [fastmcp_slim/fastmcp/server/providers/aggregate.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/aggregate.py) |
| OpenAPI Provider | 将 OpenAPI 规范转换为 MCP 工具 | [fastmcp_slim/fastmcp/server/providers/openapi/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/providers/openapi/README.md) |

## 三、Provider 协作与数据流

下图展示了 Provider 与 FastMCP 服务器之间的典型数据流：客户端发起 `tools/list` 或 `tools/call` 请求时，服务器会委托给内部聚合后的 Provider 集合，各 Provider 负责按需枚举并执行其对应的组件。

```mermaid
flowchart LR
    Client[MCP 客户端] -->|tools/list, tools/call| Server[FastMCP 服务器]
    Server -->|枚举 / 调用| Aggregate[AggregateProvider]
    Aggregate --> Local[LocalProvider]
    Aggregate --> FastMCP2[FastMCPProvider]
    Aggregate --> OpenAPI[OpenAPI Provider]
    Aggregate --> Contrib[Contrib Provider]
    Contrib --> CM[component_manager]
    Contrib --> Mixin[mcp_mixin]
    Local --> Func1[Python 函数工具]
    FastMCP2 --> Sub[嵌套的 FastMCP 实例]
    OpenAPI --> REST[REST / OpenAPI 接口]
```

这一分层结构带来的核心收益是：新增功能无需改动核心 `FastMCP` 类，只要实现一个新的 Provider 即可被自动注册到 `AggregateProvider` 中。

## 四、扩展机制与社区生态

FastMCP 通过 `contrib` 包提供社区扩展通道，允许第三方模块独立演进而无需侵入主仓库。根据 [fastmcp_slim/fastmcp/contrib/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/README.md) 的说明，`contrib` 模块可能与核心库拥有不同的稳定性保证与依赖要求，使用时需要自行评估风险。

### 典型 Contrib 模块

- **component_manager**：通过 HTTP 端点启用 / 禁用工具、资源与提示词，参见 [fastmcp_slim/fastmcp/contrib/component_manager/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/component_manager/README.md)。
- **mcp_mixin**：通过类继承与装饰器批量注册组件，参见 [fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md)。

### 部署与 CLI 入口

[fastmcp_slim/fastmcp/cli/run.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/cli/run.py) 中的 `create_client_server` 与 `create_mcp_config_server` 等函数负责把 URL、MCPConfig 等外部资源转换为可运行的 FastMCP 服务器实例，并与 `fastmcp run` 等 CLI 命令协同工作。结合 [examples/fastmcp_config_demo/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/examples/fastmcp_config_demo/README.md)，用户可以通过 `fastmcp.json` 描述入口、环境与部署参数，从而以声明式方式启动服务器。

## 五、与社区关注点的衔接

当前社区讨论集中在若干与 Provider 体系紧密相关的话题：

- **工具级超时**：[#4304](https://github.com/PrefectHQ/fastmcp/issues/4304) 提议在 `FastMCP(default_tool_timeout=...)` 上提供服务器级默认值，以减少在 `LocalProvider` 下大量 `@tool(timeout=...)` 的重复样板代码。
- **OAuth 多租户与 Keycloak**：[#1802](https://github.com/PrefectHQ/fastmcp/issues/1802) 与 [#1918](https://github.com/PrefectHQ/fastmcp/issues/1918) 显示现有 Auth Provider 尚未覆盖多租户与 Keycloak 场景，会影响 FastMCPProvider 在企业环境中的可组合性。
- **破坏性能力防护**：[#4318](https://github.com/PrefectHQ/fastmcp/issues/4318) 指出当前 Provider 注册组件时缺乏对 shell 执行、文件删除等危险能力的声明机制，需要在 Provider 契约层面引入能力标签或策略层。

这些讨论表明，Provider 抽象既是当前扩展能力的核心，也是未来安全与可治理特性需要重点演进的位置。

## 参见

- 服务器基础与组件注册：[README.md](https://github.com/PrefectHQ/fastmcp/blob/main/README.md)
- 客户端协议接入：[fastmcp_slim/fastmcp/client/mixins/tools.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/tools.py)
- 鉴权 Provider：[fastmcp_slim/fastmcp/server/auth/providers/jwt.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/jwt.py)
- 应用层示例：[examples/apps/qr_server/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/examples/apps/qr_server/README.md)

---

<a id='page-2'></a>

## Authentication, OAuth Providers & Authorization

### 相关页面

相关主题：[Framework Overview & Provider Architecture](#page-1), [Transports, Proxy Clients, Schemas, Apps & Transforms](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [fastmcp_slim/fastmcp/server/auth/providers/github.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/github.py)
- [fastmcp_slim/fastmcp/server/auth/providers/google.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/google.py)
- [fastmcp_slim/fastmcp/server/auth/providers/auth0.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/auth0.py)
- [fastmcp_slim/fastmcp/server/auth/providers/clerk.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/clerk.py)
- [fastmcp_slim/fastmcp/server/auth/providers/azure.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/azure.py)
- [fastmcp_slim/fastmcp/server/auth/providers/discord.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/discord.py)
- [fastmcp_slim/fastmcp/server/auth/providers/jwt.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/jwt.py)
- [fastmcp_slim/fastmcp/server/auth/providers/introspection.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/introspection.py)
- [fastmcp_slim/fastmcp/server/auth/providers/debug.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/debug.py)
- [fastmcp_slim/fastmcp/client/oauth_callback.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/oauth_callback.py)
- [examples/auth/mounted/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/examples/auth/mounted/README.md)
- [examples/auth/authkit/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/examples/auth/authkit/README.md)
- [examples/auth/github_oauth/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/examples/auth/github_oauth/README.md)
</details>

# Authentication, OAuth Providers & Authorization

## 概述与设计目标

FastMCP 的认证与授权层为远程 MCP 服务器提供了一套基于 OAuth 2.0 / OIDC 的保护机制。其核心目标是让服务器作者在 **最小配置** 下即可对接主流身份提供方（IdP），同时保留对底层代理行为、令牌校验流程与同意（consent）流程的完全控制。FastMCP 不强制使用单一授权模式，而是为每种 IdP 提供开箱即用的"Provider"类（通常继承自 `OAuthProxy` 或 `OIDCProxy`），并通过 `TokenVerifier` 抽象统一令牌校验入口 资料来源：[fastmcp_slim/fastmcp/server/auth/providers/github.py:1-40]()。

最新版本 v3.4.2 修复了 JWT 兼容性问题：现在来自 Clerk 等提供商的令牌在 JWS 头中携带私有非关键参数（如 `cat`）时不再被提前拒绝，仅当出现未声明的"关键"头参数时才会拒绝。这降低了与第三方 IdP 互操作的摩擦 资料来源：[GitHub Release v3.4.2](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.2)。

## 核心架构：OAuth 代理与令牌验证

FastMCP 的认证实现采用 **OAuth Proxy 模式**：本地服务器对 MCP 客户端表现为一个标准的 OAuth 2.0 授权服务器，但实际登录、令牌发放与用户信息获取都透明地代理到上游 IdP。该模式同时支持 DCR（Dynamic Client Registration）与 CIMD（Client ID Metadata Document）两种客户端发现方式，便于与 Claude Integrations、MCP Inspector 等不同客户端集成 资料来源：[fastmcp_slim/fastmcp/server/auth/providers/auth0.py:1-60]()。

客户端在完成浏览器授权后，由内置的 `create_callback_html` 与 Starlette 回调服务器渲染统一风格的 HTML 响应，显示认证成功/失败状态与目标服务 URL 资料来源：[fastmcp_slim/fastmcp/client/oauth_callback.py:38-60]()。

```mermaid
sequenceDiagram
    participant MCP_Client
    participant FastMCP_Server
    participant Upstream_IdP
    MCP_Client->>FastMCP_Server: 请求受保护资源
    FastMCP_Server-->>MCP_Client: 401 + OAuth 元数据 (RFC 8414)
    MCP_Client->>FastMCP_Server: 发起授权码流程
    FastMCP_Server->>Upstream_IdP: 代理到上游授权端点
    Upstream_IdP-->>FastMCP_Server: 授权码
    FastMCP_Server->>Upstream_IdP: 交换 access_token
    FastMCP_Server-->>MCP_Client: 颁发 FastMCP 自己的 JWT
    MCP_Client->>FastMCP_Server: 携带 Bearer Token 访问
    FastMCP_Server->>FastMCP_Server: TokenVerifier 验证
```

令牌校验支持三种策略：本地 JWT 验签（`JWTVerifier`）、RFC 7662 令牌内省（`IntrospectionTokenVerifier`）以及完全委托给用户回调的 `DebugTokenVerifier`，后者默认接受所有非空令牌，仅用于测试 资料来源：[fastmcp_slim/fastmcp/server/auth/providers/debug.py:18-42]()。

## 内置 OAuth 提供商一览

FastMCP 为常见 IdP 提供了即用型 Provider。下表按授权模式（OAuth Proxy / OIDC Proxy）与令牌类型（JWT / 不透明）整理了仓库内置实现：

| Provider | 基类 | 令牌校验方式 | 关键差异 |
|---|---|---|---|
| `GitHubProvider` | `OAuthProxy` | `GitHubTokenVerifier` 调用 GitHub API | 默认 scopes `["user"]`，可缓存验证结果 资料来源：[providers/github.py:13-48]() |
| `GoogleProvider` | `OAuthProxy` | 透明代理 + Google `tokeninfo` API | 内置 `email`/`profile` 简写别名映射 资料来源：[providers/google.py:55-71]() |
| `Auth0Provider` | `OIDCProxy` | OIDC discovery + JWT 验签 | 依赖 `config_url` 发现端点 资料来源：[providers/auth0.py:1-50]() |
| `ClerkProvider` | `OAuthProxy` | `ClerkTokenVerifier` 内省 + userinfo | v3.4.2 后容忍 Clerk 私有 JWS 头 资料来源：[providers/clerk.py:1-30]() |
| `AzureProvider` | `OAuthProxy` | OIDC + 智能 OIDC 范围剥离 | 处理 Microsoft Entra 范围前缀 资料来源：[providers/azure.py:23-43]() |
| `DiscordProvider` | `OAuthProxy` | `DiscordTokenVerifier` 调用 tokeninfo | scopes 默认 `["identify"]` 资料来源：[providers/discord.py:18-50]() |
| `JWTVerifier` / `IntrospectionTokenVerifier` | `TokenVerifier` | 本地验签 / RFC 7662 | 用于自建或非 DCR IdP 资料来源：[providers/jwt.py:1-40]()、[providers/introspection.py:1-60]() |

所有 Provider 都接受统一的 `base_url`、`client_storage`、`jwt_signing_key`、`require_authorization_consent` 等参数，便于在多环境中复用同一套配置 资料来源：[providers/github.py:55-100]()。

## 高级场景：挂载、多租户与已知限制

### 多提供商挂载

通过 Starlette 挂载，多个受 OAuth 保护的服务可以共存于同一进程；每个子应用通过 RFC 8414 路径感知发现端点暴露自己的元数据，例如 `/.well-known/oauth-authorization-server/api/mcp/github` 资料来源：[examples/auth/mounted/README.md:5-20]()。此时各 Provider 的回调路径需包含挂载前缀（如 `/api/mcp/github/auth/callback/github`），开发环境常用环境变量 `FASTMCP_SERVER_AUTH_<PROVIDER>_*` 注入凭据 资料来源：[examples/auth/mounted/README.md:23-38]()。

### AuthKit / DCR 集成

`AuthKit`（基于 WorkOS）示例演示了如何将 JWT 的 `aud` 声明自动绑定到 MCP 资源 URL：服务器启动时打印资源 URL，开发者只需将其粘贴到 WorkOS Dashboard 的"MCP 资源指示符"中，并启用 DCR 或 CIMD 即可完成接入 资料来源：[examples/auth/authkit/README.md:5-18]()。

### 已知社区问题

- **多租户支持缺失**：当前 `OAuthProxy` 只能配置单一上游授权服务器，难以按租户路由（#1802，社区高互动议题）。
- **Keycloak 支持**：仍需通过 DCR 自建，社区在 #1918 中提出官方 Provider 需求。
- **CIMD 动态端口**：`http://localhost/callback` 形式的回环地址在动态端口场景下被验证逻辑拒绝，与 RFC 8252 §7.3 不符（#3588）。
- **MCP Inspector 之外的客户端**：`/mcp/sse` 等路径下的 OAuth 握手在与 Claude Integrations 或 FastMCP Client 通信时仍存在差异（#972），建议在生产前完成端到端验证。
- **完整 OAuth 2.1 授权**：#825 长期跟踪从当前 Bearer Token 模型向完整 OAuth 2.1 授权流程的演进。

### 失败模式与最佳实践

- **令牌缓存**：对 GitHub 等不透明令牌 Provider，务必设置合理的 `cache_ttl_seconds` 与 `max_cache_size`，避免对上游 API 的重复调用耗尽配额 资料来源：[providers/github.py:35-48]()。
- **同意流程**：`require_authorization_consent` 接受 `True / False / "remember" / "external"`；当上游 IdP 已处理同意时可显式传 `"external"` 以抑制警告 资料来源：[providers/github.py:70-100]()。
- **SSRF 防护**：JWT 验签链路内置 `ssrf_safe_fetch`，禁止对任意公网 JWKS 端点发起请求，降低服务端请求伪造风险 资料来源：[providers/jwt.py:1-30]()。
- **资源指示符**：当服务器以子路径挂载时，应显式设置 `resource_base_url`，确保颁发给客户端的 JWT 正确携带资源受众。

## See Also

- [Server Configuration 与 `fastmcp.json`](https://gofastmcp.com/docs/deployment/server-configuration)
- [Bearer Token 认证指南](https://gofastmcp.com/servers/auth/bearer)
- [v3.4.2 Release Notes](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.2)

---

<a id='page-3'></a>

## Middleware, Tools, Tasks & Request Lifecycle

### 相关页面

相关主题：[Framework Overview & Provider Architecture](#page-1), [Transports, Proxy Clients, Schemas, Apps & Transforms](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [fastmcp_slim/fastmcp/server/middleware/__init__.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/middleware/__init__.py)
- [fastmcp_slim/fastmcp/server/middleware/middleware.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/middleware/middleware.py)
- [fastmcp_slim/fastmcp/server/middleware/caching.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/middleware/caching.py)
- [fastmcp_slim/fastmcp/server/middleware/rate_limiting.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/middleware/rate_limiting.py)
- [fastmcp_slim/fastmcp/server/middleware/logging.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/middleware/logging.py)
- [fastmcp_slim/fastmcp/server/middleware/timing.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/middleware/timing.py)
- [fastmcp_slim/fastmcp/utilities/json_schema_type.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema_type.py)
- [fastmcp_slim/fastmcp/server/auth/providers/jwt.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/jwt.py)
</details>

# 中间件、工具、任务与请求生命周期

## 概述

FastMCP 的服务端请求处理管道由 **工具（Tools）**、**任务（Tasks）** 与 **中间件（Middleware）** 三大抽象构成。工具把用户函数暴露给 LLM 客户端；任务为长耗时操作提供异步执行通道；中间件则负责注入缓存、限流、日志、计时等横切逻辑。本页基于 `fastmcp/server/middleware/` 与相关工具模块说明三者的协作关系、社区反馈的局限与典型故障模式。

## 请求生命周期

请求从抵达 FastMCP 直至返回客户端，按以下顺序流转：

1. **认证阶段**：服务端校验请求中携带的访问令牌（如 JWT）。资料来源：[fastmcp_slim/fastmcp/server/auth/providers/jwt.py:1-60]()
2. **消息分发**：已认证的 JSON-RPC 消息进入请求处理循环。
3. **中间件链**：按 `add_middleware()` 的注册顺序触发钩子（前置 → 调用 → 后置）。资料来源：[fastmcp_slim/fastmcp/server/middleware/middleware.py:1-120]()
4. **工具/资源/提示执行**：根据 method 名称解析并调用用户注册的处理函数。
5. **响应返回**：结果经中间件后置钩子包装后序列化返回。

```mermaid
sequenceDiagram
    participant Client
    participant Auth as Auth
    participant MW as Middleware Chain
    participant Tool as Tool/Task
    Client->>Auth: 携带 Bearer Token
    Auth-->>Client: 401 或放行
    Client->>MW: 已认证消息
    MW->>MW: on_message 前置
    MW->>Tool: 调用或调度为 Task
    Tool-->>MW: 结果 / 超时 / 异常
    MW->>MW: on_message 后置
    MW-->>Client: JSON-RPC 响应
```

## 中间件系统

中间件通过 `add_middleware()` 注册，继承 `Middleware` 基类并实现 `on_message`、工具调用等钩子。资料来源：[fastmcp_slim/fastmcp/server/middleware/middleware.py:1-200]()

### 内置中间件

- `LoggingMiddleware`：结构化日志，位于 [fastmcp_slim/fastmcp/server/middleware/logging.py:1-80]()。
- `TimingMiddleware`：记录工具调用耗时，位于 [fastmcp_slim/fastmcp/server/middleware/timing.py:1-80]()。
- `CachingMiddleware`：缓存工具结果，避免重复计算，位于 [fastmcp_slim/fastmcp/server/middleware/caching.py:1-150]()。
- `RateLimitingMiddleware` / `SlidingWindowRateLimitingMiddleware`：按 `get_client_id(ctx)` 限制调用频率，位于 [fastmcp_slim/fastmcp/server/middleware/rate_limiting.py:1-200]()。

### 社区已知的中间件问题

- **缓存中间件在 v3.4.0+ 签名不兼容**：缓存未命中时 `FastMCP._run_middleware` 内部包装函数抛出 `TypeError: ... unexpected keyword argument 'context'`，见 [#4300](https://github.com/PrefectHQ/fastmcp/issues/4300)。
- **`RateLimitingMiddleware.get_client_id` 仅接受同步可调用对象**：传入 `async` 函数会被静默忽略，限流形同虚设，见 [#4320](https://github.com/PrefectHQ/fastmcp/issues/4320)。
- **`on_message` 不覆盖未认证请求**：认证失败的消息在中间件运行前被直接拒绝，无法记录或计量，见 [#4309](https://github.com/PrefectHQ/fastmcp/issues/4309)。

### 使用模式

```python
from fastmcp import FastMCP
from fastmcp.server.middleware import (
    LoggingMiddleware, TimingMiddleware,
    CachingMiddleware, RateLimitingMiddleware,
)

mcp = FastMCP("Demo")
mcp.add_middleware(LoggingMiddleware())
mcp.add_middleware(TimingMiddleware())
mcp.add_middleware(CachingMiddleware())
mcp.add_middleware(RateLimitingMiddleware(get_client_id=lambda ctx: ctx.client_id))
```

## 工具与任务

### 工具（Tools）

通过 `@tool()` 装饰器注册。装饰器接受 `timeout`（秒）等参数；当超过设定时间，FastMCP 记录警告并抛出错误码 `-32000` 的 `McpError`。社区已提出两项增强请求：

- **服务器级默认超时**：在 `FastMCP(default_tool_timeout=...)` 处统一声明，避免在数十个工具上重复书写，见 [#4304](https://github.com/PrefectHQ/fastmcp/issues/4304)。
- **可定制的超时错误**：当前错误信息为硬编码，希望提供钩子或工厂函数，见 [#4305](https://github.com/PrefectHQ/fastmcp/issues/4305)。

### 任务（Tasks）

任务提供后台异步执行能力，常用于耗时较长的操作。当工具被标记为 `task=True` 时，调用立即返回任务句柄，客户端可稍后轮询结果。

### 工具输出 Schema 解析

注册工具时，`outputSchema` 经 `json_schema_to_type` 转换为 Python 类型辅助客户端调用。资料来源：[fastmcp_slim/fastmcp/utilities/json_schema_type.py:1-120]()。需要注意的是，自引用 `$ref` 的递归结构会触发 `RecursionError`，目前仍是已知缺陷，见 [#4306](https://github.com/PrefectHQ/fastmcp/issues/4306)。

## 常见故障模式

- **缓存中间件崩溃**：升级至 v3.4.0+ 后任何缓存未命中都会抛出 `TypeError`，见 [#4300](https://github.com/PrefectHQ/fastmcp/issues/4300)。
- **限流未生效**：传入了异步 `get_client_id` 但类型签名仅接受同步函数，见 [#4320](https://github.com/PrefectHQ/fastmcp/issues/4320)。
- **未认证请求不可观测**：`on_message` 在认证后才运行，见 [#4309](https://github.com/PrefectHQ/fastmcp/issues/4309)。
- **工具超时错误不可定制**：错误信息与日志均为硬编码，见 [#4305](https://github.com/PrefectHQ/fastmcp/issues/4305)。
- **`outputSchema` 递归 `$ref` 触发 `RecursionError`**，见 [#4306](https://github.com/PrefectHQ/fastmcp/issues/4306)。
- **缺少服务器级 `default_tool_timeout`**，见 [#4304](https://github.com/PrefectHQ/fastmcp/issues/4304)。

## 参见

- 认证与令牌校验：[fastmcp_slim/fastmcp/server/auth/providers/jwt.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/jwt.py)
- OAuth 回调处理：[fastmcp_slim/fastmcp/client/oauth_callback.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/oauth_callback.py)
- 调试 Token 校验器：[fastmcp_slim/fastmcp/server/auth/providers/debug.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/providers/debug.py)

---

<a id='page-4'></a>

## Transports, Proxy Clients, Schemas, Apps & Transforms

### 相关页面

相关主题：[Framework Overview & Provider Architecture](#page-1), [Middleware, Tools, Tasks & Request Lifecycle](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [fastmcp_slim/fastmcp/client/mixins/tools.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/tools.py)
- [fastmcp_slim/fastmcp/client/mixins/resources.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/resources.py)
- [fastmcp_slim/fastmcp/client/oauth_callback.py](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/oauth_callback.py)
- [examples/apps/qr_server/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/examples/apps/qr_server/README.md)
- [fastmcp_slim/fastmcp/contrib/component_manager/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/component_manager/README.md)
- [README.md](https://github.com/PrefectHQ/fastmcp/blob/main/README.md)
- [fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md)

</details>

# Transports、Proxy Clients、Schemas、Apps 与 Transforms

## 1. 概览与职责划分

FastMCP 是构建 Model Context Protocol (MCP) 服务器与客户端的 Python 框架，核心抽象围绕**传输 (Transports)**、**代理客户端 (Proxy Clients)**、**模式 (Schemas)**、**Apps (MCP Apps)** 与 **Transforms** 五大支柱展开。README 将其定位为"MCP 服务器的事实标准构建方式"，明确 **Servers** 将 Python 函数包装为 MCP 兼容的 tools、resources 与 prompts，**Clients** 提供完整协议支持以连接任意服务器，**Apps** 则允许为工具赋予交互式 UI。资料来源：[README.md](https://github.com/PrefectHQ/fastmcp/blob/main/README.md)。

从客户端视角看，传输层维护与远端服务器的物理连接与会话状态；代理客户端允许一个 FastMCP 实例把对远端 MCP 服务的调用映射为本地工具与资源；模式层定义 tools/resources/prompts 的输入输出结构以及 JSON Schema 的转换；Apps 层在工具调用结果之上提供 HTML/iframe 形式的交互式界面；Transforms 则处理能力裁剪、组件启停、参数过滤等运行时变换。资料来源：[fastmcp_slim/fastmcp/client/mixins/tools.py:1-40](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/tools.py#L1-L40)、[fastmcp_slim/fastmcp/contrib/component_manager/README.md:1-40](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/component_manager/README.md#L1-L40)。

## 2. 客户端传输与会话管理

客户端与 MCP 服务器的所有交互都通过传输对象完成。在 FastMCP Client 中，`list_tools_mcp` 与 `list_resources_mcp` 等高层方法在发起请求时，都会调用 `self.transport.get_session_id()` 取出当前会话标识，并将其注入 OpenTelemetry span 实现链路追踪；自动分页常量的上限为 `AUTO_PAGINATION_MAX_PAGES = 250`。资料来源：[fastmcp_slim/fastmcp/client/mixins/tools.py:24-72](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/tools.py#L24-L72)、[fastmcp_slim/fastmcp/client/mixins/resources.py:18-58](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/resources.py#L18-L58)。

```mermaid
flowchart LR
    A[FastMCP Client] --> B[Transport<br/>stdio / http / sse]
    B --> C[MCP Server]
    A -- "list_tools / list_resources" --> B
    B -- "session_id + telemetry" --> A
    A -- "OAuth 回调<br/>oauth_callback.py" --> B
    C -. "工具/资源挂载" .-> D[Proxy Client<br/>FastMCPProxy]
    D -. "转发请求" .-> B
```

OAuth 回调路径同样由客户端侧托管：`oauth_callback.py` 中定义的 `CallbackResponse` 与 `OAuthCallbackResult` 两个 dataclass，用于在本地浏览器完成授权后与 `anyio.Event` 协同，把 `code`/`state` 回填到客户端的传输对象中。资料来源：[fastmcp_slim/fastmcp/client/oauth_callback.py:120-160](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/oauth_callback.py#L120-L160)。

> **社区关注**：在 v3.4.0+ 中，`StatefulProxyClient.clear()` 可能在代理会话退出时触发 `KeyError`（#4321）；把 `RateLimitingMiddleware.get_client_id` 写成异步可调用对象会导致限流中间件被静默禁用（#4320）。这两类问题都集中在传输/代理生命周期的边缘行为上。

## 3. 模式与输出转换 (Schemas & Transforms)

模式层是工具与资源被 LLM 理解的关键。客户端的 `call_tool` 流程会调用 `json_schema_to_type` 把工具的 `outputSchema` 转换成 Python 类型适配器，以便在解析结果时获得类型校验与提示；任务/响应联合类型 (`ToolTaskResponseUnion`、`ResourceTaskResponseUnion`) 通过 Pydantic `RootModel` 表达 SEP-1686 优雅降级。资料来源：[fastmcp_slim/fastmcp/client/mixins/tools.py:28-40](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/tools.py#L28-L40)。

Transforms 概念在 contrib 模块中体现得最为具体：`fastmcp.contrib.component_manager` 通过 HTTP 端点 (例如 `POST /tools/{name}/enable` 与 `POST /resources/example://test/{id}/enable`) 在运行时启用或禁用工具、资源、提示词，并支持模板 URI 与挂载的远端组件，从而在不重启服务器的情况下完成"能力裁剪"。资料来源：[fastmcp_slim/fastmcp/contrib/component_manager/README.md:24-58](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/component_manager/README.md#L24-L58)。`fastmcp.contrib.mcp_mixin` 则通过类装饰器 (`@mcp_tool`、`@mcp_resource`、`@mcp_prompt`) 在注册阶段进行参数排除 (`exclude_args`) 与启用控制 (`enabled`)，属于另一种声明式的 transform 入口。资料来源：[fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md:24-58](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md#L24-L58)。

> **社区关注**：自引用 `$ref` 会在 `json_schema_to_type` 中触发 `RecursionError`（#4306）；`expand_uri_template` 与 `match_uri_template` 对包含保留字符的路径值无法 round-trip（#4326）。两者均属于模式/转换层在边界条件下的稳定性议题。

## 4. Apps 与资源安全策略

MCP Apps 允许工具返回交互式 UI 视图。在 `examples/apps/qr_server` 中，服务器通过 `AppConfig` 将工具 `generate_qr` 与一个 `ui://` 资源链接起来；该资源使用 `@modelcontextprotocol/ext-apps` JS SDK 在 iframe 内渲染，并通过 `ResourceCSP(resource_domains=["https://unpkg.com"])` 声明内容安全策略来源，确保宿主仅允许从白名单域名加载脚本。工具结果以 `ImageContent`（base64 PNG）的形式返回给前端展示。资料来源：[examples/apps/qr_server/README.md:1-46](https://github.com/PrefectHQ/fastmcp/blob/main/examples/apps/qr_server/README.md#L1-L46)。

整个 Apps 流水线可以概括为：FastMCP 工具返回结构化结果 (例如 `ImageContent`) → 与之绑定的 `ui://` 资源返回带 CSP 的 HTML → 宿主加载 JS SDK → SDK 通过 `ui://` URI 拉取数据 → 在沙箱化 iframe 中渲染交互界面。资料来源：[examples/apps/qr_server/README.md:32-46](https://github.com/PrefectHQ/fastmcp/blob/main/examples/apps/qr_server/README.md#L32-L46)。

---

## See Also

- [README.md](https://github.com/PrefectHQ/fastmcp/blob/main/README.md) — FastMCP 总览与三大能力 (Servers/Clients/Apps)
- `fastmcp_slim/fastmcp/client/mixins/` — 客户端工具与资源方法 (含传输会话与 schema 转换)
- `fastmcp_slim/fastmcp/contrib/component_manager/` — 运行时启用/禁用组件的 HTTP 端点
- `fastmcp_slim/fastmcp/contrib/mcp_mixin/` — 基于类的工具/资源/提示词装饰器
- `examples/apps/qr_server/` — MCP Apps、AppConfig、ResourceCSP 的端到端示例
- 社区议题索引：#4300 (缓存中间件)、#4306 (JSON Schema 递归)、#4321 (代理会话清理)、#4326 (URI 模板编码)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：PrefectHQ/fastmcp

摘要：发现 33 个潜在踩坑项，其中 12 个为 high/blocking；最高优先级：安装坑 - 来源证据：RecursionError in json_schema_to_type on self-referential $ref in tool outputSchema。

## 1. 安装坑 · 来源证据：RecursionError in json_schema_to_type on self-referential $ref in tool outputSchema

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：RecursionError in json_schema_to_type on self-referential $ref in tool outputSchema
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4306 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：Upgrade checks failing on main branch

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Upgrade checks failing on main branch
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4241 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安装坑 · 来源证据：caching middleware broken

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：caching middleware broken
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4300 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. 配置坑 · 来源证据：FastMCP StatefulProxyClient.clear() can cause KeyError during proxy session teardown

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：FastMCP StatefulProxyClient.clear() can cause KeyError during proxy session teardown
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4321 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 配置坑 · 来源证据：feat: hook or factory for customizing tool timeout error messages and types

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat: hook or factory for customizing tool timeout error messages and types
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4305 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 6. 维护坑 · 来源证据：expand_uri_template and match_uri_template do not round-trip path values containing reserved characters

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：expand_uri_template and match_uri_template do not round-trip path values containing reserved characters
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4326 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 7. 安全/权限坑 · 失败模式：security_permissions: No guardrails against destructive tool capabilities (shell exec, file deletion, env access)

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: No guardrails against destructive tool capabilities (shell exec, file deletion, env access)
- 对用户的影响：Developers may expose sensitive permissions or credentials: No guardrails against destructive tool capabilities (shell exec, file deletion, env access)
- 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4318 | No guardrails against destructive tool capabilities (shell exec, file deletion, env access)

## 8. 安全/权限坑 · 失败模式：security_permissions: on_message middleware not called for unauthenticated requests

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: on_message middleware not called for unauthenticated requests
- 对用户的影响：Developers may expose sensitive permissions or credentials: on_message middleware not called for unauthenticated requests
- 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4309 | on_message middleware not called for unauthenticated requests

## 9. 安全/权限坑 · 来源证据：No guardrails against destructive tool capabilities (shell exec, file deletion, env access)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：No guardrails against destructive tool capabilities (shell exec, file deletion, env access)
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4318 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 10. 安全/权限坑 · 来源证据：RateLimitingMiddleware.get_client_id passing an async callable silently disables rate limiting

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RateLimitingMiddleware.get_client_id passing an async callable silently disables rate limiting
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4320 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 11. 安全/权限坑 · 来源证据：feat: FastMCP(default_tool_timeout=...) for server-wide tool timeout default

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: FastMCP(default_tool_timeout=...) for server-wide tool timeout default
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4304 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 12. 安全/权限坑 · 来源证据：on_message middleware not called for unauthenticated requests

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：on_message middleware not called for unauthenticated requests
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4309 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 13. 安装坑 · 失败模式：installation: Upgrade checks failing on main branch

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Upgrade checks failing on main branch
- 对用户的影响：Developers may fail before the first successful local run: Upgrade checks failing on main branch
- 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4241 | Upgrade checks failing on main branch

## 14. 安装坑 · 失败模式：installation: caching middleware broken

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: caching middleware broken
- 对用户的影响：Developers may fail before the first successful local run: caching middleware broken
- 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4300 | caching middleware broken

## 15. 安装坑 · 失败模式：installation: v3.3.1: Loop There It Is

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.3.1: Loop There It Is
- 对用户的影响：Upgrade or migration may change expected behavior: v3.3.1: Loop There It Is
- 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.3.1 | v3.3.1: Loop There It Is

## 16. 安装坑 · 失败模式：installation: v3.4.0: Remote Control

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.4.0: Remote Control
- 对用户的影响：Upgrade or migration may change expected behavior: v3.4.0: Remote Control
- 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.0 | v3.4.0: Remote Control

## 17. 安装坑 · 失败模式：installation: v3.4.1: Floor It

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.4.1: Floor It
- 对用户的影响：Upgrade or migration may change expected behavior: v3.4.1: Floor It
- 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.1 | v3.4.1: Floor It

## 18. 配置坑 · 失败模式：configuration: CIMD redirect_uri validation rejects loopback URIs with dynamic ports (RFC 8252 §7.3)

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: CIMD redirect_uri validation rejects loopback URIs with dynamic ports (RFC 8252 §7.3)
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: CIMD redirect_uri validation rejects loopback URIs with dynamic ports (RFC 8252 §7.3)
- 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/3588 | CIMD redirect_uri validation rejects loopback URIs with dynamic ports (RFC 8252 §7.3)

## 19. 配置坑 · 失败模式：configuration: feat: FastMCP(default_tool_timeout=...) for server-wide tool timeout default

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: feat: FastMCP(default_tool_timeout=...) for server-wide tool timeout default
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: feat: FastMCP(default_tool_timeout=...) for server-wide tool timeout default
- 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4304 | feat: FastMCP(default_tool_timeout=...) for server-wide tool timeout default

## 20. 配置坑 · 失败模式：configuration: feat: hook or factory for customizing tool timeout error messages and types

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: feat: hook or factory for customizing tool timeout error messages and types
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: feat: hook or factory for customizing tool timeout error messages and types
- 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4305 | feat: hook or factory for customizing tool timeout error messages and types

## 21. 配置坑 · 失败模式：configuration: v3.4.0b1: Remote Possibility

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v3.4.0b1: Remote Possibility
- 对用户的影响：Upgrade or migration may change expected behavior: v3.4.0b1: Remote Possibility
- 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.0b1 | v3.4.0b1: Remote Possibility

## 22. 配置坑 · 失败模式：configuration: v3.4.2: Heads Up

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v3.4.2: Heads Up
- 对用户的影响：Upgrade or migration may change expected behavior: v3.4.2: Heads Up
- 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.2 | v3.4.2: Heads Up

## 23. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/PrefectHQ/fastmcp | README/documentation is current enough for a first validation pass.

## 24. 运行坑 · 失败模式：runtime: FastMCP StatefulProxyClient.clear() can cause KeyError during proxy session teardown

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: FastMCP StatefulProxyClient.clear() can cause KeyError during proxy session teardown
- 对用户的影响：Developers may hit a documented source-backed failure mode: FastMCP StatefulProxyClient.clear() can cause KeyError during proxy session teardown
- 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4321 | FastMCP StatefulProxyClient.clear() can cause KeyError during proxy session teardown

## 25. 运行坑 · 失败模式：runtime: RateLimitingMiddleware.get_client_id passing an async callable silently disables rate limiting

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: RateLimitingMiddleware.get_client_id passing an async callable silently disables rate limiting
- 对用户的影响：Developers may hit a documented source-backed failure mode: RateLimitingMiddleware.get_client_id passing an async callable silently disables rate limiting
- 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4320 | RateLimitingMiddleware.get_client_id passing an async callable silently disables rate limiting

## 26. 运行坑 · 失败模式：runtime: RecursionError in json_schema_to_type on self-referential $ref in tool outputSchema

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: RecursionError in json_schema_to_type on self-referential $ref in tool outputSchema
- 对用户的影响：Developers may hit a documented source-backed failure mode: RecursionError in json_schema_to_type on self-referential $ref in tool outputSchema
- 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4306 | RecursionError in json_schema_to_type on self-referential $ref in tool outputSchema

## 27. 维护坑 · 失败模式：migration: expand_uri_template and match_uri_template do not round-trip path values containing reserved...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: expand_uri_template and match_uri_template do not round-trip path values containing reserved characters
- 对用户的影响：Developers may hit a documented source-backed failure mode: expand_uri_template and match_uri_template do not round-trip path values containing reserved characters
- 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4326 | expand_uri_template and match_uri_template do not round-trip path values containing reserved characters

## 28. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/PrefectHQ/fastmcp | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/PrefectHQ/fastmcp | no_demo; severity=medium

## 30. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/PrefectHQ/fastmcp | no_demo; severity=medium

## 31. 安全/权限坑 · 来源证据：CIMD redirect_uri validation rejects loopback URIs with dynamic ports (RFC 8252 §7.3)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CIMD redirect_uri validation rejects loopback URIs with dynamic ports (RFC 8252 §7.3)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/3588 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 32. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/PrefectHQ/fastmcp | issue_or_pr_quality=unknown

## 33. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/PrefectHQ/fastmcp | release_recency=unknown

<!-- canonical_name: PrefectHQ/fastmcp; human_manual_source: deepwiki_human_wiki -->