openbox-mcp 1.0.1

package/README.md

@@ -0,0 +1,233 @@
+# @openbox/mcp-adapter
+
+Pure proxy MCP server that connects IDE runtimes to the OpenBox Bridge API.
+
+## Architecture
+
+```
+IDE runtime / external MCP client
+    --> MCP transport (repo-local dev server OR remote server)
+            --> Bridge API
+                  --> Supabase
+                  --> Hatchet
+                  --> Nango
+                  --> native inbox / channel-ingress endpoints
+                  --> Langfuse
+```
+
+- Two supported shapes:
+  - repo-local stdio adapter, e.g. `npm --prefix packages/mcp-adapter run dev`
+  - remote always-on HTTP MCP server
+- Transport depends on the runtime surface (`stdio` locally, HTTP remotely).
+- Recommendation:
+  - repo work should use a project-local stdio config
+  - remote HTTP is secondary: use it for tenants, external runtimes, or explicit remote validation
+- the local worker lane (`@openbox/terminal`) is adjacent to this package
+  and talks to Bridge API directly; it is not an MCP client
+- The adapter is a transport layer only -- all business logic lives in Bridge API.
+- Connection mode and inference mode are separate:
+  - a local runtime may execute models locally
+  - the same runtime may delegate inference remotely through `OpenRouter`
+  - MCP still carries identity, memory, tasks and traces through OpenBox
+- Exfiltration Guard and PII masking are enforced at the adapter boundary:
+  - locally for repo-local runtimes
+  - on the remote MCP server for remote HTTP clients
+- remote HTTP MCP clients authenticate to the adapter with `Authorization: Bearer`;
+  the local stdio lane reads the runtime key from env, then the project-local
+  `.openbox/config.json` when present, and finally `~/.openbox/config.json`;
+  in both cases the adapter authenticates to Bridge API with the configured runtime key
+
+## Setup
+
+```bash
+npx @openbox/mcp-adapter setup --key=<agent-api-key> --project=/path/to/repo
+```
+
+The setup CLI:
+1. Validates the API key against Bridge API
+2. Detects supported IDE runtimes
+3. Creates `~/OpenBox/` workspace with standard structure
+4. Writes local stdio IDE config plus, when `--project` is provided, a project `.mcp.json`
+5. Generates `guardrails.yaml` with sensible defaults
+
+For repo-local work, the canonical path is the checked-in
+[repo-level `.mcp.json`](../../.mcp.json).
+
+When `setup --project` targets a repo that contains `packages/mcp-adapter`,
+the generated `.mcp.json` uses that local adapter over `stdio`, preferring:
+
+1. `node packages/mcp-adapter/dist/terminal.js` when the built adapter is present
+2. `npm --prefix packages/mcp-adapter run --silent dev` when only source is present
+3. published `@openbox/mcp-adapter` as the last fallback
+
+Use remote HTTP only when you explicitly want the always-on deployed MCP server.
+
+## Canonical Local Path
+
+For this repo, the default project path is:
+
+1. Open the repo with a client that supports project MCP config
+2. Let the repo-level `.mcp.json` start the local adapter over `stdio`
+3. Keep HTTP MCP as an explicit opt-in, not the default repo transport
+
+This keeps project work aligned with the checked-in adapter source and avoids
+making the remote MCP endpoint the silent default inside the repo.
+
+## Remote HTTP Path
+
+Remote HTTP MCP remains supported, but it is not the canonical repo path.
+
+- Use it for tenant environments and external runtimes
+- Use it for remote liveness checks and interoperability testing
+- Configure it explicitly via IDE/global config or `--url=<remote-mcp-url>`
+
+## Source Of Truth
+
+- Architecture: [`ADR-013`](../../agent-os/docs/decisions/ADR-013-bridge-api-adapters-conectividad.md)
+- Runtime boot contract: [`runtime-adapters.md`](../../agent-os/docs/supporting/concepts/runtime-adapters.md)
+- Onboarding spec: [`mcp-onboarding`](../../agent-os/docs/specs/mcp-onboarding/README.md)
+- Repo-level adapter surface: [`agent-os/adapters/README.md`](../../agent-os/adapters/README.md)
+
+## Current Files
+
+| Path | Purpose |
+|---|---|
+| `src/index.ts` | MCP server implementation (30 tools + 8 resources) |
+| `src/terminal.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 a compatible IDE runtime |
+| `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 |
+| `scripts/xai-remote-mcp-smoke.mjs` | Reproducible xAI Responses API smoke against the remote OpenBox MCP |
+| `package.json` | Build and runtime metadata |
+| `tsconfig.json` | TypeScript config |
+
+## Tools Summary (28 total + 8 dynamic resources)
+
+| Category | Tools |
+|----------|-------|
+| **Boot & Identity** | `openbox_boot`, `openbox_list_agents`, `openbox_assume_role` |
+| **Memory** | `openbox_get_memory`, `openbox_save_memory` (PII masked), `openbox_search_memory` — with scope and optional user/session narrowing |
+| **Tasks** | `openbox_list_tasks`, `openbox_create_task`, `openbox_update_task`, `openbox_run_task`, `openbox_delegate_task` |
+| **Goals** | `openbox_list_goals`, `openbox_get_goal`, `openbox_create_goal`, `openbox_update_goal`, `openbox_close_goal` |
+| **Workflows** | `openbox_trigger_workflow`, `openbox_list_workflows`, `openbox_get_workflow`, `openbox_create_workflow`, `openbox_update_workflow`, `openbox_validate_workflow`, `openbox_get_workflow_runs` |
+| **Tracing** | `openbox_trace` |
+| **Files** | `openbox_read_file` (tracked), `openbox_list_files` |
+| **Security** | `openbox_revoke_current_key`, `openbox_doctor` (self-test) |
+| **Diagnostics** | `openbox_diagnostics` |
+| **Host** | `openbox_host_docker_ps`, `openbox_host_docker_logs`, `openbox_host_system_status`, `openbox_host_exec` |
+
+Reality check:
+- the adapter exposes `openbox_assume_role`
+- the Bridge contract for role switching is `X-Agent-Id` + `POST /auth/assume-role`
+- the OpenBox repo implements that path locally; live availability depends on the deployed backend revision
+
+## Runtime Notes
+
+- Config source precedence: `OPENBOX_API_KEY` / `API_KEY` env, then project-local `.openbox/config.json`, then `~/.openbox/config.json`
+- API key env aliases: `OPENBOX_API_KEY` or `API_KEY`
+- Supported URL order: `internalBaseUrl` / `OPENBOX_INTERNAL_BASE_URL` first when present, then `baseUrl`
+- Project repo work should prefer `.mcp.json` + local stdio; `mcpUrl` is mainly for explicit remote HTTP installs
+- Local policy source: `guardrails.yaml` in the project root
+- A local subagent is a `child run`, not a sovereign OpenBox agent
+- Loading another identity with `openbox_boot` is valid for context hydration
+- Canonical parallel agent execution still goes through dispatch + real runtimes
+- `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{?scope,user_id,session_id,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:stdio:taskflow` / `npm run smoke:http`
+
+## Security Features
+
+### Exfiltration Guard
+
+Detects and blocks attempts to upload sensitive data:
+
+| Sensitivity | Patterns | Action |
+|-------------|----------|--------|
+| Critical | Private keys, API tokens, cloud credentials | 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 (`john@example.com`) | `[EMAIL_MASKED]` |
+| Telefono ES (`+34 612 345 678`) | `[PHONE_MASKED]` |
+| Tarjeta credito | `[CARD_MASKED]` |
+
+### Guardrails for Workflows
+
+```yaml
+workflows:
+  require_human_approval:
+    - "sdr-pipeline"
+    - "dispatch"
+  local_execution_only:
+    - "feature-lifecycle"
+  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
+
+```bash
+npm install
+npm run build
+npm run dev
+npx @openbox/mcp-adapter setup --project /path/to/project
+npm run smoke:stdio
+npm run smoke:stdio:taskflow
+npm run smoke:http
+XAI_PREFLIGHT_ONLY=1 npm run smoke:xai
+XAI_API_KEY=... npm run smoke:xai
+```
+
+## xAI Remote MCP Smoke
+
+Use this when you want to verify that Grok can consume the live OpenBox MCP via
+xAI's Remote MCP support.
+
+Environment variables:
+
+- `XAI_API_KEY` - required for the full xAI call
+- `XAI_MODEL` - optional, defaults to `grok-4.20-beta-latest-non-reasoning`
+- `XAI_BASE_URL` - optional, defaults to `https://api.x.ai/v1`
+- `OPENBOX_MCP_URL` - optional, defaults to `https://mcp.example.com/mcp`
+- `OPENBOX_ALLOWED_TOOL_NAMES` - optional CSV, defaults to `openbox_diagnostics`
+- `OPENBOX_MCP_AUTH` - optional full `Authorization` header value for the MCP server
+- `OPENBOX_MCP_EXTRA_HEADERS` - optional JSON object with extra MCP headers
+- `XAI_INPUT` - optional custom prompt sent to Grok
+
+Examples:
+
+```bash
+# Verify only that the remote MCP endpoint is alive and answers initialize
+XAI_PREFLIGHT_ONLY=1 npm run smoke:xai
+
+# Full xAI -> Remote MCP -> OpenBox check
+XAI_API_KEY=... \
+OPENBOX_ALLOWED_TOOL_NAMES=openbox_diagnostics \
+npm run smoke:xai
+```
+
+## 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.