Operit MCP TCP 桥接器(mcp-tcp-bridge)实战指南:打通 STDIO 本地 MCP 服务器与 Android TCP 客户端
Operit MCP TCP 桥接器(mcp-tcp-bridge)实战指南:打通 STDIO 本地 MCP 服务器与 Android TCP 客户端
导读
本指南基于 Operit 仓库中 tools/mcp_bridge 模块,系统讲解其核心工具 MCP TCP 桥接器(mcp-tcp-bridge) 的设计动机、安装构建、命令行与代码级使用方式,以及它与 Android 端 MCPBridge / MCPBridgeClient 的完整协作链路。读完本文,你将掌握:如何把基于 STDIO 的本地 MCP 服务器(Node/Python/Java 等)桥接到 TCP 端口,如何在 Termux/终端中部署并让无法访问命名管道(FIFO)的 Android 应用通过 127.0.0.1 与本地 MCP 进程通信,以及桥接器内置的并发连接、崩溃自动重启、请求超时与日志诊断机制。
为什么需要 TCP 桥接:STDIO 与 Android 之间的鸿沟
MCP(Model Context Protocol)官方 SDK 提供两种主流传输方式:
- STDIO(标准输入输出):客户端直接以子进程方式拉起 MCP 服务器,通过管道交换 JSON-RPC 消息。这是本地 MCP 服务器最常见、最轻量的运行形态,但客户端必须有能力 fork 子进程并持有其 stdin/stdout。
- HTTP Stream / SSE:通过 HTTP 传输,适合远程服务,但需要服务器具备 Web 端点。
Operit 的架构明确区分了这两类服务的接入方式,见 tools/mcp_bridge/README.md:
远程 HTTP Stream 和 SSE MCP 服务由 Android 端的 Kotlin MCP SDK 直接连接,不经过 bridge。
问题出现在本地服务上:Android 应用无法直接访问命名管道(FIFO),而官方 MCP 客户端通过管道与子进程通信的方式在 Android 受限进程中并不可行。mcp-tcp-bridge 因此被设计为纯桥接层:它负责把基于 STDIO 的本地 MCP 服务器进程「翻译」成一个 TCP 端点(默认监听 127.0.0.1:8752),让 Android 客户端像访问普通 Socket 服务一样发送 JSON-RPC 命令,即可操作本地 MCP 工具。
架构总览:双进程协作模型
从源码结构看,桥接器由两个 TypeScript 文件组成,构建后打包为两个独立 JS 产物:
| 文件 | 运行时角色 |
|---|---|
| tools/mcp_bridge/index.ts | 主进程:TCP 服务器、命令路由、服务注册表、生命周期与重启管理 |
| tools/mcp_bridge/spawn-helper.ts | 每个 MCP 服务对应的辅助进程:通过官方 @modelcontextprotocol/sdk 的 StdioClientTransport 连接真实 MCP 服务器 |
两者通过 Node IPC(fork + process.send) 通信,而不是直接由主进程管理 MCP 子进程。这一设计带来两个关键收益(源码证据见 spawn-helper.ts):
- 隔离崩溃:MCP 服务器或 helper 的异常退出不会拖垮 TCP 主进程,主进程可依据
exit/closed事件执行自动重启策略; - 官方协议复用:helper 直接使用官方
@modelcontextprotocol/sdk(版本1.30.0,见 tools/mcp_bridge/package.json)的Client+StdioClientTransport,工具发现(listTools,含分页游标遍历)、工具调用(callTool)都走标准实现,bridge 本身无需维护协议细节。
主进程 McpBridge 类(index.ts)内部维护了多张映射表:serviceHelpers(服务名 → helper 进程)、mcpToolsMap(服务名 → 工具列表缓存)、serviceRegistry(内存态服务注册表)、pendingRequests / pendingSpawnRequests(请求跟踪),并以 net.createServer 对外提供 TCP 服务。
功能特点一览
原文档列出的能力均可从源码得到印证:
- STDIO → TCP 桥接:
spawnServiceHelper()为每个已注册服务 fork 一个 helper(index.ts); - 并发连接:
activeConnections: Set<net.Socket>跟踪多客户端,每个 socket 独立维护缓冲区(socketBuffers)按行解析 JSON(index.ts); - 自动重启崩溃的 MCP 进程:
handleServiceClosure()实现指数退避重连,默认最多重试 5 次、基础延迟 5 秒;检测到SIGABRT时立即重启(index.ts); - 优雅处理连接错误与进程终止:
SIGINT/SIGTERM触发shutdown(),逐一套接字与 helper 进程清理(index.ts); - 详细日志:主进程
console.log/error全量输出,helper 的 stdout/stderr 被接入每服务环形日志缓冲(最多 400 行、单行截断 4000 字符),可通过logs命令查询(index.ts)。
安装与构建:pnpm 工作区 + ncc 打包
mcp-tcp-bridge 是仓库根 pnpm workspace 的一部分,依赖由根目录 pnpm-lock.yaml 统一锁定(文档明确说明)。构建过程分三步(见 tools/mcp_bridge/package.json 的 scripts):
# 在项目根目录安装工作区依赖
pnpm install
# 编译 bridge 并同步 Android assets
pnpm --dir tools/mcp_bridge run build
build 实际展开为:
tsc:将index.ts、spawn-helper.ts按 tsconfig.json(target: es2020、module: NodeNext、strict: true)编译到dist/;bundle:用@vercel/ncc将两个入口各自打成自包含单文件(bundle/index.js与bundle-helper/index.js),内联全部依赖——这一步使得 Android 端无需任何node_modules;copy:把打包产物同步为 Android 资源:
bundle/index.js → app/src/main/assets/bridge/index.js
bundle-helper/index.js → app/src/main/assets/bridge/spawn-helper.js
这两个产物文件在仓库中真实存在(app/src/main/assets/bridge/index.js、app/src/main/assets/bridge/spawn-helper.js),Android 端在运行时会把它们从 assets 复制到终端环境再启动(详见下文「Android 端集成」)。
使用方法:命令行与程序化两种姿势
基本用法
# 使用默认配置启动
pnpm --dir tools/mcp_bridge start
这将在默认端口 8752 上启动桥接器,连接到 ../your-mcp-server.js。命令行解析逻辑见 index.ts:argv[0] 解析为端口(非法时回退 8752),argv[1] 为 MCP 命令(默认 node),其余参数作为 MCP 命令参数。
高级用法:自定义端口与服务器命令
# 格式
pnpm --dir tools/mcp_bridge start -- [端口] [命令] [参数...]
# 示例:在端口9000上启动,连接到Python MCP服务器
pnpm --dir tools/mcp_bridge start -- 9000 python ../python_mcp_server.py
# 示例:连接到Java MCP服务器
pnpm --dir tools/mcp_bridge start -- 8752 java -jar ../java_mcp_server.jar
注意:命令行模式启动的 MCP 服务器仅作为默认服务注册,桥接器启动后不会自动拉起任何 MCP 进程(源码注释「默认不启动任何 MCP 进程」,见 index.ts)。真正的服务启动依赖客户端后续发送 spawn 命令——这是桥接器「按需启动」模型的关键:注册表与进程分离,先注册、后 spawn。
在其他 Node.js 应用中使用
import McpBridge from './path/to/bridge';
const bridge = new McpBridge({
port: 8752,
host: '127.0.0.1',
mcpCommand: 'node',
mcpArgs: ['../your-mcp-server.js'],
verbose: true
});
bridge.start();
McpBridge 构造函数的完整可配置项(index.ts)为:
| 配置项 | 默认值 | 说明 |
|---|---|---|
port |
8752 |
TCP 监听端口 |
host |
127.0.0.1 |
监听地址(默认仅本机回环) |
mcpCommand |
node |
默认 MCP 服务器启动命令 |
mcpArgs |
['../your-mcp-server.js'] |
默认 MCP 服务器参数 |
registryPath |
无 | 预留的服务注册表持久化路径(当前为纯内存实现) |
env |
无 | 额外注入的环境变量 |
桥接协议:面向 TCP 的 9 种命令
Android 客户端与桥接器的交互不是标准 MCP JSON-RPC,而是桥接器自定义的命令信封:{ "command": "<类型>", "id": "<uuid>", "params": {...} },以换行符分帧、每行一个 JSON。主进程在 handleMcpCommand()(index.ts)中路由,完整命令清单如下:
| 命令 | 作用 | 关键参数 |
|---|---|---|
spawn |
启动 MCP 服务(不关闭其他服务) | name、command、args、env、cwd、timeoutMs;未注册但带 command 时自动注册 |
shutdown |
关闭并注销指定服务 | name |
unspawn |
只停进程、保留注册 | name |
register |
注册本地 STDIO 服务(仅接受 type: "local") |
name、command、args、cwd、description、env |
unregister |
注销服务(运行中先停) | name |
list |
列出全部服务及运行状态,或查询单个服务 | 可选 name |
listtools |
列出服务工具(有缓存则直接返回) | 可选 name |
toolcall |
调用工具 | name(目标服务)、method、params |
logs |
获取服务日志、活跃与就绪状态 | name |
reset |
关闭所有服务、清空注册表与待处理请求 | 无 |
所有响应统一为 { "id", "success", "result?, "error"? },错误码遵循 JSON-RPC 风格(如 -32601 未知方法、-32602 参数错误、-32603 内部错误)。三个重要的运行时参数值得记住:
- 请求超时:
REQUEST_TIMEOUT = 180000ms(3 分钟),由每 5 秒一次的checkRequestTimeouts()扫描清理(index.ts); - Socket 超时:每个客户端连接 120 秒无活动即被服务端主动断开(index.ts);
- 闲置回收:服务闲置超过 5 分钟(
IDLE_TIMEOUT_MS)自动 unspawn,释放进程资源(index.ts)。
helper 子进程的深度细节
spawn-helper 是容易被忽略却决定兼容性的部分,几个值得注意的实现(spawn-helper.ts):
- npx 自动改写为 pnpm dlx:若服务命令为
npx,helper 会把其改写为pnpm dlx并剔除-y/--yes参数(L39-L43),确保在 pnpm 优先的环境下正确拉取远程包; - 环境变量合并与缓存隔离:合并
process.env与服务自定义env,并默认注入npm_config_cache(指向服务工作目录下的.npm-cache)、npm_config_prefer_offline=true、UV_LINK_MODE=copy;Linux 下额外设置NODE_OPTIONS=--openssl-legacy-provider(L45-L52); - 默认工作目录:未指定
cwd时回退到~/mcp_plugins/<服务名>,并支持~路径展开(L34); - 致命错误识别:主进程通过正则(如
environment variable ... is required、api_key required)识别「缺环境变量/API Key」类致命启动错误,标记fatalServices后不再自动重启,避免无限空转(index.ts)。
Android 端集成:从部署到工具调用
运行时部署链路
Android 端由 MCPBridge.kt 负责桥接器的生命周期,链路为:
- 部署(deployBridge):从 assets 读取打包后的
bridge/index.js与bridge/spawn-helper.js,先写入应用公共目录(OperitPaths.bridgeDir()),再通过内置终端服务与会话(mcp-bridge-deploy)跨环境复制到 Termux 路径~/bridge(L205-L295); - 启动(startBridge):在终端会话
mcp-bridge-daemon中执行cd ~/bridge && node index.js [port] &后台运行;先杀掉占用端口的旧进程(PortProcessKiller.killListeners(port)),启动后最多轮询 3 次验证list命令可达(L298-L424); - 端口自适应(detectPort):优先探测本地
127.0.0.1:8752(500ms 超时快速检测),失败则回退到 8751(SSH 转发端口),结果缓存 3.5 秒(L111-L138)。
客户端 Kotlin 示例(原文档代码,可直接运行)
原文档给出了一个最小可用的 Android Socket 客户端,发送 JSON-RPC 2.0 格式请求:
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import java.io.BufferedReader
import java.io.InputStreamReader
import java.io.PrintWriter
import java.net.Socket
import org.json.JSONObject
class McpClient {
private val host = "127.0.0.1"
private val port = 8752
suspend fun sendRequest(method: String, params: JSONObject): JSONObject = withContext(Dispatchers.IO) {
Socket(host, port).use { socket ->
val input = BufferedReader(InputStreamReader(socket.getInputStream()))
val output = PrintWriter(socket.getOutputStream(), true)
// 创建JSONRPC请求
val requestId = System.currentTimeMillis().toString()
val request = JSONObject().apply {
put("jsonrpc", "2.0")
put("id", requestId)
put("method", method)
put("params", params)
}
// 发送请求
output.println(request.toString())
// 读取响应
val response = input.readLine()
JSONObject(response)
}
}
}
需要说明:该示例演示的是最朴素的 Socket 直连形态。仓库内生产级实现是 MCPBridgeClient.kt,它通过 MCPBridge.sendCommand() 发送上文 9 种命令信封,并实现了更完整的能力:
- 自动连接:
connect()先ping探活,未就绪则检查注册状态并阻塞式spawnBlocking()(默认超时 180 秒,与桥接器SPAWN_TIMEOUT对齐); - 连接复用:普通命令复用长连接(3.5 秒空闲后自动关闭,
COMMAND_CONNECTION_KEEP_MS),spawn命令则使用独立专用 socket 等待完整启动结果,避免阻塞其他命令; - 工具调用容错:
callTool()检测not available/not connected/connection closed/timeout等错误后自动重连并重试一次;getTools()解析工具列表,getToolDescriptions()生成name: description文本供 LLM 使用; - 失败诊断:
buildSpawnFailureDetail()从桥接器错误响应中提取lastError与最近 6 行日志摘要,拼装成可读的失败原因(L180-L206)。
在 Termux 中使用
原文档给出的 Termux 部署步骤完整如下:
# 安装Node.js
pkg install nodejs
# 克隆或下载此项目
git clone <项目URL>
cd <项目目录>
# 安装根工作区依赖
pnpm install
# 编译并同步 Android assets
pnpm --dir tools/mcp_bridge run build
# 启动桥接器
pnpm --dir tools/mcp_bridge start -- 8752 node ../your-mcp-server.js
在 Termux 场景中还需注意:Android 端 MCPBridge 的自动部署/启动逻辑(把 assets 中打包好的单文件复制到 ~/bridge 后 node index.js)可以完全替代手动 clone 构建流程;当应用与 Termux 处于同一台设备时,客户端走 127.0.0.1:8752 直连;若桥接器运行在远端 Linux 主机上,则通过 SSH 端口转发到本地 8751 接入(这正是 detectPort() 双端口设计的用意)。
注意事项与最佳实践
原文档的安全与运维建议,结合源码补充如下:
- 确保 MCP 服务器程序已正确安装并可执行:桥接器不会替你做依赖管理——helper 仅负责拉起命令,命令不存在、缺 Python 包等都会在
logs命令的日志缓冲中暴露; - 仅限内部网络使用,不要暴露到公共互联网:桥接器默认监听
127.0.0.1,无任何认证与加密。若确有跨主机需求,优先采用 SSH 端口转发(如 8751 方案),而不是直接放开监听地址; - 生产环境考虑添加认证和加密层:从源码看,当前实现是纯内存注册表 + 明文 TCP,适合开发与本地集成;生产化可在外部叠加 TLS 隧道或访问控制;
- Android 端必须声明
INTERNET权限:即使连接的是127.0.0.1回环地址,Android 的 Socket 访问同样受INTERNET权限约束,需在 app/src/main/AndroidManifest.xml 中配置; - 留意环境变量缺失类致命错误:桥接器识别到缺 API Key / 环境变量后会将服务标记为 fatal 并停止重启,此时请通过
logs命令查看具体缺失项,补齐后重新spawn; - 按需启动、闲置回收:服务在闲置 5 分钟后会被自动 unspawn,下次
toolcall前客户端会自动重新连接,这是预期行为而非故障。
相关资源索引
- 桥接器主进程实现:tools/mcp_bridge/index.ts
- 桥接器 helper 进程实现:tools/mcp_bridge/spawn-helper.ts
- 构建脚本与依赖声明:tools/mcp_bridge/package.json
- Android 端客户端封装:MCPBridgeClient.kt
- Android 端部署与启动管理:MCPBridge.kt
- 打包产物(Android assets):app/src/main/assets/bridge/index.js、app/src/main/assets/bridge/spawn-helper.js
- 根工作区依赖锁文件:pnpm-lock.yaml