MCP 服务器
Deckbase MCP
适用于 Deckbase 的 Model Context Protocol 服务器。AI 工具（Cursor、Claude Code、VS Code 等）可以读取文档，并管理牌组和卡片。
端点
| 模式 | 端点 | 身份验证 |
|---|---|---|
| 托管模式（HTTP） | POST /api/mcp | Authorization: Bearer：仪表板 API 密钥或 OAuth 访问令牌。生产环境使用同一路径：/api/mcp。 |
OAuth（浏览器登录）是最快的连接方式，详见连接 Deckbase MCP。脚本和 CI 也可以使用仪表板 API 密钥。MCP 面向 Basic、Pro 和 VIP 订阅用户开放。完整参考见 docs/public/MCP.md，可通过 read_doc 读取。
工具
| 工具 | 说明 | 参数 |
|---|---|---|
| list_docs | 列出 docs/public/ 中的 Markdown 文件。 | 无。 |
| 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 | 用于 generate_audio_for_card 中 voice_id 的 ElevenLabs 语音 ID 和名称。Deckbase 精选目录。不读取用户的 Firestore 数据。 | 可选：language、gender、search。 |
| list_ai_image_models | 可用于 generate_image_for_card 的 AI 图像模型 ID，含名称和点数消耗。 | 无。 |
| 工具 | 说明 | 参数 |
|---|---|---|
| list_decks | 用户的牌组（deckId、标题、描述、可选的 defaultTemplateId、可选的 iconEmoji）。 | 无。 |
| create_deck | 创建牌组。返回 deckId，若设置了图标则返回 icon_emoji / iconEmoji。 | title（必填）、description（可选）、可选的 icon_emoji 或 iconEmoji（单个 emoji；除非用户明确不要，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（必填布尔值）。 |
| 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，默认使用问答（Q+A）布局。 | 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。资源
服务器会为 docs/public/ 中的文档提供 MCP 资源：
resources/listdocs/public/ 中的每个 .md 文件对应一个资源（例如 deckbase://docs/public/MCP.md）。
resources/read通过该 URI 获取文档内容。
示例：牌组、模板和卡片
- 1
在客户端中配置 MCP URL 和 Bearer 令牌：
Authorization: Bearer YOUR_API_KEY（或从连接页面获取的 OAuth 访问令牌）。 - 2
调用 list_templates。若结果为空，请先使用 list_template_block_types 和 create_template。
- 3
用选定的
templateId调用 get_template_schema，了解确切的blockId键和side值。 - 4
调用 create_deck，传入
title、可选的description，并在希望智能体为主题挑选相配图标时传入icon_emoji。 - 5
调用 create_card，传入
deckId，并可选传入templateId、front（主区块）以及用于其他区块（包括背面）的block_text。
技术细节
有关客户端配置（Cursor、VS Code、Claude 等），请参阅 连接 Deckbase MCP • 其他链接请参阅 资源