Operit MCP TCP 桥接器(mcp-tcp-bridge)实战指南:打通 STDIO 本地 MCP 服务器与 Android TCP 客户端

原创2026-10-02 21:26:551,864 阅读
文章标签:人工智能AI AgentAI 应用移动开发工具调用GUI 自动化本地部署插件系统Agent 工作流

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):

  1. 隔离崩溃:MCP 服务器或 helper 的异常退出不会拖垮 TCP 主进程,主进程可依据 exit/closed 事件执行自动重启策略;
  2. 官方协议复用: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 实际展开为:

  1. tsc:将 index.ts、spawn-helper.ts 按 tsconfig.json(target: es2020、module: NodeNext、strict: true)编译到 dist/;
  2. bundle:用 @vercel/ncc 将两个入口各自打成自包含单文件(bundle/index.js 与 bundle-helper/index.js),内联全部依赖——这一步使得 Android 端无需任何 node_modules;
  3. 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 负责桥接器的生命周期,链路为:

  1. 部署(deployBridge):从 assets 读取打包后的 bridge/index.js 与 bridge/spawn-helper.js,先写入应用公共目录(OperitPaths.bridgeDir()),再通过内置终端服务与会话(mcp-bridge-deploy)跨环境复制到 Termux 路径 ~/bridge(L205-L295);
  2. 启动(startBridge):在终端会话 mcp-bridge-daemon 中执行 cd ~/bridge && node index.js [port] & 后台运行;先杀掉占用端口的旧进程(PortProcessKiller.killListeners(port)),启动后最多轮询 3 次验证 list 命令可达(L298-L424);
  3. 端口自适应(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 前客户端会自动重新连接,这是预期行为而非故障。

相关资源索引

登录后查看全文
Operit