# Servidor MCP de Mockdraft

Mockdraft sirve para revisar y aprobar prototipos visuales de aplicaciones o sitios web, hechos en HTML. Un equipo de diseño sube un prototipo, su cliente marca y comenta directamente sobre el diseño, y aprueba cada versión cuando está lista.

El servidor MCP es una integración opcional. Permite que un asistente de IA compatible con el Model Context Protocol trabaje con los prototipos de un equipo: encontrar un prototipo, leer el feedback del cliente como instrucciones, obtener el HTML de la versión actual, publicar la siguiente versión y cerrar las marcas que atiende.

- Dirección: `https://mockdraft.dev/mcp`
- Transporte: Streamable HTTP, sin estado. Solo `POST`; `GET` y `DELETE` responden `405`. Las respuestas son JSON (sin stream del servidor).
- Autenticación: `Authorization: Bearer md_…`, un token personal.
- Idioma: los nombres de las herramientas, sus parámetros y sus respuestas están en español.

## Conceptos

| Término | Qué es |
| --- | --- |
| Equipo | El equipo de diseño o la agencia. Cada token, prototipo y cliente pertenece a un equipo. |
| Cliente | La empresa para la que se hace el prototipo. Tiene personas de contacto que revisan. |
| Prototipo | La aplicación o el sitio web en revisión, por ejemplo «Sitio web 2027». Tiene versiones numeradas. |
| Versión | Cada subida del prototipo: v1, v2, v3… Cada una es un documento HTML completo. |
| Marca | Un comentario numerado sobre una versión, anclado a un elemento de la página. Puede estar abierta (`abierta`) o resuelta (`resuelta`) y tener respuestas. |
| Enlace de revisión | El enlace privado que abre el cliente para revisar. El cliente no necesita cuenta. |
| Aprobación | La conformidad del cliente con una versión, con el nombre completo que escribió y la fecha. No se edita ni se deshace. |
| Acuerdo de confidencialidad | El acuerdo del equipo que cada persona del cliente acepta antes de ver un prototipo, si el equipo lo pide. Cada aceptación guarda una copia del texto. |

### Estados de una versión

El estado de una versión indica qué se le pide al cliente (el «pedido»).

| Estado | Etiqueta | Qué puede hacer el cliente |
| --- | --- | --- |
| `borrador` | Borrador | Nada. Solo la ve el equipo. |
| `comentarios` | Para comentarios | Marcar y comentar, pero todavía no aprobar. |
| `revision` | En revisión | Marcar, comentar y aprobar. |
| `cambios` | Cambios pedidos | El cliente pidió cambios. |
| `aprobada` | Aprobada | Nada más: una versión aprobada ya no cambia. |

Un equipo puede compartir una versión primero solo para comentarios y pedir la aprobación después, sobre la misma versión, sin volver a subirla.

### Tipos de marca

| Tipo | Qué significa para quien aplica el feedback |
| --- | --- |
| Nota | Un comentario fijado a un elemento. |
| `circular` | Esto se queda como está. |
| `tachar` | Quitar o cambiar esto. |
| `flecha` | Mover esto o relacionarlo con otro elemento. |
| `resaltar` | Reescribir este texto. |

Cada marca apunta a un elemento con un selector CSS y lleva el comentario del cliente, si lo hay.

## Conexión

### 1. Crear un token

1. Entre en https://mockdraft.dev/entrar. El acceso se solicita; no hay registro público.
2. Vaya a Ajustes → Integraciones y cree un token.
3. Cópielo en ese momento. Empieza por `md_`, se muestra una sola vez y Mockdraft solo guarda su huella (hash).

El token actúa en nombre de esa persona, dentro de su equipo. Deja de funcionar si se revoca o si la persona sale del equipo. Cada persona puede tener hasta 20 tokens activos.

### 2. Configurar el cliente MCP

La mayoría de los clientes que admiten servidores remotos aceptan una configuración como esta. Los nombres de las claves cambian de un cliente a otro (algunos usan `transport` en lugar de `type`), así que conviene revisar la documentación del cliente.

```json
{
  "mcpServers": {
    "mockdraft": {
      "type": "http",
      "url": "https://mockdraft.dev/mcp",
      "headers": { "Authorization": "Bearer md_SU_TOKEN" }
    }
  }
}
```

Los clientes que solo ejecutan servidores locales (stdio) pueden conectarse con el puente `mcp-remote`:

```json
{
  "mcpServers": {
    "mockdraft": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mockdraft.dev/mcp", "--header", "Authorization:${MOCKDRAFT_AUTH}"],
      "env": { "MOCKDRAFT_AUTH": "Bearer md_SU_TOKEN" }
    }
  }
}
```

No guarde el token en archivos compartidos ni en repositorios. Si el cliente tiene un almacén de secretos o admite variables de entorno, úselos.

### 3. Comprobar la conexión

```bash
curl -s https://mockdraft.dev/mcp \
  -H "Authorization: Bearer $MOCKDRAFT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Con un token válido responde la lista de herramientas. Con uno inválido o revocado responde `401` con un error JSON-RPC.

## Herramientas

| Herramienta | Qué hace | Escribe |
| --- | --- | --- |
| `listar_prototipos` | Lista los prototipos activos del equipo con su versión actual, estado y marcas abiertas. | No |
| `ver_prototipo` | Muestra las versiones de un prototipo, sus estados, quién aprobó y cuántos revisores tiene. | No |
| `crear_prototipo` | Crea un prototipo nuevo y, si no existe, su cliente. | Sí |
| `publicar_version` | Publica una versión nueva a partir de un documento HTML completo. | Sí |
| `cambiar_pedido` | Cambia lo que se le pide al cliente con la última versión: solo comentarios o también la aprobación. | Sí |
| `obtener_feedback` | Devuelve el feedback del cliente sobre una versión como un prompt listo para aplicar, con el detalle de cada marca. | No |
| `obtener_html` | Devuelve el HTML completo de una versión. | No |
| `resolver_marcas` | Marca como resueltas una o varias marcas de una versión. | Sí |

### `listar_prototipos`

| Parámetro | Tipo | Qué es |
| --- | --- | --- |
| `estado` | `borrador` \| `comentarios` \| `revision` \| `cambios` \| `aprobada`, opcional | Solo los prototipos cuya versión actual está en ese estado. |
| `buscar` | texto, opcional | Texto a buscar en el nombre del prototipo. |

Sirve para encontrar el id del prototipo (`prototipo_id`), que piden todas las demás herramientas.

### `ver_prototipo`

| Parámetro | Tipo | Qué es |
| --- | --- | --- |
| `prototipo_id` | UUID | El prototipo. |

### `crear_prototipo`

| Parámetro | Tipo | Qué es |
| --- | --- | --- |
| `nombre` | texto, de 1 a 120 caracteres | Nombre del prototipo. |
| `cliente` | texto, opcional | Nombre del cliente. Se crea si no existe. |

El prototipo nuevo no tiene versiones. La primera se publica con `publicar_version`.

### `publicar_version`

| Parámetro | Tipo | Qué es |
| --- | --- | --- |
| `prototipo_id` | UUID | El prototipo. |
| `html` | texto, hasta 2.000.000 de caracteres, opcional | El documento HTML completo de la versión (`index.html`, con `<html>…</html>`). Puede llevar JavaScript y animaciones. Obligatorio salvo que `archivos` incluya `index.html`. |
| `archivos` | lista, opcional, hasta 200 | Los demás archivos del prototipo: scripts, estilos, imágenes, fuentes, datos. Cada uno es `{ "ruta": "js/app.js", "contenido": "…", "base64": false }`. Las rutas son relativas a `index.html`, sin `/` inicial ni `..`. Los archivos binarios van en base64 con `"base64": true`. |
| `resumen` | texto, opcional, hasta 500 caracteres | Qué cambió, en una o dos frases para el cliente. |
| `resuelve` | lista de enteros, opcional | Números de las marcas de la versión anterior que atiende esta versión. Se marcan como resueltas. |
| `pedido` | `revision` \| `comentarios` \| `borrador`, opcional | Qué se le pide al cliente. `revision` (por defecto): comentar y aprobar. `comentarios`: solo comentar, sin aprobar todavía. `borrador`: el cliente no la ve. |

El parámetro antiguo `enviar_a_revision` sigue funcionando (`false` equivale a `borrador`), pero lo reemplaza `pedido`.

La respuesta puede traer avisos (`Avisos`): rutas absolutas que se pasaron a relativas, archivos que la página usa y no se enviaron, recursos por `http://` o tipos de archivo no admitidos. Conviene leerlos y corregir lo que señalan en la siguiente versión.

### `cambiar_pedido`

| Parámetro | Tipo | Qué es |
| --- | --- | --- |
| `prototipo_id` | UUID | El prototipo. Siempre actúa sobre su última versión. |
| `pedido` | `revision` \| `comentarios` | `revision`: pedir la aprobación del cliente. `comentarios`: solo comentarios. |

Un borrador puede pasar a cualquiera de los dos. Una versión aprobada ya no cambia.

### `obtener_feedback`

| Parámetro | Tipo | Qué es |
| --- | --- | --- |
| `prototipo_id` | UUID | El prototipo. |
| `version` | entero, opcional | Número de versión. Por defecto, la última. |
| `incluir_resueltas` | booleano, opcional | Incluir también las marcas resueltas, como contexto. |

### `obtener_html`

| Parámetro | Tipo | Qué es |
| --- | --- | --- |
| `prototipo_id` | UUID | El prototipo. |
| `version` | entero, opcional | Número de versión. Por defecto, la última. |

### `resolver_marcas`

| Parámetro | Tipo | Qué es |
| --- | --- | --- |
| `prototipo_id` | UUID | El prototipo. |
| `numeros` | lista de enteros | Números de las marcas que se resuelven. |
| `version` | entero, opcional | Número de versión. Por defecto, la última. |

## JavaScript y prototipos con varios archivos

Mockdraft no sanitiza ni quita código: el JavaScript del prototipo se ejecuta tal cual. Lo que lo hace seguro es el aislamiento.

Funciona:

- Scripts en línea y desde CDNs por `https://`, módulos ES, `fetch` a los archivos del propio prototipo, fuentes propias, animaciones con CSS y JavaScript, canvas, vídeo y audio.
- `localStorage`, `sessionStorage` y cookies, guardados en memoria mientras dura la visita (el prototipo corre en un origen aislado, sin almacenamiento real).
- `alert`, `confirm` y `prompt`, y enlaces que abren una pestaña nueva.
- Secciones de pantalla completa (`100vh`), barras fijas y animaciones con scroll: el prototipo se muestra como en un navegador, en una pantalla de alto fijo con su propio scroll. Anchos de escritorio, tablet (820 × 1180) y móvil (390 × 844).
- Varias páginas enlazadas con rutas relativas (`acerca.html`).

Reglas:

- Use rutas relativas (`js/app.js`, `./img/logo.png`). Las rutas absolutas (`/assets/app.js`) que apuntan a archivos subidos se corrigen en el HTML, el CSS y las cadenas de recursos del JavaScript, pero no en los imports de JavaScript. Si compila con Vite, configure `base: './'`.
- Cargue los recursos externos por `https://`.
- Los formularios no se pueden enviar a un servidor y el prototipo no puede navegar la página de Mockdraft. Los formularios se manejan con JavaScript (`preventDefault`).
- Las marcas se anclan a elementos. Las marcas sobre elementos que solo existen tras una interacción (un menú o un modal abierto) aparecen cuando ese elemento está en pantalla.

## Flujos habituales

### Aplicar el feedback del cliente

1. `listar_prototipos` para encontrar el prototipo y su id.
2. `obtener_feedback` para leer las marcas abiertas de la versión actual.
3. `obtener_html` para partir del HTML de esa versión.
4. Hacer los cambios y llamar a `publicar_version` con el HTML completo, un `resumen` breve y, en `resuelve`, los números de las marcas atendidas.

Los números de marca nunca se inventan: se usan los que devuelve `obtener_feedback`.

### Compartir para comentarios y pedir la aprobación después

1. `publicar_version` con `pedido: "comentarios"`. El cliente puede marcar y comentar, pero no ve el botón para aprobar.
2. Cuando la versión esté lista, `cambiar_pedido` con `pedido: "revision"`. El cliente ya puede aprobarla, y las marcas que dejó se quedan donde están.

### Empezar un prototipo nuevo

1. `crear_prototipo` con el nombre y el cliente.
2. `publicar_version` con el primer HTML.
3. Una persona del equipo comparte el enlace de revisión desde la aplicación (Compartir). El servidor MCP no envía enlaces ni mensajes a los clientes.

## Límites

- Cada petición: hasta 3 MB.
- `html`: hasta 2.000.000 de caracteres. `html` más `archivos`: hasta 2.500.000 caracteres en total. Los prototipos más grandes se suben como `.zip` desde la aplicación (hasta 50 MB).
- Todo queda limitado al equipo del token. Un prototipo de otro equipo responde como si no existiera.
- La aprobación solo ocurre en la página de revisión del cliente. Ninguna herramienta puede aprobar una versión.

## Errores

Los errores de una herramienta llegan como un resultado normal con `isError: true` y un mensaje en español, por ejemplo «No existe un prototipo con ese id en tu equipo.». Los errores de transporte usan JSON-RPC: `401` si falta el token, es inválido o está revocado; `405` para cualquier método que no sea `POST`; `413` si la petición supera los 3 MB.

## Más información

- Mockdraft: https://mockdraft.dev
- Solicitar acceso: https://mockdraft.dev/#acceso
- Índice para asistentes de IA: https://mockdraft.dev/llms.txt
