框架总览与 Provider 架构

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

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

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

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

二、Provider 体系结构

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

1. Provider 基类与契约

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

2. 核心 Provider 类型

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

三、Provider 协作与数据流

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

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 的说明，contrib 模块可能与核心库拥有不同的稳定性保证与依赖要求，使用时需要自行评估风险。

典型 Contrib 模块

• component_manager：通过 HTTP 端点启用 / 禁用工具、资源与提示词，参见 fastmcp_slim/fastmcp/contrib/component_manager/README.md。
• mcp_mixin：通过类继承与装饰器批量注册组件，参见 fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md。

部署与 CLI 入口

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，用户可以通过 fastmcp.json 描述入口、环境与部署参数，从而以声明式方式启动服务器。

五、与社区关注点的衔接

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

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

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

参见

• 服务器基础与组件注册：README.md
• 客户端协议接入：fastmcp_slim/fastmcp/client/mixins/tools.py
• 鉴权 Provider：fastmcp_slim/fastmcp/server/auth/providers/jwt.py
• 应用层示例：examples/apps/qr_server/README.md

概述与设计目标

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。

核心架构：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。

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 都接受统一的 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
• Bearer Token 认证指南
• v3.4.2 Release Notes

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

概述

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. 响应返回：结果经中间件后置钩子包装后序列化返回。

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。
• RateLimitingMiddleware.get_client_id 仅接受同步可调用对象：传入 async 函数会被静默忽略，限流形同虚设，见 #4320。
• on_message 不覆盖未认证请求：认证失败的消息在中间件运行前被直接拒绝，无法记录或计量，见 #4309。

使用模式

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。
• 可定制的超时错误：当前错误信息为硬编码，希望提供钩子或工厂函数，见 #4305。

任务（Tasks）

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

工具输出 Schema 解析

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

常见故障模式

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

参见

• 认证与令牌校验：fastmcp_slim/fastmcp/server/auth/providers/jwt.py
• OAuth 回调处理：fastmcp_slim/fastmcp/client/oauth_callback.py
• 调试 Token 校验器：fastmcp_slim/fastmcp/server/auth/providers/debug.py

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。

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

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、fastmcp_slim/fastmcp/client/mixins/resources.py:18-58。

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。

社区关注：在 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。

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。fastmcp.contrib.mcp_mixin 则通过类装饰器 (@mcp_tool、@mcp_resource、@mcp_prompt) 在注册阶段进行参数排除 (exclude_args) 与启用控制 (enabled)，属于另一种声明式的 transform 入口。资料来源：fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md:24-58。

社区关注：自引用 $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。

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

Pitfall Log / 踩坑日志

项目：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