SPOC

@spocapp/mcp-bridge

Claude Desktop、Cursor、Zed、Windsurf など、stdio のみをサポートする MCP クライアントから、SPOC MCP サーバー（spoc.com/mcp/rpc）に接続するための、小型の stdio ブリッジです。

• 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 を設定し、環境変数でベアラートークンを渡します。

環境変数

変数	デフォルト	備考
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	(未設定)	SSE イベントストリームをスキップするには 1 を設定します。通知は利用できなくなりますが、それ以外はすべて引き続き動作します。
SPOC_DEBUG	(未設定)	stderr にログを出力するには 1 を設定します。MCP クライアントがエラーを黙って無視する場合のデバッグに便利です。

ベアラートークン

https://spoc.com/settings/api-keys で生成します。ハーネスの発行が必要な呼び出しが SPOC に拒否されないよう、harness:issue スコープが選択されていることを確認してください。

プリンシパルを必要としない読み取り専用ツールは、匿名で利用できます。ベアラートークンが必要なのは、ID に代わって動作するツールのみです。

スモークテスト

ブリッジと上流サーバーの両方が正常に動作していることを確認します。

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

"name":"spoc" と "version":"1.27.0" を含む JSON が、1 行だけ返されるはずです。これが表示されれば、MCP 対応クライアントを利用できます。

トラブルシューティング

再起動後、クライアントにツールが表示されません。 上記のスモークテストを通常のターミナルで実行してください。エラーフレームが返された場合は、error.data フィールドに原因が示されます。何も返されない場合は、クライアントのログで起動エラーを確認してください。よくある原因は、クライアントの PATH に npx が含まれていないことです。

ツール呼び出しで ERR_INTERNAL が発生します。 ほとんどの場合、ブリッジではなく上流の問題です。SPOC_DEBUG=1 を設定して再実行すると、ブリッジが上流からの生のレスポンスをログに記録します。

401 エラーが発生します。 ベアラートークンがない、間違っている、または必要なスコープがありません。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 のレポートイベントの HMAC 署名を直接実装する場合は、注意点が 1 つあります。SPOC の正規形式は JavaScript の JSON.stringify の動作に準拠しており、非 ASCII 文字を \uXXXX にエスケープせず、そのまま出力します。Python の json.dumps(...) はデフォルトで非 ASCII 文字をエスケープするため、em ダッシュ、曲がった引用符、アクセント付き文字を初めて含めると、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