StdioServerTransport 是 MCP（Model Context Protocol）模型上下文协议官方内置的标准传输层实现

StdioServerTransport 完整详细解释

一、基础定义

StdioServerTransport 是 MCP（Model Context Protocol）模型上下文协议 官方内置的标准传输层实现，全称标准输入输出服务端传输。作用：通过进程自带的 stdin（标准输入）、stdout（标准输出）完成客户端 ↔ MCP 服务端之间 JSON-RPC 消息通信。

核心定位

Transport（传输层）：只负责收发二进制 / 文本消息，不处理业务逻辑；
Server 后缀：运行在MCP 服务端 一侧；配套客户端：StdioClientTransport（客户端侧标准输入输出传输）。

二、底层通信原理

进程启动模式客户端（如豆包桌面、Cursor、Claude Desktop）fork / 启动 MCP 插件子进程；

子进程的 stdin 绑定父进程输出 → 客户端下发请求给服务端
子进程的 stdout 绑定父进程输入 → 服务端返回响应、推送事件给客户端
stderr 标准错误流分离：日志、报错打印到 stderr，不会污染通信数据流（关键设计）

消息格式采用 MCP 规范的带长度前缀 JSON 消息 ： Content-Length: {数字}\r\n\r\n{"jsonrpc":"2.0",...} StdioServerTransport 自动完成：

读取 stdout 流、解析长度头、切割完整 JSON 报文
把服务端输出的 JSON 自动包装长度头写入 stdout

三、适用场景 & 优缺点

适用场景

本地运行的 MCP 本地插件（本地文件读取、本地代码工具、向量数据库本地服务），是本地 MCP 插件最主流传输方式。

优点

无需端口、无需 TCP/HTTP、不用处理端口占用、防火墙；
进程隔离，插件崩溃只会单独杀死子进程，不污染主 AI 客户端；
跨平台兼容 Windows/macOS/Linux；
部署极简，仅需启动二进制 / 脚本即可对接 AI 客户端。

缺点

仅限本机进程间通信，无法跨机器远程调用；
单进程一对一绑定，一个 stdio 子进程只能对接一个客户端；
大量高频消息时性能弱于 WebSocket/TCP 长连接。

四、核心 API 结构（TypeScript MCP SDK）

typescript

运行

复制代码

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { Server } from "@modelcontextprotocol/sdk/server/index.js";

// 1. 创建MCP服务实例
const server = new Server({
  name: "本地文件工具",
  version: "1.0.0"
});

// 2. 实例化标准输入输出传输层
const transport = new StdioServerTransport();

// 3. 绑定服务与传输，开始监听stdin/stdout消息
await server.connect(transport);

内部关键方法

connect() 绑定 server 与 stdio 流，启动循环读取 stdin、写入 stdout；
send(message) 序列化 JSON-RPC 报文，拼接 Content-Length 头部，输出到 stdout；
onmessage(callback) 监听 stdin 收到的客户端请求 JSON 消息；
close() 关闭流、销毁进程通信通道。

五、关键设计细节（容易踩坑）

stderr 不能用来输出通信数据 console.log、普通打印默认输出 stdout，会破坏 MCP 协议报文；插件日志必须使用 console.error() 输出到 stderr。
进程生命周期绑定客户端关闭 → stdin 流关闭 → StdioServerTransport 自动触发 server 关闭，插件进程退出。
区分 StdioServerTransport / StdioClientTransport

StdioServerTransport：你写的 MCP 插件（子进程）使用
StdioClientTransport：AI 客户端（Cursor/Claude）用来启动插件、作为调用方

六、和其他传输对比

StdioServerTransport（本地进程）无网络、零配置，本地插件首选；
WebSocketTransport / HttpStreamTransport 远程 MCP 服务、跨设备调用使用，需要端口 / 服务部署。

七、典型完整运行流程

AI 客户端启动你的 Node/Python 写的 MCP 插件子进程；
插件内部初始化 StdioServerTransport 并绑定 MCP Server；
客户端通过 stdin 下发工具调用请求；
Stdio 传输层解析 JSON → server 执行业务工具；
结果通过 transport 写入 stdout 返回客户端；
插件日志打印至 stderr，客户端单独捕获日志不干扰通信。

八、常见报错问题

工具无响应原因：代码中使用 console.log 打印日志污染 stdout 协议流；修复：全部替换为 console.error。
客户端提示协议解析失败原因：手动输出内容到 stdout，破坏 Content-Length 报文格式。
插件启动立刻退出 StdioServerTransport 未执行server.connect(transport)，传输未初始化，流直接关闭。

StdioServerTransport 是 MCP（Model Context Protocol）模型上下文协议 官方内置的标准传输层实现