如何构建一个 MCP 服务器:Feishu-MCP 的 stdio/SSE/Streamable HTTP 三种传输层实现详解
如何构建一个 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 服务器只需要回答两个问题:
- 对外提供什么能力——注册 tools、配置 capabilities;
- 消息通过哪条通道传输——这就是"传输层"(Transport)。
Feishu-MCP 的妙处在于:同一个服务器内核,通过三种不同的 Transport 适配了三种典型部署场景。这也是本文的重点。
二、整体架构:一个 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)的处理步骤非常清晰:
- 从查询参数
userKey或请求头user-key取出用户标识,缺失时用sessionId兜底并打印警告; - 创建
SSEServerTransport实例并注册会话映射(userAuthManager.createSession); - 把连接交给 SSE 连接管理器统一维护;
- 为这条连接创建独立的
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)的处理逻辑:
- 命中已有 sessionId → 复用内存中的
transports[sessionId]实例; - 无 sessionId 且是初始化请求 → 创建
StreamableHTTPServerTransport(sessionId 用randomUUID生成),初始化回调里把sessionId → userKey持久化映射存下来; - 其他情况 → 返回 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(下图中红箭头标注处),权限配置细节可参考项目内的手把手教程:
第 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 条经验:
- 内核与传输层解耦:业务逻辑(工具注册、服务调用)只写一遍,Transport 按场景替换;
- stdio 模式守护 stdout:日志走 stderr 或协议内
sendLoggingMessage; - SSE 必须做心跳保活:25 秒级别的 keepalive 注释行 + 断连自动清理;
- Streamable HTTP 做好会话生命周期:初始化时生成 sessionId、请求时复用、DELETE 时清理三件套缺一不可;
- 多用户共享场景管理身份标识:用
userKey隔离 token 缓存,公网部署再加 Bearer Token 认证。
想要更深入地学习,推荐阅读项目内两份文档:doc/MCP服务实现分享.md 梳理了整体架构与工具注册细节,doc/stdio-user-auth-analysis.md 剖析了 stdio 模式下 OAuth 认证的特殊处理。掌握以上模式,你就可以用同样的套路为任意业务系统构建自己的 MCP 服务器了。

