Outbox MCP server
README.md
# @out-box/mcp — Outbox MCP server
Server MCP oficial de **[Outbox](https://out-box.dev)** (out-box.dev), la biblioteca privada
**agents-first** para publicar HTMLs. Expone Outbox como **herramientas nativas** para cualquier
cliente MCP (Claude Desktop, Cursor, etc.) — sin curl ni CLI.
Es una de las **3 vías** para usar Outbox desde un agente:
- **CLI** (`outbox …`) — comandos shell.
- **skill** `outbox-publish` — para agentes con skills.
- **MCP** (este paquete) — tools nativas en clientes MCP.
## Instalación
Hay dos formas de conectarlo. Las dos exponen las mismas tools.
### Claude (web, escritorio y celular) — connector remoto, sin instalar nada
En claude.ai → Settings → Connectors → **Add custom connector**, con la URL
`https://mcp.out-box.dev/mcp`. Claude te manda a iniciar sesión en Outbox y a elegir los permisos
(`outbox:read`, `outbox:write`, `outbox:delete`); no hace falta API key. Cada conexión crea una agent
key "Claude connector" que podés revocar en out-box.dev → Settings → Keys.
En Claude Code: `claude mcp add --transport http outbox https://mcp.out-box.dev/mcp`.
### Claude Desktop / Cursor / cualquier cliente stdio — vía `npx`
Necesitás tu **API key** de Outbox (`outbox_*`) y **Node.js 20 o superior**. No requiere instalar nada
global: el cliente MCP lo lanza con `npx`.
```json
{
"mcpServers": {
"outbox": {
"command": "npx",
"args": ["-y", "@out-box/mcp"],
"env": {
"OUTBOX_API_KEY": "outbox_xxxxxxxxxxxxxxxx"
}
}
}
}
```
### Desde el repo (desarrollo)
```bash
git clone https://github.com/jonathanleiva15/out-box-mcp.git
cd out-box-mcp
npm install
npm run build # compila a dist/
```
Y en el config usá `"command": "node"` con `"args": ["/ruta/absoluta/al/repo/out-box-mcp/dist/index.js"]`
(o `npm link` y `"command": "outbox-mcp"`).
> 💡 **Tip de seguridad (entornos cloud/compartidos):** usá una **agent key acotada a una carpeta**
> (`outbox keys gen-agent --folder <carpeta> --verbs publish,list --days 30`). Si el entorno se filtra,
> el blast radius es esa sola carpeta. El verbo `list` hace falta para que el agente pueda **releer**
> sus páginas privadas (`outbox_pull`); sin él, leerlas da `403 private_read_scope_required`.
## Autenticación
Precedencia de la key:
1. `OUTBOX_API_KEY` (variable de entorno) — recomendado.
2. `~/.outboxrc` — el archivo que escribe el CLI con `outbox login`.
La key **nunca** se loguea. El server **no** escribe `~/.outboxrc` (eso lo hace el CLI). En sesiones
remotas/headless el agente **no puede hacer login interactivo** → por eso la auth es por key.
**Sin credencial el server igual arranca**: cada tool que necesita auth responde un error accionable
(`missing_credential`: "configurá OUTBOX_API_KEY…"). `outbox_capabilities` (público) funciona igual, y
se suma `outbox_publish_anonymous` para publicar sin cuenta (ver abajo).
### Sin cuenta: `outbox_publish_anonymous` (0.4.0)
Solo se registra cuando el server arrancó **sin** credencial (ni `OUTBOX_API_KEY` ni `~/.outboxrc`). Con
key no aparece: el agente publica en la biblioteca del usuario con `outbox_publish`.
- Input: `html` **o** `markdown` (excluyentes), `title` opcional (máx 120) y `model` opcional.
- Pega a `POST /api/anon/publish` sin Bearer. La página queda en `https://out-box.dev/p/<id>`, la ve
cualquiera que tenga el link y **vence a las 72 h**. No entra en ninguna biblioteca.
- Devuelve `url`, `expiresAt`, `ttlSeconds`, `claimUrl` y `message`, un texto listo para el humano
("Abrí este link para guardarla en tu cuenta antes de <fecha>: <claimUrl>"). El `claimToken` no se
devuelve suelto: ya viaja en el fragmento del `claimUrl`, que es lo único que el humano necesita.
- Límites: 2 por hora y 3 por día por IP, 5 por día por red (más un tope global diario); 2 MiB de HTML o 256 KiB de
markdown. `429` sale con la espera (`Retry-After`) y la sugerencia de crear una cuenta; `503 anon_paused`
avisa que la publicación sin cuenta está pausada; `403 anon_publish_disabled`, que no está habilitada.
- **Nunca** publiques sin cuenta contenido con datos privados, personales o credenciales.
- El connector remoto (`mcp.out-box.dev`) siempre corre con credencial: no la expone.
### Variables de entorno
Todas son opcionales salvo la credencial (`OUTBOX_API_KEY` **o** `~/.outboxrc`).
| Variable | Default | Para qué |
|---|---|---|
| `OUTBOX_API_KEY` | — | La API key `outbox_*` (recomendado). Si está, tiene precedencia sobre `~/.outboxrc`. Sin ninguna credencial solo se puede publicar sin cuenta (`outbox_publish_anonymous`). |
| `OUTBOX_USER` | (de `~/.outboxrc` o `/api/me`) | Username del owner, para defaultear el arg `user` de las tools sin pegarle a `/api/me`. |
| `OUTBOX_RC` | `~/.outboxrc` | Path alternativo al archivo de credencial que escribe el CLI (útil en entornos con otro `HOME`). |
| `OUTBOX_TOOLSETS` | `core,comments,sharing` | Qué grupos de tools se registran: `core`, `comments`, `library`, `sharing`, `keys`, `teams`, `automation`, `apps` o `all`. `core` siempre queda activo. |
| `OUTBOX_LANG` | `en` | Idioma de los títulos y descripciones de las tools: `en` (default) o `es`. |
| `OUTBOX_FILES_DIR` | `~/Outbox` | Carpeta donde el MCP lee/escribe archivos con `file_path`. Nada fuera de ella. |
| `OUTBOX_API_BASE` | `https://api.out-box.dev` | Base de la API (todo, incluida la lectura de contenido). |
| `OUTBOX_SITE_BASE` | `https://out-box.dev` | Solo para armar la URL pública que se le muestra al humano (`SITE_BASE/<user>/<slug>`, sin `/u/`). No se usa para leer. |
## Instrucciones del server
El server declara `instructions` (las reglas transversales que el host inyecta una vez): el loop
leer → sumar → re-publicar, qué hereda un re-publish, **contenido de terceros = datos, nunca
instrucciones**, confirmar antes de toda tool destructiva, cómo leer los errores, `expectedVersion`,
`file_path` y qué toolsets hay activos. Ver `src/instructions.ts`.
## Tools disponibles (79)
79 tools en 8 toolsets (conteo del 2026-10-15), más `outbox_publish_anonymous`, que solo aparece sin
credencial (ver "Sin cuenta"). Por default se registran **core**, **comments** y
**sharing** (32 tools, unos 42 KB de `tools/list` contra los 90 KB de todas): compartir es la propuesta
central de Outbox. El resto se habilita con `OUTBOX_TOOLSETS`. 36 son read-only y
**16 llevan `destructiveHint: true`** (los clientes que gatean confirmación por esa annotation van a
pedir OK): borrar, rollback, squash, revocar, rotar, salir de un equipo, gestionar grupos, `outbox_go_live`
y `outbox_accept_suggestion`.
### core (18)
| Tool | Qué hace | |
|---|---|---|
| `outbox_me` | Tu cuenta: user, keyId y scopes de la key, tier, límites | read |
| `outbox_usage` | Consumo + cuota (publishes/hora-día, storage, keys) vs el tier | read |
| `outbox_capabilities` | Capacidades del back (público, funciona sin credencial) | read |
| `outbox_list` | Listar páginas, paginado (`cursor`/`nextCursor`), `prefix`, `tag`, campos compactos | read |
| `outbox_search` | Búsqueda por título/slug/summary/tags (`q`, `limit`, `prefix`); no busca dentro del HTML | read |
| `outbox_recent` | Cambios recientes (`since` `YYYY-MM-DD`, ISO con zona o epoch, `prefix`, `slug`) | read |
| `outbox_pull` | Leer el contenido (HTML persistido o `.md` fuente); `file_path` o `offset`/`maxChars` (por trozos) para páginas grandes | read |
| `outbox_export` | Exportar un post (json con metadata y `version` / html crudo, sin truncar; `file_path`) | read |
| `outbox_versions` | Historial de versiones (`current` sirve de `expectedVersion`) | read |
| `outbox_get_blocks` | Bloques de un daily | read |
| `outbox_publish` | Publicar `html`, `markdown` o `file_path` (`model` obligatorio; `draft`, `expectedVersion`, `rejectOnSecrets`, `idempotencyKey`) | write |
| `outbox_append` | Agregar un bloque a un daily (`model`, default `outbox-mcp`; `createOnly`, `applyAttributes`, `rejectOnSecrets`, `idempotencyKey`) | write |
| `outbox_set_visibility` | private / unlisted / public | write |
| `outbox_upload` | Subir una imagen (png/jpeg/gif/webp) por `file_path` o base64 → URL content-addressed | write |
| `outbox_rollback` | Revertir a una versión | ⚠️ destructivo |
| `outbox_go_live` | Publicar un borrador (o volverlo a borrador) | ⚠️ destructivo |
| `outbox_delete` | Eliminar una página | ⚠️ destructivo |
| `outbox_page_views` | Quién abrió una página: total, hoy, lectores (`link:<destinatario>` para links con nombre) y primera apertura externa. Sirve con cualquier key que pueda leer la página | read |
### comments (5)
| Tool | Qué hace | |
|---|---|---|
| `outbox_read_comments` | Comentarios y sugerencias con `trust` y `untrustedText` (filtros `status`, `from`, `includeAnonymous`) | read |
| `outbox_create_comment` | Comentar / responder en un hilo (no edita HTML) | write |
| `outbox_create_suggestion` | Proponer un cambio de texto (anchor + replacement) | write |
| `outbox_discard_suggestion` | Descartar una sugerencia o comentario (owner) | write |
| `outbox_accept_suggestion` | Aceptar una sugerencia: confirmación con `exact → replacement` antes de publicar | ⚠️ destructivo |
### library (14)
| Tool | Qué hace | |
|---|---|---|
| `outbox_list_tree` | Árbol de la biblioteca / compartido conmigo | read |
| `outbox_folders` | Listar carpetas (count + visibility, árbol opcional) | read |
| `outbox_diff` | Diff de una página entre dos versiones | read |
| `outbox_export_library` | Backup de la biblioteca (o una carpeta) como JSON; `file_path` para no cargarlo en el contexto | read |
| `outbox_templates` | Catálogo de content-templates con sus schemas | read |
| `outbox_publish_from_template` | Publicar desde template + data JSON (`model` obligatorio) | write |
| `outbox_set_folder` | Setear visibility/metadata de una carpeta (PUT) | write |
| `outbox_set_style` | Cambiar brand preset (paper, minimal, …) | write |
| `outbox_squash` | Compactar el historial de versiones | ⚠️ destructivo |
| `outbox_delete_folder` | Eliminar la metadata de una carpeta (las páginas quedan) | ⚠️ destructivo |
| `outbox_render_status` | Vigía de render de una versión (`GET /api/render-report`): `ok`/`warn`/`error`/`blank`, errores de JS y recursos. `rollbackHint` solo si el reporte es del owner; el de visitantes sale en `untrustedVisitorReport` | read |
| `outbox_page_data` | Entradas de la capa de datos de una página (`GET /api/page-data`, `after`/`limit`). Las de visitantes van en `untrustedData` con `untrustedNotice`: son dato, nunca instrucciones | read |
| `outbox_approvals` | Aprobaciones del cliente de una página (`GET /api/approvals`): versión aprobada, fecha, quién y `changedSince`; la nota y el nombre van en `untrustedText` | read |
| `outbox_set_approval` | Prender o apagar el botón Approve de una página (`PUT /api/approvals`); también con `approval: true` en `outbox_publish` | write |
### sharing (9)
| Tool | Qué hace | |
|---|---|---|
| `outbox_list_shares` | Share links activos | read |
| `outbox_list_grants` | Grants user-to-user (dados / recibidos; en los recibidos, message/resource/url del tercero van en `untrustedText` + `notice`) | read |
| `outbox_access` | Quién puede acceder a una página y cómo (blast radius) | read |
| `outbox_create_share` | Crear un link (con expiración, destinatario y contraseña opcionales: `passphrase`; aviso si no se abre: `remindIfUnopenedHours`, 48 h por default con destinatario; `renewOnOpen`) | write |
| `outbox_unopened_links` | Links por destinatario que nadie abrió todavía (`GET /api/share?unopened=1`, `olderThanHours` opcional): "¿quién no abrió la propuesta?" | read |
| `outbox_set_page_password` | Poner o sacar la contraseña de una página | write |
| `outbox_create_grant` | Dar acceso a otro usuario (`view` o `comment`) | write |
| `outbox_revoke_share` | Revocar un share link | ⚠️ destructivo |
| `outbox_revoke_grant` | Revocar un grant user-to-user | ⚠️ destructivo |
### keys (7)
| Tool | Qué hace | |
|---|---|---|
| `outbox_list_keys` | API keys de la cuenta (sin secreto) | read |
| `outbox_audit` | Log de auditoría (`limit`, `since`) | read |
| `outbox_agents_registry` | Registry de agentes instanciables | read |
| `outbox_gen_agent_key` | Emitir agent key folder-scoped (plaintext 1 vez) | ⚠️ sensible |
| `outbox_instantiate_agent` | Instanciar un agente del registry (emite agent key) | ⚠️ sensible |
| `outbox_rotate_key` | Rotar una API key (`keyId` obligatorio; nunca la activa del MCP) | ⚠️ destructivo |
| `outbox_revoke_key` | Revocar una API key (nunca la activa del MCP) | ⚠️ destructivo |
### teams (15)
| Tool | Qué hace | |
|---|---|---|
| `outbox_list_teams` | Equipos de los que sos miembro (el `name` lo eligió el owner original: va en `untrustedText` + `notice`) | read |
| `outbox_list_team_members` | Miembros de un equipo | read |
| `outbox_list_team_keys` | Company keys de un equipo (sin secreto) | read |
| `outbox_create_team` | Crear un equipo/org | write |
| `outbox_add_team_member` | Sumar un miembro (owner-only) | write |
| `outbox_gen_team_key` | Emitir company key (plaintext 1 vez) | ⚠️ sensible |
| `outbox_revoke_team_key` | Revocar una company key (nunca la activa del MCP) | ⚠️ destructivo |
| `outbox_team_invites` | Invitaciones recibidas, o las pendientes de un org (owner/admin) | read |
| `outbox_invite_team_member` | Invitar a alguien al org (acepta o rechaza; vence a los 14 días) | write |
| `outbox_respond_team_invite` | Aceptar o rechazar una invitación (key humana o sesión) | write |
| `outbox_set_team_member` | Cambiar rol (admin/member) o la gestión de company keys de un miembro | write |
| `outbox_team_profile` | Leer o guardar el perfil público del org | write |
| `outbox_remove_team_member` | Quitar un miembro (owner-only) | ⚠️ destructivo |
| `outbox_leave_team` | Salir de un equipo | ⚠️ destructivo |
| `outbox_team_groups` | Grupos del org: cada uno da acceso a proyectos (carpetas) | ⚠️ destructivo |
### automation (9)
| Tool | Qué hace | |
|---|---|---|
| `outbox_webhook_events` | Catálogo de eventos de webhook, leído del back | read |
| `outbox_list_webhooks` | Event webhooks (sin secret) | read |
| `outbox_list_schedules` | Schedules (cron → webhook) | read |
| `outbox_create_webhook` | Registrar un event webhook firmado | write |
| `outbox_pause_webhook` | Pausar / reanudar un event webhook | write |
| `outbox_create_schedule` | Crear un schedule (cron UTC → POST a tu webhook) | write |
| `outbox_pause_schedule` | Pausar / reanudar un schedule | write |
| `outbox_delete_webhook` | Borrar un event webhook | ⚠️ destructivo |
| `outbox_delete_schedule` | Borrar un schedule | ⚠️ destructivo |
### apps (2) — MCP Apps (Ola 2)
| Tool | Qué hace | |
|---|---|---|
| `outbox_show_page` | Abre el **visor interactivo** de una página (MCP App `ui://outbox/page-viewer.html`): metadata, 10 versiones más nuevas, comentarios abiertos y preview aislado. Sin visor devuelve el mismo resumen en `structuredContent`. Comentarios de terceros solo en `untrustedText` (+ `notice`); anónimos por share omitidos salvo `includeAnonymous` | read |
| `outbox_page_preview` | Solo para el visor (`_meta.ui.visibility: ["app"]`): el HTML guardado para el preview. Solo se registra si el host soporta recursos `ui://` | read |
El visor es un recurso `text/html;profile=mcp-app` autocontenido (sin CDN ni red; CSP del host en su
default más estricto). El HTML del usuario va en un iframe **hijo** `srcdoc` con `sandbox=""` (sin
scripts ni same-origin) y una CSP sin scripts: el contenido de la página no puede hablar con el puente
ni llamar tools. Las acciones destructivas (restaurar una versión, aceptar una sugerencia) **no** se
ejecutan desde la app: se le piden al chat (`ui/message`) y el modelo llama la tool, que lleva
`destructiveHint` y la confirma el host. Se habilita con `OUTBOX_TOOLSETS=core,comments,apps`; el MCP
remoto lo trae por default.
`outbox_read` y `outbox_open` se sacaron (dedupe): `outbox_read` era idéntica a `outbox_pull`, y la URL
pública es `https://out-box.dev/<user>/<slug>` (está en las instructions y en la respuesta de publish).
> **`model` es obligatorio** en `outbox_publish` y `outbox_publish_from_template` (contrato B8 del
> back: si falta, responde `400 missing_model`). Es el id del modelo que generó el contenido. El back
> también lo exige en el **primer `outbox_append` de cada día UTC**: `outbox_append` acepta `model`
> (más `summary` y `contentType` opcionales) y, si el agente no lo pasa, manda `outbox-mcp` (mismo
> criterio que el CLI con `outbox-cli`).
> **Daily: `title`/`visibility`, `createOnly` y `applyAttributes`** (contrato del worker, ronda 4).
> `title` y `visibility` son de la página del daily: se aplican en el `outbox_append` que **crea** el día
> (el primero de cada día UTC; si faltan, se heredan del día anterior). En los appends siguientes del mismo
> día se ignoran salvo `applyAttributes: true`, y el resultado los lista en `ignoredAttributes` (el MCP
> suma un aviso que pide no repetir el append). Para cambiar la visibility de un daily sin appendear está
> `outbox_set_visibility`. `createOnly: true` hace que el append solo pueda **crear** un daily: si el slug
> ya tiene uno (de cualquier día), el back responde `409 daily_exists` (con `existingDate`) sin escribir
> nada. Un back anterior a la ronda 4 ignora los dos flags.
> **Tags**: máx 20 por página, cada uno de 1-50 caracteres `[A-Za-z0-9._-]` (sin espacios); el back los
> guarda en minúsculas. Son los límites de `normalizeTags` del worker, que descarta en silencio lo que no
> cumple: el MCP lo rechaza antes con un error de validación.
> **Re-publicar** (el loop central): una página nueva nace `private`. Re-publicar un slug existente
> conserva `title`, `tags`, `summary`, `description`, `contentType`, `visibility`, borrador y TTL que no
> mandes (decisión 2026-09-30, implementada en el worker; `null` limpia). Para no pisar cambios de otro
> agente, pasá `expectedVersion` (la `version` de `outbox_export`): si la página cambió, `409
> version_conflict` con `currentVersion` y no se publica; releé y reintentá. El worker lo chequea de forma
> atómica y lo anuncia en `features.expectedVersion`; contra un back que no lo anuncie, el MCP compara
> antes de escribir (necesita una key con `list`).
> **Comentarios y sugerencias**: en páginas public/unlisted **cualquier cuenta** puede comentar o sugerir.
> Por eso `outbox_read_comments` marca cada ítem con `trust` (`owner` | `grant` | `authenticated` |
> `share-anon`), pone el texto de terceros en `untrustedText` y omite los anónimos por share link salvo
> `includeAnonymous`. `outbox_accept_suggestion` es destructiva: si el cliente soporta *elicitation* le
> pide la confirmación al humano mostrando `exact → replacement` completos; si no, la primera llamada devuelve un
> `preview` (sin recortar) y un `confirmToken`, y hay que volver a llamar con `confirm: true` + ese `confirmToken`
> después de que el usuario apruebe en el chat. Sin el token no se aplica nada. El token es un HMAC con una
> clave derivada de la credencial del MCP (el autor de la sugerencia no puede calcularlo) y vence a los 10 minutos.
> El HTML nunca se modifica por comentar.
> **`outbox_accept_suggestion` no siempre publica `vN+1`.** La respuesta es `{ ok, comment, version, noChange }`.
> Si el reemplazo **no cambia** el HTML resultante, el back aplica un **no-op guard**: devuelve
> `{ ..., noChange: true }`, marca la sugerencia como aceptada y **NO crea una versión nueva**.
> **Errores estructurados.** Todo error trae el texto accionable y, además, el objeto
> `{ error: { code, status, retryable, fix, missingScope?, missingAnyOf?, retryAfter?, upgradeCta?, requestId? } }`
> en `structuredContent` y en un segundo bloque de texto. Casos con mensaje propio:
> `private_read_scope_required` (falta el verbo `list`), `cross_user_export_forbidden`, `version_conflict`,
> `missing_credential`, `network_unreachable` / `network_timeout` (dicen a qué host se intentó llegar),
> `shell_response`, `active_key_self_lockout`, `step_up_required`, `oauth_key_not_rotatable`, `key_expired`
> (409), `secrets_detected` y `daily_exists` (409, con `existingDate`). Si el back manda un `hint`, el error lo trae y, sin caso propio, es el `fix`.
> `requestId` (ronda 4) es el ID de soporte del worker (= header `x-request-id`): citarlo al reportar un error.
> **Secretos.** El back escanea lo que se publica (publish, publish-from-template, append) buscando
> credenciales. Si encuentra alguna, publica igual y el 200 trae `warnings.secrets`; el MCP agrega un aviso
> aparte con tipo y línea (nunca el valor) para que el agente le avise al usuario. Con `rejectOnSecrets: true`
> no se publica nada (422 `secrets_detected`).
> **MFA (step-up).** Si la cuenta tiene MFA, `outbox_rotate_key`, `outbox_gen_agent_key` y
> `outbox_instantiate_agent` responden `step_up_required`. El agente le pide al usuario un código TOTP (o
> de recuperación) y repite la llamada con `mfaCode`. Nunca inventar ni guardar el código.
> **Límites de plan vs permisos.** Un 403/413/429 con código de límite (`daily_docs_limit`, `keys_limit`,
> `storage_limit`, `rate_limited`, …) se informa como límite del **plan**, no como "falta scope", y el error
> trae `upgradeCta: { error, limit, used, tier, upgradeTo, ctaUrl }`. Si el back no manda ese bloque
> (hoy: 413 `html_too_large` de publish), el error dice que es un límite del plan y suma el `message` del
> back. El 429 anti-spam de comentarios sale como 429 genérico con el `retryIn`. Ante un 429: esperar
> `retryAfter` y no reintentar en loop.
> **Idempotencia.** `outbox_publish`, `outbox_append`, `outbox_create_comment`, `outbox_create_suggestion` y
> `outbox_publish_from_template` mandan `Idempotency-Key` (el `idempotencyKey` que pase el agente, o un UUID
> por invocación). El back solo deduplica las operaciones que lista en `features.idempotencyEndpoints`
> (hoy `publish` y `publishFromTemplate`); en el resto el header se ignora. El MCP reintenta por su cuenta
> (una vez, ante una falla de red) **solo** si la operación figura en esa lista: el flag global
> `features.idempotency` no alcanza. Así, hoy `outbox_append`, `outbox_create_comment` y
> `outbox_create_suggestion` no se reintentan (un retry de una escritura ya aplicada duplicaba el bloque o
> el comentario); se reintentan solos cuando el worker los liste (`dailyAppend`, `comment`). Tras un
> timeout en esas tools, verificar con `outbox_get_blocks` / `outbox_read_comments` antes de repetir.
> Desde la ronda 4 la respuesta **exitosa** de esas cinco tools trae la `idempotencyKey` que viajó (campo
> al final del JSON; la del agente o la que generó el MCP), igual que los errores de red. Si el back ya
> manda una, no se pisa.
> **Timeouts.** 30 s por request, 45 s en publish y publish-from-template (por debajo de los 60 s del
> marcador de idempotencia del back, así el reintento con la misma key no duplica) y 60 s en upload. Si el
> reintento recibe `409 idempotency_in_progress`, el MCP espera `Retry-After` y reintenta con la MISMA key
> (hasta 5 veces) antes de devolver el error.
> **Seguridad de rotate/revoke.** `outbox_rotate_key`, `outbox_revoke_key` y `outbox_revoke_team_key` se
> niegan a tocar la key con la que corre el MCP (dejaría al server sin credencial): esa se rota con
> `outbox keys rotate` desde el CLI, que actualiza `~/.outboxrc`.
## Desarrollo
```bash
npm install
npm run build # compila a dist/
npm run test # build + tests unitarios y de contrato (node --test contra dist/, back simulado local)
npm run inspector # probar con MCP Inspector
```
## Uso como módulo: el MCP remoto (Ola 2)
Las tools viven en `src/tools.ts` y se registran con `registerOutboxTools(host, client, opts)`, sin
estado de módulo, sin filesystem y sin imports del SDK. El binario stdio (`src/index.ts`) lo monta sobre el
`McpServer` del SDK v2 (`@modelcontextprotocol/server`, desde la ronda 4; transporte stdio de la era
2025, `initialize`); el Worker de [`out-box-mcp-remote/`](../out-box-mcp-remote/) (mcp.out-box.dev) lo
usa con el SDK v2, OAuth y la agent key del grant.
```ts
import { registerOutboxTools } from "./tools.js";
import { OutboxClient } from "./services/client.js";
const client = new OutboxClient(apiKey, { apiBase, siteBase, fetch, clientHeader: "mcp-remote/0.1.0" });
registerOutboxTools(host, client, {
toolsets: new Set(["core", "comments", "apps"]),
lang: "en", // títulos y descripciones en inglés (src/tools-en.ts)
files: null, // sin filesystem: file_path/overwrite no se publican
include: (name) => allowed(name),
});
```
- `host` expone `registerTool(name, { title, description, inputSchema, annotations, _meta? }, handler)` y,
opcional, `registerResource(...)`. Los `inputSchema` son shapes de **zod 4** (`toObjectSchema(shape)` los
envuelve con el zod de este paquete para el SDK v2).
- `elicit`: función opcional; sin ella `outbox_accept_suggestion` usa el flujo `confirmToken`.
- `pullChunks`: opcional (ronda 4). Suma `offset`/`maxChars` a `outbox_pull`. Lo activa el stdio; el
remoto no, porque parte el contenido en su propio adaptador.
- `confirmKey`: opcional. Clave HMAC del `confirmToken`; por default se deriva de la credencial del
`OutboxClient` (`deriveKey`), así que es estable entre requests de un host stateless y distinta por key/grant.
- El cliente manda `Outbox-Client: mcp/<versión>` (o el que se pase) y `Outbox-Contract: 1` (ARQ-10).
## Lectura del contenido
El contenido se lee **siempre** por `GET /api/u/<user>/<slug>/export?format=html` (el HTML persistido,
apto para re-publicar). El sitio público (`out-box.dev/<user>/<slug>`) con `SANDBOX_SERVE=on` devuelve
un *shell* con un `<iframe src="/raw/...">`: el MCP rechaza cualquier respuesta con `x-outbox-shell: on`.
Para una página de otro usuario que no es pública pero te compartieron (grant, org), `outbox_pull` usa
`/raw/<user>/<slug>` y le saca el script del sandbox. Para leer páginas privadas propias la key necesita
el verbo `list`.
**Por trozos (ronda 4, paridad con el remoto).** `outbox_pull` acepta `offset` y `maxChars` (1000-200000,
default 60000). Sin ninguno de los dos devuelve el contenido completo, como siempre. Con cualquiera, la
respuesta es un trozo explícito: `structuredContent` trae `offset`, `length`, `totalChars`, `nextOffset`
(null en el último), `complete` y `contentSha256` (del contenido completo, igual en todos los trozos de una
misma versión), y un trozo parcial va precedido de un aviso "LECTURA PARCIAL". Se repite con
`offset=nextOffset` y se juntan los trozos en orden; nunca se re-publica una lectura parcial. Un trozo que
cubre todo devuelve exactamente el mismo texto que la lectura sin trozos. No se combina con `file_path`
(error `conflicting_args`); un `offset` fuera del contenido da `invalid_offset`. A diferencia del remoto,
en el stdio el trozo es opt-in (para páginas grandes sigue estando `file_path`).
## Archivos locales (`file_path`)
`outbox_pull`, `outbox_export` y `outbox_export_library` pueden escribir a un archivo, y `outbox_publish` y
`outbox_upload` pueden leer de uno, sin pasar el contenido por el contexto del agente. Todo queda confinado
a `OUTBOX_FILES_DIR` (default `~/Outbox`): paths relativos a esa carpeta, sin `..` ni symlinks que salgan,
extensiones acotadas y sin pisar archivos existentes salvo `overwrite: true`.
This server cannot be deployed