SPOC

@spocapp/mcp-bridge

小型 stdio 桥接工具，让 Claude Desktop、Cursor、Zed、Windsurf 和其他仅支持 stdio 的 MCP 客户端能够与 SPOC MCP 服务 spoc.com/mcp/rpc 通信。

• npm：@spocapp/mcp-bridge
• MCP Registry：io.github.SPOC-App/mcp-bridge
• 在线服务：https://spoc.com/mcp/rpc — 自报名称为 spoc / 1.27.0

它是什么（以及不是什么）

目前大多数 MCP 客户端只支持 stdio 传输——通过子进程的 stdin/stdout 传输 JSON-RPC。SPOC 的 MCP 服务使用 HTTP+SSE，因此可以同时服务多个客户端。这个桥接工具负责连接两者：安装后，将 MCP 客户端指向它，SPOC 的工具就会出现在客户端的工具选择器中。

它不是对 MCP 协议的重写，也不会缓存、批处理或重新解释请求。每个 JSON-RPC 帧都会原样传递。如果你需要的行为与桥接工具目前提供的不同，通常直接在 SPOC 中修复会比修改这个桥接工具更容易。

安装

你无需安装它——大多数 MCP 客户端会在需要时通过 npx 获取：

npx -y @spocapp/mcp-bridge

或者安装一次，然后让客户端指向该二进制文件：

npm install -g @spocapp/mcp-bridge
which spoc-mcp-bridge

配置 MCP 客户端

Claude Desktop

编辑配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "spoc": {
      "command": "npx",
      "args": ["-y", "@spocapp/mcp-bridge"],
      "env": {
        "SPOC_BEARER": "spk_live_..."
      }
    }
  }
}

重启 Claude Desktop。几秒钟内，SPOC 的工具应该就会出现在工具选择器中。

Cursor

~/.cursor/mcp.json（或依次选择 Settings → MCP → Edit mcp.json）：

{
  "mcpServers": {
    "spoc": {
      "command": "npx",
      "args": ["-y", "@spocapp/mcp-bridge"],
      "env": { "SPOC_BEARER": "spk_live_..." }
    }
  }
}

Zed

~/.config/zed/settings.json：

{
  "context_servers": {
    "spoc": {
      "command": {
        "path": "npx",
        "args": ["-y", "@spocapp/mcp-bridge"],
        "env": { "SPOC_BEARER": "spk_live_..." }
      }
    }
  }
}

Windsurf、Continue 等

任何支持 MCP stdio 传输的客户端都可以用相同方式配置。将命令设为 npx -y @spocapp/mcp-bridge，并通过环境变量传入 bearer。

环境变量

变量	默认值	说明
SPOC_BEARER	(未设置)	作为 Authorization: Bearer … 发送的令牌。匿名访问时省略。需要主体的工具（例如 spoc.harness.issue）必须设置此项。
SPOC_ENDPOINT	https://spoc.com/mcp/rpc	HTTP JSON-RPC 端点。
SPOC_EVENTS_ENDPOINT	https://spoc.com/mcp/events	用于服务端发起通知的 SSE 端点。
SPOC_TIMEOUT_MS	30000	HTTP 请求超时时间，单位为毫秒。
SPOC_DISABLE_SSE	(未设置)	设为 1 可跳过 SSE 事件流。通知将不可用，其他功能仍正常。
SPOC_DEBUG	(未设置)	设为 1 可将日志输出到 stderr。当 MCP 客户端静默吞掉错误时，此设置很有用。

Bearer 令牌

在 https://spoc.com/settings/api-keys 生成令牌。请确保勾选 harness:issue 权限范围，否则 SPOC 会拒绝需要签发 harness 的调用。

匿名访问适用于不需要主体的只读工具。只有代表某个身份执行操作的工具才需要 bearer。

冒烟测试

确认桥接工具和上游服务都运行正常：

npx -y @spocapp/mcp-bridge <<< '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'

你应该会收到一行 JSON，其中包含 "name":"spoc" 和 "version":"1.27.0"。如果看到这些内容，支持 MCP 的客户端就可以正常工作。

故障排查

重启后，客户端中未显示工具。 在普通终端中运行上面的冒烟测试。如果返回错误帧，error.data 字段会说明原因。如果完全没有返回内容，请检查客户端日志中是否有启动错误——通常是因为客户端的 PATH 中没有 npx。

调用工具时出现 ERR_INTERNAL。 几乎总是上游问题，而非桥接问题。设置 SPOC_DEBUG=1 并重新运行——桥接会记录原始上游响应。

出现 401 错误。 Bearer 令牌缺失、错误或权限范围不足。请在 https://spoc.com/settings/api-keys 验证。

SSE 无法连接。 通知是可选的。设置 SPOC_DISABLE_SSE=1 后，除服务端发起的通知外，其他功能仍可正常使用。

测试

npm ci
npm run build
npm test        # unit + client-integration suites (offline, no network)

client-integration 测试套件会将 spoc-mcp-bridge 作为真实子进程启动，并通过 Claude Desktop、Cursor、Zed 和 Windsurf 使用的相同 stdio 协议驱动它——包括 initialize、notifications/initialized、tools/list、tools/call、并发进行中的调用、混合类型 ID、SSE 通知、上游错误和超时。如果测试通过，使用 stdio 的 MCP 客户端就能正常工作。

如需同时测试真实的生产端点：

SPOC_LIVE_TEST=1 npm test                              # anonymous only
SPOC_LIVE_TEST=1 SPOC_BEARER=spk_live_... npm test     # + tools/call

CI 会在每次推送和 PR 时，在 Node 18 / 20 / 22 上运行离线测试套件；实时测试套件仅在 main 上运行。

编写自己的客户端

如果你要直接实现 SPOC 的 report-event HMAC 签名（而不是通过此桥接），需要注意一点：SPOC 的规范形式与 JavaScript 的 JSON.stringify 行为一致，会保留非 ASCII 字符，而不是将其转义为 \uXXXX。Python 默认的 json.dumps(...) 会转义非 ASCII 字符——首次包含破折号、弯引号或带重音符号的字符时，就会收到 bad_signature 401 错误。请传入 ensure_ascii=False。

链接

• https://spoc.com — 底层服务
• https://spoc.com/mcp/manifest — 工具目录
• https://spoc.com/docs/api — 完整的 HTTP API
• CHANGELOG.md — 发布历史以及各版本之间的变更
• RELEASING.md — 如何发布新版本

许可证

MIT