punkpeye/fastmcp

FastMCP – 快速概览

是什么 – FastMCP 是一个用于构建支持 Model Context Protocol (MCP) 的服务器的 TypeScript 框架。MCP 是一种协议，允许 LLM（或其他 AI 代理）调用工具、获取资源，并与后端服务器交换结构化数据。FastMCP 封装了官方 MCP SDK，并提供了大量底层处理，使你可以专注于定义工具、资源、提示等。

核心功能

• 使用简单、类型安全的 API 定义 工具、资源 和 提示（支持 Zod、ArkType、Valibot 或原始 JSON Schema）。
• 内置 认证、会话与请求 ID 追踪 和 错误处理。
• 多种传输方式：
  • stdio（用于本地 CLI 使用）
  • HTTP 流式传输（高效二进制友好流式传输，也提供 SSE 回退）
  • HTTPS，支持自定义证书、CORS 配置和健康检查端点。
• 通过底层 Hono 应用支持 自定义 HTTP 路由——你可以在 MCP 端点之外，暴露 REST API、Webhook、管理页面等。
• 边缘运行时支持——轻量级的 EdgeFastMCP 类让你可以在 Cloudflare Workers、Deno Deploy 等环境中运行相同服务器（边缘仅支持无状态模式）。
• 无状态模式 适用于无服务器部署——每个请求获得临时会话，不保留持久状态。
• 便捷功能：进度通知、流式输出、类型安全的服务器事件、提示参数自动补全、采样/引导控制、可配置的 ping、内存中传输（用于单元测试），以及 CLI 工具（fastmcp dev、fastmcp inspect）。

何时使用 – 如果你希望使用现成的 MCP 服务器，而无需编写官方 SDK 所需的底层套接字处理，就应选择 FastMCP。它非常适合快速原型设计或需要认证、HTTPS、自定义路由或边缘部署的生产服务。如果你需要对每个细节完全控制，原始 SDK 可能仍更合适。

典型工作流程

1. npm install fastmcp
2. 使用基本元数据创建 FastMCP 实例。
3. 使用 server.addTool(...) 等方法添加工具/资源，提供一个模式（Zod 等）和一个异步 execute 函数。
4. 调用 server.start({ transportType: "httpStream", httpStream: { port: 8080 } })（CLI 使用 stdio）。
5. 可选地通过 server.getApp() 添加自定义 Hono 路由，用于 REST 端点或 Webhook。
6. 部署——在 Node 服务器上运行，或切换到 EdgeFastMCP 并部署到 Cloudflare Workers。

示例片段（来自 README）展示了一个可使用 npx fastmcp dev src/examples/addition.ts 在本地运行的微型加法工具。

---

快速参考

• 包名: fastmcp (npm)
• 语言: TypeScript
• 主要运行时: Node.js（Cloudflare Workers、Deno Deploy 使用 EdgeFastMCP）
• 传输选项: stdio、httpStream（可选 HTTPS）、SSE 回退
• 认证: 可插拔的 authenticate 回调；支持 API 密钥、OAuth 等。
• 测试: 内存中传输、CLI 开发模式、检查器 UI。

---

总结 – FastMCP 是一个真正的、可投入生产的框架，用于构建基于 MCP 的 AI 服务后端，它处理协议细节、安全性和部署问题，让开发者可以专注于 AI 特定逻辑。