Repository navigation
feat(c5): Streamable HTTP MCP gateway #7
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,136 @@ | ||
| # MCP Gateway (C5) | ||
|
|
||
| Public Bot surface for Flok Computers. **ComputerService** is the only path to compute. MCP / xAI account auth never authorizes computer access. | ||
|
|
||
| ## Endpoint | ||
|
|
||
| ```text | ||
| POST /mcp | ||
| ``` | ||
|
|
||
| Streamable HTTP, JSON-RPC 2.0. | ||
|
|
||
| | Protocol | Behavior | | ||
| |---|---| | ||
| | **2026-07-28** (preferred) | Stateless. `MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name` headers. `server/discover`, `tools/list`, `tools/call`. No session store. Header/body disagreement is `-32020`. | | ||
| | 2025-era (`2025-06-18`, `2025-03-26`, …) | Compatibility path: `initialize` / `notifications/initialized` / `ping` still work. `Mcp-Session-Id` may be sent and is **ignored** for identity and authorization. | | ||
|
|
||
| `GET` / `DELETE` return 405. C5 does not hold SSE sessions. | ||
|
|
||
| ## How a Grok Bot connects | ||
|
|
||
| 1. Operator provisions a computer (`ComputerService.requestComputer`) and issues a pair code (`issuePairCode`). That is control-plane, not an MCP tool. | ||
| 2. Configure a Grok Bot custom MCP connector: | ||
| - URL: `https://<host>/mcp` (`FLOK_MCP_BASE_URL`) | ||
| - Optional wrapper header: `Authorization: Bearer <FLOK_MCP_AUTH_TOKEN>` | ||
| 3. The Bot calls `computer_pair` with the pair code plus its `bird_id` / `flock_id`. | ||
| 4. The Bot stores `capability_token` and `computer_handle` and passes both on every later `computer_*` tool. | ||
|
|
||
| The existing Flok publish token at `~/flok/token` is **not** compute authority. Do not copy it into `FLOK_MCP_AUTH_TOKEN`. | ||
|
|
||
| Real Grok Bot pairing through a public URL is a **manual** gate. This package does not deploy. Set `FLOK_MCP_PUBLIC_URL` and `FLOK_LIVE_MCP_GROK_TEST=1` only after an approved public HTTPS endpoint exists. | ||
|
|
||
| ## Auth / capability flow | ||
|
|
||
| ```text | ||
| Grok Bot | ||
| │ Authorization: Bearer <wrapper> ← optional, connection identity only | ||
| │ POST /mcp tools/call computer_pair { pair_code, bird_id, flock_id } | ||
| ▼ | ||
| McpGateway | ||
| │ throttle pair by connection (wrapper digest or unauth+IP) | ||
| │ ComputerService.pair() ← C4 identity + digest checks | ||
| ▼ | ||
| { capability_token, capability_id, computer_handle, node_handle, scopes, expires_at } | ||
| │ | ||
| │ tools/call computer_status|exec|fs|observe|act | ||
| │ { capability_token, computer_handle, ... } | ||
| ▼ | ||
| ComputerService.authorize() → isCapabilityValid (digest, binding, scope, expiry, revoke) | ||
| │ | ||
| ▼ | ||
| ComputerProvider (never called from the gateway) | ||
| ``` | ||
|
|
||
| - Shared xAI account MCP auth / `account_id` is metadata. It cannot status/exec/fs. | ||
| - After pairing, the **capability token** is the routing and authorization credential. | ||
| - Transport session IDs are not Bot identity. | ||
|
|
||
| ## Tools (exactly eight) | ||
|
|
||
| | Tool | Service call | Notes | | ||
| |---|---|---| | ||
| | `computer_pair` | `pair()` | Returns the capability secret **once**. | | ||
| | `computer_status` | `status()` | No `providerDetail` / provider refs. | | ||
| | `computer_exec` | `exec()` | Default argv. `mode: "shell"` needs `shell` scope. stdout/stderr clipped to 64k. | | ||
| | `computer_fs` | `filesystem()` | Path jail. stat/list/read/write/mkdir/move/copy/delete. | | ||
| | `computer_observe` | `observe()` | Screenshot only when requested. No fabricated accessibility. | | ||
| | `computer_act` | `act()` | Bounded C3B actions. No VNC/takeover tool. | | ||
| | `handoff_send` | — | `PHASE_NOT_STARTED` (C9). | | ||
| | `handoff_receive` | — | `PHASE_NOT_STARTED` (C9). | | ||
|
|
||
| ## Example (fake tokens only) | ||
|
|
||
| Pair: | ||
|
|
||
| ```http | ||
| POST /mcp HTTP/1.1 | ||
| MCP-Protocol-Version: 2026-07-28 | ||
| Mcp-Method: tools/call | ||
| Mcp-Name: computer_pair | ||
| Content-Type: application/json | ||
|
|
||
| {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"computer_pair","arguments":{"pair_code":"ABCD-EFGH-JK","bird_id":"bird-noema","flock_id":"flock-adaptive"}}} | ||
| ``` | ||
|
|
||
| ```json | ||
| { | ||
| "jsonrpc": "2.0", | ||
| "id": 1, | ||
| "result": { | ||
| "content": [{"type": "text", "text": "{...}"}], | ||
| "isError": false, | ||
| "structuredContent": { | ||
| "capability_token": "fakeTokenNotARealSecret", | ||
| "capability_id": "cap_example", | ||
| "computer_handle": "computer_example", | ||
| "node_handle": "bird-noema", | ||
| "flock_id": "flock-adaptive", | ||
| "scopes": ["status", "exec", "fs", "observe", "act", "lifecycle"], | ||
| "expires_at": "2026-09-21T00:00:00.000Z" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Status: | ||
|
|
||
| ```json | ||
| {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"computer_status","arguments":{"capability_token":"fakeTokenNotARealSecret","computer_handle":"computer_example"}}} | ||
| ``` | ||
|
|
||
| ## Env / config | ||
|
|
||
| | Variable | Required for unit tests | Meaning | | ||
| |---|---|---| | ||
| | `FLOK_MCP_COMPUTERS_ENABLED` | no | Must be `1`/`true` to bind `src/mcp-server.ts` | | ||
| | `FLOK_MCP_LISTEN_HOST` | no | Default `127.0.0.1` | | ||
| | `FLOK_MCP_LISTEN_PORT` | no | Default `8787` | | ||
| | `FLOK_MCP_AUTH_TOKEN` | no | Optional wrapper Bearer. Connection auth, not Bot auth. | | ||
| | `FLOK_MCP_BASE_URL` | no | Public URL to document for Grok (e.g. `https://host/mcp`) | | ||
| | `FLOK_MCP_PUBLIC_URL` | no | Live Grok gate only | | ||
| | `FLOK_LIVE_MCP_GROK_TEST` | no | Opt-in live file; not CI | | ||
|
|
||
| ```bash | ||
| FLOK_MCP_COMPUTERS_ENABLED=1 npm run start:mcp | ||
| ``` | ||
|
|
||
| Default provider for that process is **FakeProvider**. Paid Runloop is not started here. | ||
|
|
||
| ## Logging | ||
|
|
||
| The gateway redacts `pair_code`, `capability_token`, `Authorization`, and API-key fields. Do not log raw pair codes or capability secrets anywhere else either. | ||
|
|
||
| ## SDK note | ||
|
|
||
| C5 implements a tools-only Streamable HTTP surface (2026-07-28 + 2025-era initialize) without vendoring `@modelcontextprotocol/server`. That keeps secret redaction, connection throttling, and “session is not identity” under this package’s control. Clients still speak standard JSON-RPC `tools/list` / `tools/call`. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -16,8 +16,10 @@ | |
| "test:live:docker": "node --experimental-vm-modules node_modules/tsx/dist/cli.mjs --test tests/providers/docker-dev.isolation.test.ts", | ||
| "test:live:runloop": "node --experimental-vm-modules node_modules/tsx/dist/cli.mjs --test tests/providers/runloop.isolation.test.ts tests/live/runloop.live.test.ts", | ||
| "test:live:runloop-c3b": "node --experimental-vm-modules node_modules/tsx/dist/cli.mjs --test tests/live/runloop.c3b.live.test.ts", | ||
| "test:live:mcp": "node --experimental-vm-modules node_modules/tsx/dist/cli.mjs --test tests/live/mcp.grok.live.test.ts", | ||
| "build": "tsc", | ||
| "verify": "npm run typecheck && npm test && npm run build" | ||
| "verify": "npm run typecheck && npm test && npm run build", | ||
| "start:mcp": "node --experimental-vm-modules node_modules/tsx/dist/cli.mjs src/mcp-server.ts" | ||
| }, | ||
| "dependencies": { | ||
| "@runloop/api-client": "1.28.0", | ||
|
|
@@ -31,6 +33,7 @@ | |
| "exports": { | ||
| ".": "./src/index.ts", | ||
| "./computers": "./src/lib/computers/index.ts", | ||
| "./mcp": "./src/lib/mcp/index.ts", | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
# Description: Inspect the package manifest export map, entry fields, and tsconfig output settings.
set -euo pipefail
fd -t f '^package.json$' -d 2 --exec sh -c 'echo "== $1 =="; jq "{name, main, module, types, files, exports, scripts}" "$1"' _ {}
fd -t f '^tsconfig' -d 2 --exec sh -c 'echo "== $1 =="; cat "$1"' _ {}
echo "== .npmignore =="
fd -t f '^.npmignore$' -d 2 --exec cat {}Repository: Adaptive-Liquidity/floks-pc Length of output: 2629 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== package files =="
git ls-files | sed -n '1,120p'
echo "== MCP source =="
mcp_file="$(fd -t f '^index\.ts$' src/lib/mcp -d 2 | head -n 1)"
test -n "$mcp_file"
cat -n "$mcp_file"
echo "== source entry files =="
for f in src/index.ts "$mcp_file"; do
if test -f "$f"; then
echo "-- $f --"
sed -n '1,100p' "$f"
fi
done
echo "== relevant package references =="
rg -n '"(main|module|types|files|exports|build)"|src/lib/mcp|dist/' README.md package.json .github 2>/dev/null || true
echo "== expected TypeScript output paths =="
python3 - <<'PY'
import json
from pathlib import Path
pkg = json.loads(Path("package.json").read_text())
ts = json.loads(Path("tsconfig.json").read_text())
print("exports:", json.dumps(pkg.get("exports"), indent=2))
print("main:", pkg.get("main"))
print("types:", pkg.get("types"))
print("files:", pkg.get("files"))
print("outDir:", ts["compilerOptions"].get("outDir"))
print("rootDir:", ts["compilerOptions"].get("rootDir"))
for source in ("src/index.ts", "src/lib/mcp/index.ts"):
relative = Path(source).relative_to(ts["compilerOptions"]["rootDir"]).with_suffix(".js")
print(source, "->", str(Path(ts["compilerOptions"]["outDir"]) / relative))
PYRepository: Adaptive-Liquidity/floks-pc Length of output: 7694 Align the package exports with 🤖 Prompt for AI Agents |
||
| "./providers": "./src/lib/computers/providers/index.ts" | ||
| } | ||
| } | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,75 @@ | ||
| /** | ||
| * MCP gateway configuration. Secrets come from the process environment of the | ||
| * control plane — never from ~/flok/token, never from a Node VM, never from | ||
| * client-supplied account_id. | ||
| */ | ||
|
|
||
| export const MCP_PREFERRED_PROTOCOL = "2026-07-28"; | ||
| export const MCP_LEGACY_PROTOCOLS = [ | ||
| "2025-11-25", | ||
| "2025-06-18", | ||
| "2025-03-26", | ||
| "2024-11-05", | ||
| ] as const; | ||
|
|
||
| export const MCP_SUPPORTED_PROTOCOLS: readonly string[] = [ | ||
| MCP_PREFERRED_PROTOCOL, | ||
| ...MCP_LEGACY_PROTOCOLS, | ||
| ]; | ||
|
|
||
| export const MCP_SERVER_INFO = { | ||
| name: "flok-mcp-gateway", | ||
| version: "0.0.1", | ||
| } as const; | ||
|
|
||
| export const MCP_PATH = "/mcp"; | ||
| export const MCP_MAX_BODY_BYTES = 1_048_576; | ||
| export const MCP_MAX_EXEC_OUTPUT_CHARS = 64_000; | ||
| export const MCP_MAX_ARGV = 64; | ||
| export const MCP_MAX_ARG_CHARS = 8_192; | ||
| export const MCP_MAX_ENV_KEYS = 32; | ||
| export const MCP_MAX_JSONRPC_BATCH = 32; | ||
|
|
||
| /** Per authenticated (or unauthenticated) MCP connection, not per Bot identity. */ | ||
| export const MCP_PAIR_CONNECTION_FAILURE_LIMIT = 20; | ||
| export const MCP_PAIR_CONNECTION_WINDOW_MS = 10 * 60 * 1000; | ||
| export const MCP_PAIR_THROTTLE_MAX_ENTRIES = 4_096; | ||
|
|
||
| export interface McpGatewayConfig { | ||
| /** Optional public base URL (documentation / Grok connector). */ | ||
| baseUrl?: string; | ||
| /** | ||
| * Optional wrapper Bearer token for the HTTP endpoint. | ||
| * This authenticates the *connection*, not a Bot, and never authorizes | ||
| * computer access. Distinct from Flok publish tokens and capability secrets. | ||
| */ | ||
| authToken?: string; | ||
| listenHost?: string; | ||
| listenPort?: number; | ||
| } | ||
|
|
||
| export function loadMcpGatewayConfig( | ||
| env: NodeJS.ProcessEnv = process.env, | ||
| ): McpGatewayConfig { | ||
| const config: McpGatewayConfig = {}; | ||
| const baseUrl = env.FLOK_MCP_BASE_URL?.trim(); | ||
| if (baseUrl) config.baseUrl = baseUrl; | ||
| const authToken = env.FLOK_MCP_AUTH_TOKEN?.trim(); | ||
| if (authToken) config.authToken = authToken; | ||
| const listenHost = env.FLOK_MCP_LISTEN_HOST?.trim(); | ||
| if (listenHost) config.listenHost = listenHost; | ||
| const portRaw = env.FLOK_MCP_LISTEN_PORT?.trim(); | ||
| if (portRaw) { | ||
| const port = Number.parseInt(portRaw, 10); | ||
| if (!/^\d+$/.test(portRaw) || !Number.isInteger(port) || port <= 0 || port >= 65536) { | ||
| throw new Error("FLOK_MCP_LISTEN_PORT must be an integer between 1 and 65535"); | ||
| } | ||
| config.listenPort = port; | ||
| } | ||
|
coderabbitai[bot] marked this conversation as resolved.
Resolved
|
||
| return config; | ||
| } | ||
|
|
||
| export function mcpComputersEnabled(env: NodeJS.ProcessEnv = process.env): boolean { | ||
| const v = env.FLOK_MCP_COMPUTERS_ENABLED?.trim().toLowerCase(); | ||
| return v === "1" || v === "true" || v === "yes"; | ||
| } | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win
🧩 Analysis chain
🌐 Web query:
tsx recommended CLI invocation package.json scripts node --import tsx💡 Result:
To use tsx in your package.json scripts, you have two primary options: using the tsx CLI directly or registering it via the node --import flag [1][2]. 1. Using the tsx CLI This is the recommended and most common approach for running TypeScript files [2]. Since npm automatically includes local node_modules/.bin in the PATH, you can reference tsx directly without npx [3][4]. { "scripts": { "start": "tsx./index.ts" } } 2. Using node --import tsx This approach is useful if you need to run the node command directly or require more control over the Node.js environment [5][6]. Using --import is the modern, preferred method, as the older --loader flag is deprecated in newer versions of Node.js [7][2][8]. { "scripts": { "start": "node --import tsx./index.ts" } } Key Considerations: - Installation: Ensure tsx is installed as a development dependency (npm install --save-dev tsx) so it is available in your environment [1][2]. - Compatibility: The --import tsx method is highly recommended over the deprecated --loader flag to avoid warnings or registration issues in newer Node.js versions [2][8]. - When to use --import: Use this when you are integrating with tools that specifically require the node command or when you need specialized Node.js configuration that the tsx CLI might not expose directly [5][6]. For standard execution, the tsx CLI is typically sufficient and simpler [9][4].
Citations:
🏁 Script executed:
Repository: Adaptive-Liquidity/floks-pc
Length of output: 4331
🏁 Script executed:
Repository: Adaptive-Liquidity/floks-pc
Length of output: 655
Invoke
tsxthrough its public CLI in all TypeScript test and MCP scripts.Replace the internal
node_modules/tsx/dist/cli.mjspath withtsx. Remove the unnecessary--experimental-vm-modulesflag.🤖 Prompt for AI Agents