Servidor MCP

Deckbase MCP

Servidor Model Context Protocol para o Deckbase. Ferramentas de IA (Cursor, Claude Code, VS Code etc.) podem ler a documentação e gerenciar baralhos e cartões.

Endpoints

Modo	Endpoint	Autenticação
Hospedado (HTTP)	POST /api/mcp	`Authorization: Bearer`: chave de API do painel ou token de acesso OAuth. Mesmo caminho em produção: `/api/mcp`.

O OAuth (login pelo navegador) é a forma mais rápida de conectar: veja Conectando ao MCP do Deckbase. As chaves de API do painel também estão disponíveis para scripts e CI. O MCP está disponível para assinantes Basic, Pro e VIP. Referência completa em docs/public/MCP.md via read_doc.

Ferramentas

Documentação

Ferramenta	Descrição	Parâmetros
list_docs	Lista os arquivos Markdown em `docs/public/`.	Nenhum.
read_doc	Lê um documento pelo caminho. Apenas os documentos em `docs/public/` são servidos.	`path`: por exemplo, `MCP.md` ou `deckbase://docs/public/MCP.md`.
list_template_block_types	Chaves de tipo de bloco e ids numéricos (text, media, interactive, layout). Use antes de `create_template`. Dados estáticos.	Nenhum.
list_block_schemas	Formatos JSON por tipo de bloco: `blocksSnapshot`, `values`, `configJson`. Combine com `export_deck` para ver exemplos reais.	Nenhum.
list_elevenlabs_voices	Ids e rótulos de vozes do ElevenLabs para `voice_id` em `generate_audio_for_card`. Catálogo curado do Deckbase. Nenhuma leitura no Firestore do usuário.	`language`, `gender` e `search` opcionais.
list_ai_image_models	Ids permitidos de modelos de imagem de IA para `generate_image_for_card`, com rótulos e custos em créditos.	Nenhum.

Baralhos e cartões: exigem autenticação

Ferramenta	Descrição	Parâmetros
list_decks	Baralhos do usuário (`deckId`, título, descrição, `defaultTemplateId` opcional, `iconEmoji` opcional).	Nenhum.
create_deck	Cria um baralho. Retorna `deckId` e `icon_emoji` / `iconEmoji` quando definidos.	`title` (obrigatório), `description` (opcional), `icon_emoji` ou `iconEmoji` opcional (um único emoji; clientes de IA devem escolher um que combine com o título, a menos que o usuário recuse).
update_deck	Atualiza o título, a descrição, o modelo padrão ou o ícone do baralho.	`deckId` (obrigatório); título, descrição, `default_template_id`, `icon_emoji` ou `iconEmoji` opcionais (uma string vazia remove o ícone).
list_templates	Modelos (`templateId`, nome, descrição).	Nenhum.
get_template_schema	JSON exato do layout: `blockId`, tipo, `side` (`"front"` \| `"back"`), `configJson`, `valuesExample`, dicas de `create_card`.	`templateId` ou `deckId` para o modelo padrão do baralho.
create_card	Novo cartão a partir de um modelo. Retorna `cardId`, `templateId` e `usedDeckDefault`. `front` preenche o bloco principal; as chaves de `block_text` incluem blocos do verso (`side` vindo de `get_template_schema`).	`deckId` obrigatório. Opcionais: `templateId`, `front`, `block_text`, `generate_audio`, `voice_id`, `audio_language`, `audio_gender`.
create_cards	Criação em lote. Máximo de 50 por requisição. Em caso de falha: `created` + `failedAt`.	`deckId` e array `cards` (obrigatórios). Opcionais no nível superior: `templateId`, `voice_id`, `generate_audio`.
update_card	Edita o conteúdo de um cartão.	`deckId`, `cardId`; opcionalmente `values` / `blocks_snapshot`, ou mescle `front` / `block_text`.
delete_card	Exclusão lógica (lixeira) de um cartão. O servidor recusa a operação, a menos que `user_confirmed` seja true: use apenas após consentimento humano explícito.	`deckId`, `cardId`, `user_confirmed` (booleano obrigatório).
delete_cards	Exclusão lógica em lote em um único baralho. Mesma regra de consentimento de `delete_card`. Máximo de 50 por requisição.	`deckId`, `card_ids` (array não vazio), `user_confirmed`.
generate_audio_for_card	TTS do ElevenLabs para um cartão existente.	`deckId`, `cardId`. Informe `voice_id` ou `audio_language` + `audio_gender`. Opcionais: `text`, `block_id`, `replace_existing`.
export_deck	JSON do baralho + cartões. Inclui `truncated` e `exportType`. A exportação completa inclui `blocksSnapshot` por cartão com `side` + `values`.	`deckId` (obrigatório); opcionais `max_cards` (padrão 2000, limite 5000) e `export_type`: `full` ou `values_only`.
create_template	Novo modelo (layout de blocos). Retorna `templateId` e os ids dos blocos. Padrão Q+A caso `block_types` seja omitido.	`name` (obrigatório); descrição, `block_types` / `blocks` (`side` por bloco), `voice_id`, `audio_language`, `audio_gender`, `mainBlockId` / `subBlockId` opcionais.
update_template	Atualiza metadados e/ou layout. Incrementa `version`.	`templateId` (obrigatório); nome, descrição, `block_types` / `blocks`, `voice_id`, `audio_language` + `audio_gender`, `mainBlockId` / `subBlockId` opcionais.

As ferramentas que leem seus dados exigem um token OAuth válido ou uma chave de API. list_template_block_types e list_block_schemas retornam dados estáticos (sem necessidade de autenticação). list_elevenlabs_voices não lê o Firestore. Requisições não autenticadas retornam 401.

Recursos

O servidor expõe recursos MCP para os documentos em docs/public/:

resources/list

Um recurso por arquivo .md em docs/public/ (por exemplo, deckbase://docs/public/MCP.md).

resources/read

Busca o conteúdo do documento por esse URI.

Exemplo: baralho, modelo e cartão

1
Configure seu cliente com a URL do MCP e um token bearer: Authorization: Bearer YOUR_API_KEY (ou um token de acesso OAuth da página de conexão).
2
Chame list_templates. Se estiver vazio, use list_template_block_types e create_template primeiro.
3
Chame get_template_schema com o templateId escolhido para descobrir as chaves exatas de blockId e os valores de side.
4
Chame create_deck com um title, um description opcional e icon_emoji quando o agente deve escolher um ícone que combine com o tema.
5
Chame create_card com deckId e, opcionalmente, templateId, front (bloco principal) e block_text para os demais blocos, incluindo o verso.

Detalhes técnicos

ProtocoloMCP 2024-11-05

Nome do servidordeckbase-mcp

HospedadoJSON-RPC 2.0 sobre POST. Use um token de acesso OAuth ou uma chave de API do painel (Bearer), não um token de ID do Firebase.

Estrutura do cartãocreate_card copia o layout de blocos do modelo. Cada bloco inclui o side do modelo; valores vazios por padrão. Os dados são armazenados no Firestore e sincronizados com o painel e o app mobile.

Para configurar seu cliente (Cursor, VS Code, Claude etc.), veja Conectando ao MCP do Deckbase • Para outros links, veja Recursos