@openbox/mcp-adapter

Pure proxy MCP server that connects any IDE to the OpenBox Bridge API over Streamable HTTP.

Architecture

IDE (Claude Code / Cursor / Windsurf / VS Code / Codex)
    --> HTTPS --> OpenBox MCP Server (Hetzner, always on)
                    --> Bridge API (thevive.ai) --> Supabase

• One remote MCP server on Hetzner. No local server process.
• Transport: Streamable HTTP (not stdio).
• The adapter is a transport layer only -- all business logic lives in Bridge API.
• Exfiltration Guard and PII masking are enforced locally before data leaves the device.

Setup

npx @openbox/mcp-adapter setup --key=sk_ob_xxxx

The setup CLI:

1. Validates the API key against Bridge API
2. Detects installed IDEs (Claude Code, Cursor, Windsurf, VS Code, Codex)
3. Creates ~/OpenBox/ workspace with standard structure
4. Writes MCP config to each detected IDE
5. Generates guardrails.yaml with sensible defaults

After setup, every detected IDE can immediately use all 30 OpenBox tools.

Source Of Truth

• Architecture: ADR-013
• Runtime boot contract: docs/concepts/runtime-adapters.md
• Onboarding spec: docs/specs/mcp-onboarding/
• Repo-level adapter surface: adapters/README.md

Current Files

| Path | Purpose | |---|---| | src/index.ts | MCP server implementation (30 tools + 8 resources) | | src/cli.ts | CLI entrypoint (setup or server mode) | | src/setup.ts | Onboarding flow: IDE detection, workspace creation, config install | | boot-hook.sh | Local boot helper for Claude Code | | scripts/stdio-smoke.mjs | Reproducible stdio smoke against the live Bridge API | | scripts/http-smoke.mjs | Reproducible Streamable HTTP smoke against the live Bridge API | | package.json | Build and runtime metadata | | tsconfig.json | TypeScript config |

Tools Summary (30 total)

| Category | Tools | |----------|-------| | Boot & Identity | openbox_boot, openbox_list_agents, openbox_assume_role | | Memory | get_memory, save_memory (PII masked), search_memory | | Tasks | list_tasks, create_task, update_task, run_task, delegate_task | | Workflows | trigger_workflow, list_workflows, get_workflow, create_workflow, update_workflow, validate_workflow, get_workflow_runs | | Tracing | trace | | Files | read_file (tracked), list_files | | Security | revoke_current_key, doctor (self-test) | | Diagnostics | diagnostics | | Host | docker_ps, docker_logs, system_status, host_exec |

Runtime Notes

• Config source: ~/.openbox/config.json or env vars
• Supported URL order: internalBaseUrl / OPENBOX_INTERNAL_BASE_URL first when present, then baseUrl
• Local policy source: guardrails.yaml in the project root
• openbox_diagnostics verifies /boot, /agents, /tasks, /memory, version compatibility, host access and guardrails state
• openbox_doctor runs comprehensive self-tests including exfiltration guard and PII masking
• Dynamic MCP resource templates:
  • openbox://agent/{agent_id}/identity
  • openbox://agent/{agent_id}/memory{?limit,offset}
  • openbox://agent/{agent_id}/tasks{?status,limit,offset}
  • openbox://workflow/{workflow_id}
  • openbox://workflow/{workflow_id}/runs{?status,limit,offset}
• stdio mode uses newline-delimited JSON-RPC, not Content-Length framing
• Reproducible smoke: npm run smoke:stdio / npm run smoke:http

Security Features

Exfiltration Guard

Detects and blocks attempts to upload sensitive data:

| Sensitivity | Patterns | Action | |-------------|----------|--------| | Critical | Private keys, API tokens (GitHub, OpenAI, Anthropic, Slack), AWS keys | BLOCKED | | Secret | Passwords, API secrets, access tokens, JWTs | BLOCKED | | PII | DNI/NIE, email, phone, credit card | AUTO-MASKED |

PII Masking

| Pattern | Mask | |---------|------| | DNI espanol (12345678A) | [DNI_MASKED] | | Email ([email protected]) | [EMAIL_MASKED] | | Telefono ES (+34 612 345 678) | [PHONE_MASKED] | | Tarjeta credito | [CARD_MASKED] |

Guardrails for Workflows

workflows:
  require_human_approval:
    - "sdr-pipeline"
    - "dispatch"
  local_execution_only:
    - "dev-process"
  deny:
    - "deprecated-workflow"

File System Security

• Project folder isolation: cannot read/list files outside project folder
• Guardrails integration: respects ignore_patterns and readonly_patterns
• Session tracking: file reads tracked for 5 minutes TTL

Commands

npm install
npm run build
npm run dev
npx @openbox/mcp-adapter setup --project /path/to/project

Rules

• Keep this package as a transport adapter only.
• No Supabase client, no service role key, no product state cache.
• If a capability belongs to OpenBox business logic, implement it in Bridge API, not here.
• Exfiltration Guard is enforced at the adapter level -- cannot be bypassed by Bridge API.