目录

1. 简介
2. 核心架构与设计理念
3. 初始化流程与配置参数
4. 功能模块整合机制
5. 请求分发与会话生命周期管理
6. 启动模式对比与部署实践

简介

FastMCP 是一个为 MCP（Model Context Protocol）协议设计的高层抽象服务器框架，旨在简化 MCP 服务器的开发与部署。它通过统一的接口暴露 MCP 能力，整合了工具、资源和提示词三大核心功能模块，为开发者提供了更加直观和便捷的编程接口。本文档将深入解析 FastMCP 的设计原理、核心架构、初始化流程、功能整合机制以及在不同环境下的部署最佳实践。

核心架构与设计理念

FastMCP 的核心设计理念是提供一个高内聚、低耦合的服务器抽象层。它通过封装底层 MCP 协议的复杂性，让开发者能够专注于业务逻辑的实现，而非协议细节。

其架构主要由以下几个核心组件构成：

1. FastMCP 类：作为整个服务器的入口和协调中心，负责管理配置、初始化各功能模块，并提供统一的 API。
2. ToolManager：专门负责管理所有注册的工具（Tools），处理工具的注册、查找和调用。
3. ResourceManager：负责管理所有资源（Resources），包括静态资源和基于 URI 模板的动态资源。
4. PromptManager：负责管理所有提示词（Prompts），支持参数化提示词的渲染。
5. StreamableHTTPSessionManager：管理基于 HTTP 的会话生命周期，支持有状态和无状态模式。

这些组件通过依赖注入的方式在 FastMCP 的初始化过程中被创建和关联，形成了一个清晰的分层架构。

图源

• server.py
• tool_manager.py
• resource_manager.py
• manager.py
• streamable_http_manager.py

初始化流程与配置参数

初始化流程

FastMCP 的初始化是一个关键过程，它通过 __init__ 方法完成。其主要步骤如下：

1. 配置解析：首先，根据传入的参数（如服务器名称、主机地址、端口等）创建一个 Settings 对象。该对象还支持从环境变量（前缀为 FASTMCP_）中读取配置，提供了灵活的配置管理方式。
2. 核心组件创建：
   • 创建底层的 MCPServer 实例，作为协议的实际执行者。
   • 创建 ToolManager、ResourceManager 和 PromptManager 实例，用于管理各自的模块。
3. 认证配置验证：检查 auth 配置项，确保 auth_server_provider 和 token_verifier 不会同时被指定，保证认证配置的正确性。
4. 功能模块注册：调用 self._setup_handlers() 方法，将 FastMCP 实例中的处理函数（如 list_tools, call_tool）注册到 MCPServer 的协议处理器中。这一步是将高层抽象与底层协议连接起来的关键。
5. 日志配置：根据 log_level 参数配置日志系统。

核心配置参数

FastMCP 的 __init__ 方法接受一系列丰富的配置参数，主要包括：

• 元数据参数：
  • name: 服务器名称。
  • instructions: 服务器指令，用于向客户端描述服务器功能。
  • website_url: 服务器网站链接。
  • icons: 服务器图标列表。
• 网络与传输参数：
  • host, port: 服务器监听的主机和端口。
  • mount_path, sse_path, message_path, streamable_http_path: 各种传输协议的挂载路径。
  • json_response: 是否使用 JSON 响应而非 SSE 流。
  • stateless_http: 是否启用无状态 HTTP 模式。
• 功能模块参数：
  • tools: 初始工具列表。
  • warn_on_duplicate_*: 控制在注册重复的工具、资源或提示词时是否发出警告。
• 安全与生命周期参数：
  • auth: 认证设置。
  • lifespan: 一个异步上下文管理器，在服务器启动和关闭时执行，用于管理数据库连接等资源。

本节来源

• server.py

功能模块整合机制

FastMCP 通过装饰器和管理器模式，将工具、资源和提示词三大功能模块无缝整合到服务器中。

工具（Tools）模块

工具是服务器提供的核心功能单元。FastMCP 提供了两种方式来注册工具：

1. @tool 装饰器：这是最常用的方式。开发者只需在函数上添加 @server.tool() 装饰器，该函数就会被自动注册为一个工具。
2. add_tool 方法：允许在运行时动态添加工具。

当一个工具被调用时，FastMCP 的 call_tool 方法会通过 ToolManager 找到对应的 Tool 对象并执行。ToolManager 在内部维护一个工具名称到 Tool 实例的字典，确保了高效的查找。

图示来源

• server.py
• tool_manager.py

资源（Resources）模块

资源模块允许服务器暴露可读取的数据，如文件、数据库查询结果等。FastMCP 支持两种资源：

1. 静态资源：通过 @resource("resource://my-resource") 装饰器注册，其 URI 是固定的。
2. 模板资源：URI 中包含参数占位符（如 resource://{city}/weather），函数的参数会与占位符匹配，实现动态资源。

ResourceManager 内部使用两个字典分别存储静态资源和模板资源。当客户端请求一个资源时，get_resource 方法会先在静态资源中查找，如果未找到，则遍历模板资源，尝试匹配 URI 模板并创建具体的资源实例。

提示词（Prompts）模块

提示词模块用于向客户端提供预定义的、可参数化的消息序列。通过 @prompt 装饰器，可以将一个返回 list[Message] 的函数注册为一个提示词。PromptManager 负责管理这些提示词，并在客户端请求时，根据传入的参数调用相应的函数来渲染出最终的消息列表。

本节来源

• server.py
• server.py
• server.py
• tool_manager.py
• resource_manager.py
• manager.py

请求分发与会话生命周期管理

请求分发机制

FastMCP 支持多种传输协议，如 stdio、sse 和 streamable-http。请求分发的核心在于 run 方法和相应的 app 方法（如 sse_app, streamable_http_app）。

以 streamable-http 为例：

1. run_streamable_http_async 方法会调用 streamable_http_app() 创建一个 Starlette 应用实例。
2. streamable_http_app 方法会创建一个 StreamableHTTPASGIApp 实例，并将其作为路由的终点。
3. 当 HTTP 请求到达时，ASGI 服务器会调用 StreamableHTTPASGIApp.__call__，进而调用 StreamableHTTPSessionManager.handle_request。

会话生命周期管理

StreamableHTTPSessionManager 是会话管理的核心。它通过 MCP-Session-ID HTTP 头来跟踪会话。

• 有状态模式 (stateless_http=False)：
  • 新会话：当请求不包含 MCP-Session-ID 时，会创建一个新的 StreamableHTTPServerTransport 实例，并生成一个唯一的会话 ID。
  • 现有会话：当请求包含有效的 MCP-Session-ID 时，会复用已有的 StreamableHTTPServerTransport 实例来处理请求。
  • 会话状态（如服务器内部的连接流）在会话 ID 存在期间被持久化。
• 无状态模式 (stateless_http=True)：
  • 每个请求都会创建一个全新的 StreamableHTTPServerTransport 实例。
  • 请求处理完毕后，该实例立即被销毁。
  • 这种模式适用于无状态的微服务或需要在多节点间负载均衡的场景。

图示来源

• server.py
• server.py
• streamable_http_manager.py

启动模式对比与部署实践

同步与异步启动模式对比

FastMCP 提供了同步和异步两种启动模式，主要通过 run 和 run_*_async 方法族来实现。

• 同步模式 (run 方法)：
  • 优点：使用简单，符合传统同步编程习惯。
  • 缺点：阻塞当前线程，无法在同一个进程中运行其他任务。
  • 适用场景：简单的脚本式服务器，或作为主程序的唯一任务。
• 异步模式 (run_*_async 方法)：
  • 优点：非阻塞，可以与其他异步任务并发执行，资源利用率高。
  • 缺点：需要在异步事件循环中运行。
  • 适用场景：复杂的服务器应用，需要与其他服务（如数据库、消息队列）交互，或需要集成到更大的异步框架中。

不同部署环境下的最佳实践

• 本地开发：

  • 使用 run(transport="stdio") 模式，便于与命令行工具或调试器集成。
  • 启用 debug=True 和 log_level="DEBUG" 以获取详细的日志信息。
  • 示例：python server.py。

• 容器化部署 (如 Docker)：

  • 推荐使用 streamable-http 传输，便于通过 HTTP 网关暴露服务。
  • 通过环境变量（FASTMCP_HOST, FASTMCP_PORT 等）配置服务器参数，实现配置与镜像的分离。
  • 使用 stateless_http=True 可以简化容器的水平扩展。
  • 示例 Dockerfile 指令：CMD ["uv", "run", "server.py", "--transport", "streamable-http"]。

• 云服务部署 (如 AWS, GCP)：

  • 结合云服务的负载均衡器和自动伸缩组，使用 stateless_http=True 模式。
  • 将 event_store 配置为使用云存储（如 S3、GCS）的持久化实现，以支持有状态的会话恢复。
  • 利用云服务的监控和日志服务（如 CloudWatch, Stackdriver）来收集 log_level="INFO" 或 WARNING 级别的日志。
  • 通过云服务的密钥管理服务（KMS）来安全地管理 auth 相关的敏感配置。

本节来源

• server.py
• server.py
• examples\servers\simple-streamablehttp\README.md
• examples\servers\simple-streamablehttp-stateless\README.md