如何构建一个 MCP 服务器:Feishu-MCP 的 stdio/SSE/Streamable HTTP 三种传输层实现详解

原创2026-10-30 17:23:492,306 阅读

如何构建一个 MCP 服务器:Feishu-MCP 的 stdio/SSE/Streamable HTTP 三种传输层实现详解

想亲手搭建一个 MCP 服务器吗?Feishu-MCP 是一个极佳的实战范本:它基于 Model Context Protocol(MCP)协议,为 Cursor、Claude Code、Cline 等 AI 工具提供飞书文档与任务管理能力,并且在同一个服务中完整实现了 stdio、SSE、Streamable HTTP 三种传输层。读懂它的源码,你就掌握了构建 MCP 服务器的核心套路。

一、MCP 服务器是什么?先搞懂"传输层"

MCP(Model Context Protocol)是 AI 模型与外部系统之间的标准协议。它把 AI 工具当作客户端,把提供能力的服务当作MCP 服务器,双方通过 JSON-RPC 2.0 消息通信,AI 因此可以调用工具(Tools)、读取资源(Resources)。

一个最小化的 MCP 服务器只需要回答两个问题:

  1. 对外提供什么能力——注册 tools、配置 capabilities;
  2. 消息通过哪条通道传输——这就是"传输层"(Transport)。

Feishu-MCP 的妙处在于:同一个服务器内核,通过三种不同的 Transport 适配了三种典型部署场景。这也是本文的重点。

Feishu-MCP 在 AI 工具中调用飞书文档的 MCP 服务器使用演示

二、整体架构:一个 Server,三种入口

Feishu-MCP 的架构可以概括为一句话:内核是统一的,入口是可切换的。

┌─────────────┐        ┌──────────────────────┐        ┌──────────┐
│  AI 客户端   │ <====> │      Feishu-MCP      │ <====> │  飞书 API │
│(Cursor等)    │  传输层 │  (统一 FeishuMcp 内核) │        │          │
└─────────────┘        └──────────────────────┘        └──────────┘
        stdio 模式  |  SSE 模式  |  Streamable HTTP 模式

启动入口在 src/index.ts,核心逻辑非常简单:

  • 判断环境变量 NODE_ENV=cli 或命令行带 --stdio 参数 → 走 stdio 模式;
  • 否则默认启动 HTTP 服务器,同时暴露 /sse 和 /mcp 两类端点。

而真正承载 MCP 协议的部分是 src/mcp/feishuMcp.ts 中的 FeishuMcp 类——它继承官方 SDK 的 McpServer,在构造函数中按 FEISHU_ENABLED_MODULES 配置动态注册 document、task、member 等模块的工具。可以看到,传输层的选择与业务工具注册完全解耦,这正是官方 SDK "Server + Transport" 分离设计的价值所在。

三、传输层一:stdio 标准输入输出(本地集成首选)

stdio 模式让 MCP 服务器以子进程方式运行,AI 客户端通过标准输入(stdin)发请求、标准输出(stdout)收响应,不占用任何网络端口,是 Cursor 等本地 IDE 工具最推荐的方式。

3.1 实现要点

在 src/server.ts 的 connect 方法中,服务器把 StdioServerTransport 接到 FeishuMcp 实例上,并监听 stdin 的 close/end 事件来做资源清理——客户端断开时进程自动退出,干净利落。

3.2 新手最容易踩的坑:stdout 污染

stdio 模式下 stdout 必须只包含合法的 JSON-RPC 消息。任何一条 console.log 都会破坏协议解析,导致客户端报 JSON 解析错误。项目专门做过一份分析文档:doc/stdio-logging-impact-analysis.md,结论是:

  • 普通模式下日志走 console.*,warn/error 走 stderr 相对安全,log/info 会污染 stdout;
  • 因此 stdio 模式下 Logger 会自动抑制控制台输出,日志改为通过 MCP 协议自身的 sendLoggingMessage 传递。

💡 给新手的关键实践:如果你自己写 MCP 服务器,请把日志统一输出到 stderr 或日志文件,永远不要 console.log 到 stdout。

3.3 一个反直觉的设计:stdio 模式也要开 HTTP 端口

用 user 认证(OAuth)时,飞书授权流程需要一个回调地址接收 code。但 stdio 进程没有常驻 HTTP 服务怎么办?Feishu-MCP 的解法在 src/index.ts:stdio 模式下额外启动一个最小化的 callback 服务器(src/services/callbackService.ts),只注册 /callback 一个路由。而且它贴心地处理了 EADDRINUSE 错误——多个 stdio 进程可以共享同一个已存在的 callback 服务器,静默通过而不是崩溃。

四、传输层二:SSE 模式(/sse + /messages 双端点)

SSE(Server-Sent Events)是 MCP 早期的 HTTP 传输方案,适合把 MCP 服务器部署成共享服务、多人通过 URL 接入的场景。它用两个端点协作完成双向通信:

端点 方法 作用
/sse GET 客户端建立长连接,服务器向客户端推送消息
/messages POST 客户端把 JSON-RPC 请求发到这个端点,服务器再经 SSE 流回复

4.1 连接建立流程

/sse 路由(src/server.ts)的处理步骤非常清晰:

  1. 从查询参数 userKey 或请求头 user-key 取出用户标识,缺失时用 sessionId 兜底并打印警告;
  2. 创建 SSEServerTransport 实例并注册会话映射(userAuthManager.createSession);
  3. 把连接交给 SSE 连接管理器统一维护;
  4. 为这条连接创建独立的 FeishuMcp 实例并连接 transport——每个 SSE 连接一个 Server 实例,互不干扰。

4.2 长连接的心跳保活

HTTP 长连接最大的敌人是"静默断开":网络中断后双方都不知情。src/manager/sseConnectionManager.ts 用全局定时器每 25 秒向所有活跃连接写入 : keepalive 注释行:

  • 写入成功 → 连接活着;
  • 写入失败(writableEnded)→ 自动清理该连接及对应 transport。

一个细节是 keepAliveIntervalId.unref()——定时器不阻止进程退出,避免 stdio 模式下进程"赖着不走"。这就是新手实现 SSE 传输层时几乎必做、却最常漏掉的一步。

五、传输层三:Streamable HTTP(新一代单端点方案)

MCP 规范后来用 Streamable HTTP 取代了 SSE 的双端点设计:所有请求都打到同一个 /mcp 端点,用 HTTP 语义(POST/GET/DELETE)分别表达"发送消息""接收服务器推送""终止会话"。

5.1 会话管理是核心

Streamable HTTP 通过 Mcp-Session-Id 请求头区分会话。/mcp 路由(src/server.ts)的处理逻辑:

  1. 命中已有 sessionId → 复用内存中的 transports[sessionId] 实例;
  2. 无 sessionId 且是初始化请求 → 创建 StreamableHTTPServerTransport(sessionId 用 randomUUID 生成),初始化回调里把 sessionId → userKey 持久化映射存下来;
  3. 其他情况 → 返回 400 Bad Request: No valid session ID provided。

配套的两个语义化路由也很值得学习:

  • GET /mcp:客户端建立 SSE 流,接收服务器主动推送的通知;
  • DELETE /mcp:客户端主动终止会话,服务器随即清理 transport 和会话映射。

5.2 多用户共享的一个高级设计

同一个 Streamable 会话在后续请求中可以携带新的 user-key 请求头,服务器会动态切换该会话绑定的用户上下文(src/server.ts)。这支撑了"多租户中转架构":一个 MCP 服务实例代理给多个团队使用,不同租户的请求在同一会话层动态隔离。这个设计对想搭建企业级共享 MCP 服务的开发者非常有参考价值。

5.3 安全:Bearer Token 认证

所有 HTTP 端点都挂了一层 bearerAuthMiddleware:配置了 MCP_BEARER_TOKEN 环境变量后,每个请求必须携带 Authorization: Bearer <token>,格式错误或令牌不匹配分别返回 401/403。未配置则跳过认证,保持向后兼容——公网部署 MCP 服务器时强烈建议开启。

六、三种传输层怎么选?一张表说清楚

对比维度 stdio SSE Streamable HTTP
通信通道 进程 stdin/stdout /sse + /messages 双端点 单一 /mcp 端点
是否占端口 否(callback 除外) 是 是
典型场景 本地 IDE(Cursor 等)私有集成 共享服务、老客户端兼容 共享服务、新客户端首选
多用户支持 单用户(一个 FEISHU_USER_KEY) userKey 参数区分 userKey + 会话内动态切换
会话管理 进程生命周期即会话 连接管理器 + 心跳保活 Mcp-Session-Id 显式会话

选型建议:个人本地开发用 stdio,零配置最省心;要把 MCP 服务器部署给团队共享,优先用 Streamable HTTP,SSE 留给旧客户端兼容。

七、动手实践:三步启动你的飞书 MCP 服务器

第 1 步:准备飞书应用凭证

在飞书开放平台创建自建应用,进入"凭证与基础信息"页面获取 App ID 和 App Secret(下图中红箭头标注处),权限配置细节可参考项目内的手把手教程:

飞书开放平台应用凭证 App ID 与 App Secret 获取位置

第 2 步:选择模式启动

# stdio 模式(本地 AI 工具集成)
npx feishu-mcp@latest --stdio \
  --feishu-app-id=<你的AppID> --feishu-app-secret=<你的AppSecret> \
  --feishu-auth-type=tenant --enabled-modules=document

# HTTP 模式(SSE + Streamable HTTP 端点同时可用)
npx feishu-mcp@latest --feishu-app-id=<你的AppID> --feishu-app-secret=<你的AppSecret>

也可以本地克隆后开发调试:

git clone https://gitcode.com/gh_mirrors/fe/Feishu-MCP
cd Feishu-MCP
pnpm install && pnpm run dev

HTTP 模式启动后,控制台会打印三个端点:/sse、/messages 和 /mcp,监听在 3333 端口(可用 PORT 修改)。

第 3 步:在 AI 客户端中接入

stdio 模式(Cursor / Cline 的 mcpServers 配置):

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "npx",
      "args": ["-y", "feishu-mcp@latest", "--stdio"],
      "env": {
        "FEISHU_APP_ID": "<你的飞书应用ID>",
        "FEISHU_APP_SECRET": "<你的飞书应用密钥>",
        "FEISHU_USER_KEY": "<你的用户标识>"
      }
    }
  }
}

SSE 模式 / Streamable HTTP 模式(只需一个 URL,userKey 用于多用户区分,建议随机):

{
  "mcpServers": {
    "feishu_local": { "url": "http://localhost:3333/sse?userKey=123456" },
    "feishu_streamable": { "url": "http://localhost:3333/mcp?userKey=123456" }
  }
}

之后就可以让 AI 直接"读取这个飞书文档""把会议纪要写入飞书"了,工具能力一览见 tool-schemas/ 下的各工具 JSON 定义。

八、复盘:从 Feishu-MCP 学到的构建要点

最后把全文浓缩成构建 MCP 服务器的 5 条经验:

  1. 内核与传输层解耦:业务逻辑(工具注册、服务调用)只写一遍,Transport 按场景替换;
  2. stdio 模式守护 stdout:日志走 stderr 或协议内 sendLoggingMessage;
  3. SSE 必须做心跳保活:25 秒级别的 keepalive 注释行 + 断连自动清理;
  4. Streamable HTTP 做好会话生命周期:初始化时生成 sessionId、请求时复用、DELETE 时清理三件套缺一不可;
  5. 多用户共享场景管理身份标识:用 userKey 隔离 token 缓存,公网部署再加 Bearer Token 认证。

想要更深入地学习,推荐阅读项目内两份文档:doc/MCP服务实现分享.md 梳理了整体架构与工具注册细节,doc/stdio-user-auth-analysis.md 剖析了 stdio 模式下 OAuth 认证的特殊处理。掌握以上模式,你就可以用同样的套路为任意业务系统构建自己的 MCP 服务器了。

登录后查看全文
Feishu-MCP