MCP-сервер
Deckbase MCP
Сервер Model Context Protocol для Deckbase. AI-инструменты (Cursor, Claude Code, VS Code и др.) могут читать документацию и управлять колодами и карточками.
Эндпоинты
| Режим | Эндпоинт | Авторизация |
|---|---|---|
| Облачный (HTTP) | POST /api/mcp | Authorization: Bearer: API-ключ из панели управления или OAuth access token. Тот же путь в продакшене: /api/mcp. |
Самый быстрый способ подключиться: OAuth (вход через браузер), см. Подключение к Deckbase MCP. API-ключи из панели управления тоже доступны для скриптов и CI. MCP доступен подписчикам Basic, Pro и VIP. Полный справочник в docs/public/MCP.md через read_doc.
Инструменты
| Инструмент | Описание | Параметры |
|---|---|---|
| list_docs | Список Markdown-файлов в docs/public/. | Нет. |
| read_doc | Читает документ по пути. Отдаются только документы из docs/public/. | path, например MCP.md или deckbase://docs/public/MCP.md. |
| list_template_block_types | Ключи типов блоков и их числовые id (text, media, interactive, layout). Используй перед create_template. Статические данные. | Нет. |
| list_block_schemas | JSON-структуры для каждого типа блока: blocksSnapshot, values, configJson. Смотри вместе с export_deck, чтобы получить реальные примеры. | Нет. |
| list_elevenlabs_voices | id и названия голосов ElevenLabs для voice_id в generate_audio_for_card. Курируемый каталог Deckbase. Без чтения пользовательского Firestore. | Необязательные language, gender, search. |
| list_ai_image_models | Разрешённые id AI-моделей изображений для generate_image_for_card с названиями и стоимостью в кредитах. | Нет. |
| Инструмент | Описание | Параметры |
|---|---|---|
| list_decks | Колоды пользователя (deckId, название, описание, необязательные defaultTemplateId и iconEmoji). | Нет. |
| create_deck | Создаёт колоду. Возвращает deckId, а также icon_emoji / iconEmoji, если они заданы. | title (обязательно), description (необязательно), необязательный icon_emoji или iconEmoji (один эмодзи; AI-клиенты должны выбирать подходящий к названию, если пользователь не против). |
| update_deck | Обновляет название, описание, шаблон по умолчанию или иконку колоды. | deckId (обязательно); необязательные title, description, default_template_id, icon_emoji или iconEmoji (пустая строка убирает иконку). |
| list_templates | Шаблоны (templateId, название, описание). | Нет. |
| get_template_schema | Точный JSON для макета: blockId, тип, side ("front" | "back"), configJson, valuesExample, подсказки для create_card. | templateId или deckId для шаблона по умолчанию этой колоды. |
| create_card | Новая карточка из шаблона. Возвращает cardId, templateId, usedDeckDefault. front заполняет основной блок; ключи block_text включают блоки обратной стороны (side из get_template_schema). | deckId обязателен. Необязательные templateId, front, block_text, generate_audio, voice_id, audio_language, audio_gender. |
| create_cards | Массовое создание. Максимум 50 за запрос. При ошибке: created + failedAt. | deckId, массив cards (обязательно). Необязательные на верхнем уровне templateId, voice_id, generate_audio. |
| update_card | Редактирует содержимое карточки. | deckId, cardId; необязательные values / blocks_snapshot или слияние front / block_text. |
| delete_card | Мягко удаляет одну карточку (в корзину). Сервер откажет, если user_confirmed не true: используй только после явного согласия человека. | deckId, cardId, user_confirmed (обязательный boolean). |
| delete_cards | Массовое мягкое удаление в одной колоде. То же правило согласия, что и в delete_card. Максимум 50 за запрос. | deckId, card_ids (непустой массив), user_confirmed. |
| generate_audio_for_card | ElevenLabs TTS для существующей карточки. | deckId, cardId. Передай voice_id либо audio_language + audio_gender. Необязательные text, block_id, replace_existing. |
| export_deck | JSON колоды и карточек. Включает truncated, exportType. Полный экспорт содержит blocksSnapshot для каждой карточки с side + values. | deckId (обязательно); необязательные max_cards (по умолчанию 2000, максимум 5000), export_type: full или values_only. |
| create_template | Новый шаблон (макет блоков). Возвращает templateId и id блоков. По умолчанию вопрос + ответ, если block_types не указан. | name (обязательно); необязательные description, block_types / blocks (side для каждого блока), voice_id, audio_language, audio_gender, mainBlockId / subBlockId. |
| update_template | Обновляет метаданные и/или макет. Повышает version. | templateId (обязательно); необязательные name, description, block_types / blocks, voice_id, audio_language + audio_gender, mainBlockId / subBlockId. |
list_template_block_types и list_block_schemas возвращают статические данные (аутентификация не нужна). list_elevenlabs_voices не читает Firestore. Запросы без аутентификации возвращают 401.Ресурсы
Сервер предоставляет MCP-ресурсы для документов в docs/public/:
resources/listОдин ресурс на каждый .md-файл в docs/public/ (например, deckbase://docs/public/MCP.md).
resources/readПолучает содержимое документа по этому URI.
Пример: колода, шаблон и карточка
- 1
Настрой клиента с MCP URL и bearer-токеном:
Authorization: Bearer YOUR_API_KEY(или OAuth access token со страницы подключения). - 2
Вызови list_templates. Если список пуст, сначала используй list_template_block_types и create_template.
- 3
Вызови get_template_schema с выбранным
templateId, чтобы узнать точные ключиblockIdи значенияside. - 4
Вызови create_deck с
title, необязательнымdescriptionиicon_emoji, когда агент должен подобрать подходящую иконку для темы. - 5
Вызови create_card с
deckIdи, при необходимости,templateId,front(основной блок) иblock_textдля остальных блоков, включая обратную сторону.
Технические детали
Как настроить клиент (Cursor, VS Code, Claude и др.), смотри в разделе Подключение к Deckbase MCP • Другие ссылки смотри в разделе Ресурсы