out-box-mcp

# @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.

### 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`. |
| `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 (77)

77 tools en 8 toolsets (conteo del 2026-10-10). 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`. 35 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 (12)

| 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 |

### 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)