Server MCP

MCP di Deckbase

Server Model Context Protocol per Deckbase. Gli strumenti AI (Cursor, Claude Code, VS Code ecc.) possono leggere la documentazione e gestire mazzi e carte.

Endpoint

Modalità	Endpoint	Autenticazione
Ospitato (HTTP)	POST /api/mcp	`Authorization: Bearer`: chiave API della dashboard o token di accesso OAuth. Stesso percorso in produzione: `/api/mcp`.

OAuth (accesso tramite browser) è il modo più rapido per connettersi: vedi Connessione a Deckbase MCP. Sono disponibili anche chiavi API della dashboard per script e CI. MCP è disponibile per gli abbonati Basic, Pro e VIP. Riferimento completo in docs/public/MCP.md tramite read_doc.

Tool

Documentazione

Tool	Descrizione	Parametri
list_docs	Elenca i file Markdown in `docs/public/`.	Nessuno.
read_doc	Legge una documentazione per percorso. Vengono servite solo le documentazioni in `docs/public/`.	`path`: ad es. `MCP.md` o `deckbase://docs/public/MCP.md`.
list_template_block_types	Chiavi dei tipi di blocco e id numerici (text, media, interactive, layout). Usa prima di `create_template`. Dati statici.	Nessuno.
list_block_schemas	Strutture JSON per tipo di blocco: `blocksSnapshot`, `values`, `configJson`. Usa insieme a `export_deck` per esempi reali.	Nessuno.
list_elevenlabs_voices	Id e etichette delle voci ElevenLabs per `voice_id` in `generate_audio_for_card`. Catalogo curato da Deckbase. Nessuna lettura Firestore dell'utente.	`language`, `gender`, `search` opzionali.
list_ai_image_models	Id dei modelli di immagini AI consentiti per `generate_image_for_card` con etichette e costi in crediti.	Nessuno.

Mazzi e carte: richiedono autenticazione

Tool	Descrizione	Parametri
list_decks	Mazzi dell'utente (`deckId`, titolo, descrizione, `defaultTemplateId` opzionale, `iconEmoji` opzionale).	Nessuno.
create_deck	Crea un mazzo. Restituisce `deckId` e `icon_emoji` / `iconEmoji` se impostato.	`title` (obbligatorio), `description` (opzionale), `icon_emoji` o `iconEmoji` opzionale (una sola emoji; i client AI dovrebbero sceglierne una adatta al titolo, salvo rinuncia esplicita dell'utente).
update_deck	Aggiorna titolo, descrizione, template predefinito o icona del mazzo.	`deckId` (obbligatorio); titolo, descrizione opzionali, `default_template_id`, `icon_emoji` o `iconEmoji` opzionali (stringa vuota rimuove l'icona).
list_templates	Template (`templateId`, nome, descrizione).	Nessuno.
get_template_schema	JSON esatto del layout: `blockId`, tipo, `side` (`"front"` \| `"back"`), `configJson`, `valuesExample`, suggerimenti `create_card`.	`templateId` oppure `deckId` per il template predefinito del mazzo.
create_card	Nuova carta da un template. Restituisce `cardId`, `templateId`, `usedDeckDefault`. `front` riempie il blocco principale; le chiavi `block_text` includono i blocchi del retro (`side` da `get_template_schema`).	`deckId` obbligatorio. Opzionali: `templateId`, `front`, `block_text`, `generate_audio`, `voice_id`, `audio_language`, `audio_gender`.
create_cards	Creazione in blocco. Max 50 per richiesta. In caso di errore: `created` + `failedAt`.	`deckId`, array `cards` (obbligatorio). Opzionali a livello principale: `templateId`, `voice_id`, `generate_audio`.
update_card	Modifica il contenuto di una carta.	`deckId`, `cardId`; opzionali `values` / `blocks_snapshot`, oppure unione di `front` / `block_text`.
delete_card	Eliminazione morbida di una carta (cestino). Il server rifiuta se `user_confirmed` non è true: usalo solo dopo un consenso umano esplicito.	`deckId`, `cardId`, `user_confirmed` (booleano obbligatorio).
delete_cards	Eliminazione morbida in blocco in un mazzo. Stessa regola di consenso di `delete_card`. Max 50 per richiesta.	`deckId`, `card_ids` (array non vuoto), `user_confirmed`.
generate_audio_for_card	TTS ElevenLabs per una carta esistente.	`deckId`, `cardId`. Passa `voice_id` oppure `audio_language` + `audio_gender`. Opzionali: `text`, `block_id`, `replace_existing`.
export_deck	JSON di mazzo + carte. Include `truncated`, `exportType`. L'esportazione completa include `blocksSnapshot` per carta con `side` + `values`.	`deckId` (obbligatorio); opzionali `max_cards` (predefinito 2000, limite 5000), `export_type`: `full` oppure `values_only`.
create_template	Nuovo template (layout di blocchi). Restituisce `templateId` e gli id dei blocchi. Q+A predefinito se `block_types` è omesso.	`name` (obbligatorio); opzionali descrizione, `block_types` / `blocks` (con `side` per blocco), `voice_id`, `audio_language`, `audio_gender`, `mainBlockId` / `subBlockId`.
update_template	Aggiorna metadati e/o layout. Incrementa `version`.	`templateId` (obbligatorio); opzionali nome, descrizione, `block_types` / `blocks`, `voice_id`, `audio_language` + `audio_gender`, `mainBlockId` / `subBlockId`.

I tool che leggono i tuoi dati richiedono un token OAuth valido o una chiave API. list_template_block_types e list_block_schemas restituiscono dati statici (nessuna autenticazione richiesta). list_elevenlabs_voices non legge Firestore. Le richieste non autenticate restituiscono 401.

Risorse

Il server espone risorse MCP per la documentazione in docs/public/:

resources/list

Una risorsa per ogni file .md in docs/public/ (ad es. deckbase://docs/public/MCP.md).

resources/read

Recupera il contenuto della documentazione tramite quell'URI.

Esempio: mazzo, template e carta

1
Configura il tuo client con l'URL MCP e un token bearer: Authorization: Bearer YOUR_API_KEY (oppure un token di accesso OAuth dalla pagina Connect).
2
Chiama list_templates. Se è vuoto, usa prima list_template_block_types e create_template.
3
Chiama get_template_schema con il templateId scelto per conoscere le chiavi esatte blockId e i valori side.
4
Chiama create_deck con un title, description opzionale e icon_emoji quando l'agente deve scegliere un'icona adatta all'argomento.
5
Chiama create_card con deckId e opzionalmente templateId, front (blocco principale) e block_text per gli altri blocchi, incluso il retro.

Dettagli tecnici

ProtocolloMCP 2024-11-05

Nome del serverdeckbase-mcp

OspitatoJSON-RPC 2.0 tramite POST. Usa un token di accesso OAuth o una chiave API della dashboard (Bearer), non un Firebase ID token.

Struttura della cartacreate_card copia il layout di blocchi del template. Ogni blocco include il side del template; valori vuoti per impostazione predefinita. I dati sono memorizzati in Firestore e sincronizzati con la dashboard e l'app mobile.

Per la configurazione del client (Cursor, VS Code, Claude ecc.), vedi Connessione a Deckbase MCP • Per altri collegamenti, vedi Risorse