Servidor MCP

MCP de Deckbase

Servidor de Model Context Protocol para Deckbase. Las herramientas de IA (Cursor, Claude Code, VS Code, etc.) pueden leer la documentación y gestionar mazos y tarjetas.

Endpoints

Modo	Endpoint	Autenticación
Hospedado (HTTP)	POST /api/mcp	`Authorization: Bearer`: clave de API del panel o token de acceso OAuth. Misma ruta en producción: `/api/mcp`.

OAuth (inicio de sesión en el navegador) es la forma más rápida de conectarse; consulta Cómo conectar con MCP de Deckbase. Las claves de API del panel también están disponibles para scripts y CI. MCP está disponible para suscriptores Basic, Pro y VIP. Referencia completa en docs/public/MCP.md mediante read_doc.

Herramientas

Documentación

Herramienta	Descripción	Parámetros
list_docs	Enumera los archivos Markdown en `docs/public/`.	Ninguno.
read_doc	Lee un documento por ruta. Solo se sirven documentos en `docs/public/`.	`path`: por ejemplo, `MCP.md` o `deckbase://docs/public/MCP.md`.
list_template_block_types	Claves de tipos de bloque e ids numéricos (text, media, interactive, layout). Úsala antes de `create_template`. Datos estáticos.	Ninguno.
list_block_schemas	Estructuras JSON por tipo de bloque: `blocksSnapshot`, `values`, `configJson`. Combínala con `export_deck` para ver ejemplos reales.	Ninguno.
list_elevenlabs_voices	Ids y etiquetas de voces de ElevenLabs para `voice_id` en `generate_audio_for_card`. Catálogo curado de Deckbase. No lee Firestore del usuario.	`language`, `gender` y `search` opcionales.
list_ai_image_models	Ids de modelos de imágenes de IA permitidos para `generate_image_for_card`, con etiquetas y costos en créditos.	Ninguno.

Mazos y tarjetas (requieren autenticación)

Herramienta	Descripción	Parámetros
list_decks	Mazos del usuario (`deckId`, título, descripción, `defaultTemplateId` opcional, `iconEmoji` opcional).	Ninguno.
create_deck	Crea un mazo. Devuelve `deckId` y `icon_emoji` / `iconEmoji` cuando están definidos.	`title` (obligatorio), `description` (opcional), `icon_emoji` o `iconEmoji` opcionales (un solo emoji; los clientes de IA deben elegir uno acorde con el título a menos que el usuario indique lo contrario).
update_deck	Actualiza título, descripción, plantilla predeterminada o ícono del mazo.	`deckId` (obligatorio); título, descripción, `default_template_id`, `icon_emoji` o `iconEmoji` opcionales (una cadena vacía borra el ícono).
list_templates	Plantillas (`templateId`, nombre, descripción).	Ninguno.
get_template_schema	JSON exacto del diseño: `blockId`, tipo, `side` (`"front"` \| `"back"`), `configJson`, `valuesExample`, sugerencias de `create_card`.	`templateId` o `deckId` para la plantilla predeterminada del mazo.
create_card	Nueva tarjeta a partir de una plantilla. Devuelve `cardId`, `templateId`, `usedDeckDefault`. `front` rellena el bloque principal; las claves de `block_text` incluyen bloques del reverso (`side` según `get_template_schema`).	`deckId` obligatorio. Opcionales: `templateId`, `front`, `block_text`, `generate_audio`, `voice_id`, `audio_language`, `audio_gender`.
create_cards	Creación en lote. Máximo 50 por solicitud. En caso de error: `created` + `failedAt`.	`deckId` y arreglo `cards` (obligatorios). Opcionales a nivel superior: `templateId`, `voice_id`, `generate_audio`.
update_card	Edita el contenido de una tarjeta.	`deckId`, `cardId`; opcionales `values` / `blocks_snapshot`, o combina `front` / `block_text`.
delete_card	Elimina suavemente una tarjeta (papelera). El servidor se niega a menos que `user_confirmed` sea true; úsala solo después del consentimiento explícito del usuario.	`deckId`, `cardId`, `user_confirmed` (booleano obligatorio).
delete_cards	Eliminación suave en lote dentro de un mazo. Misma regla de consentimiento que `delete_card`. Máximo 50 por solicitud.	`deckId`, `card_ids` (arreglo no vacío), `user_confirmed`.
generate_audio_for_card	TTS de ElevenLabs para una tarjeta existente.	`deckId`, `cardId`. Pasa `voice_id` o `audio_language` + `audio_gender`. Opcionales: `text`, `block_id`, `replace_existing`.
export_deck	JSON del mazo con sus tarjetas. Incluye `truncated` y `exportType`. La exportación completa incluye `blocksSnapshot` por tarjeta con `side` + `values`.	`deckId` (obligatorio); opcionales `max_cards` (predeterminado 2000, tope 5000), `export_type`: `full` o `values_only`.
create_template	Nueva plantilla (diseño de bloques). Devuelve `templateId` e ids de bloques. Pregunta y respuesta por defecto si se omite `block_types`.	`name` (obligatorio); opcionales description, `block_types` / `blocks` (`side` por bloque), `voice_id`, `audio_language`, `audio_gender`, `mainBlockId` / `subBlockId`.
update_template	Actualiza metadatos o diseño. Incrementa `version`.	`templateId` (obligatorio); opcionales name, description, `block_types` / `blocks`, `voice_id`, `audio_language` + `audio_gender`, `mainBlockId` / `subBlockId`.

Las herramientas que leen tus datos requieren un token OAuth válido o una clave de API. list_template_block_types y list_block_schemas devuelven datos estáticos (sin autenticación). list_elevenlabs_voices no lee Firestore. Las solicitudes sin autenticación devuelven 401.

Recursos

El servidor expone recursos MCP para la documentación en docs/public/:

resources/list

Un recurso por cada archivo .md en docs/public/ (por ejemplo, deckbase://docs/public/MCP.md).

resources/read

Obtiene el contenido del documento mediante esa URI.

Ejemplo: mazo, plantilla y tarjeta

1
Configura tu cliente con la URL del MCP y un token Bearer: Authorization: Bearer YOUR_API_KEY (o un token de acceso OAuth desde la página Connect).
2
Llama a list_templates. Si está vacía, usa primero list_template_block_types y create_template.
3
Llama a get_template_schema con el templateId elegido para conocer las claves exactas de blockId y los valores de side.
4
Llama a create_deck con un title, description opcional y icon_emoji cuando el agente deba elegir un ícono acorde al tema.
5
Llama a create_card con deckId y, opcionalmente, templateId, front (bloque principal) y block_text para los demás bloques, incluido el reverso.

Detalles técnicos

ProtocoloMCP 2024-11-05

Nombre del servidordeckbase-mcp

HospedadoJSON-RPC 2.0 por POST. Usa un token de acceso OAuth o una clave de API del panel (Bearer), no un token de ID de Firebase.

Estructura de la tarjetacreate_card copia el diseño de bloques de la plantilla. Cada bloque incluye side según la plantilla; los valores están vacíos por defecto. Los datos se guardan en Firestore y se sincronizan con el panel y la app móvil.

Para configurar el cliente (Cursor, VS Code, Claude, etc.), consulta Cómo conectar con MCP de Deckbase • Para otros enlaces, consulta Recursos