Máy chủ MCP

Deckbase MCP

Máy chủ Model Context Protocol cho Deckbase. Các công cụ AI (Cursor, Claude Code, VS Code, v.v.) có thể đọc tài liệu và quản lý bộ thẻ và thẻ.

Điểm cuối

Chế độ	Điểm cuối	Xác thực
Lưu trữ (HTTP)	POST /api/mcp	`Authorization: Bearer`: khóa API trên bảng điều khiển hoặc token truy cập OAuth. Cùng đường dẫn trong môi trường production: `/api/mcp`.

OAuth (đăng nhập bằng trình duyệt) là cách kết nối nhanh nhất. Xem Kết nối với Deckbase MCP. Khóa API trên bảng điều khiển cũng có sẵn cho script và CI. MCP khả dụng cho người đăng ký Basic, Pro và VIP. Tài liệu tham khảo đầy đủ trong docs/public/MCP.md qua read_doc.

Công cụ

Tài liệu

Công cụ	Mô tả	Tham số
list_docs	Liệt kê các tệp Markdown trong `docs/public/`.	Không có.
read_doc	Đọc tài liệu theo đường dẫn. Chỉ tài liệu trong `docs/public/` mới được cung cấp.	`path`, ví dụ: `MCP.md` hoặc `deckbase://docs/public/MCP.md`.
list_template_block_types	Khóa loại khối và ID số (text, media, interactive, layout). Dùng trước `create_template`. Dữ liệu tĩnh.	Không có.
list_block_schemas	Cấu trúc JSON theo từng loại khối: `blocksSnapshot`, `values`, `configJson`. Kết hợp với `export_deck` để xem ví dụ thực tế.	Không có.
list_elevenlabs_voices	ID giọng nói ElevenLabs và nhãn cho `voice_id` trên `generate_audio_for_card`. Danh mục được Deckbase tuyển chọn. Không đọc Firestore của người dùng.	Tùy chọn `language`, `gender`, `search`.
list_ai_image_models	ID mô hình tạo ảnh AI được phép cho `generate_image_for_card`, kèm nhãn và chi phí tín dụng.	Không có.

Bộ thẻ và Thẻ: yêu cầu xác thực

Công cụ	Mô tả	Tham số
list_decks	Các bộ thẻ của người dùng (`deckId`, tiêu đề, mô tả, `defaultTemplateId` tùy chọn, `iconEmoji` tùy chọn).	Không có.
create_deck	Tạo một bộ thẻ. Trả về `deckId`, `icon_emoji` / `iconEmoji` nếu được đặt.	`title` (bắt buộc), `description` (tùy chọn), `icon_emoji` hoặc `iconEmoji` tùy chọn (một emoji duy nhất; ứng dụng AI nên chọn emoji phù hợp với tiêu đề trừ khi người dùng không muốn).
update_deck	Cập nhật tiêu đề, mô tả, mẫu mặc định hoặc biểu tượng bộ thẻ.	`deckId` (bắt buộc); tiêu đề, mô tả, `default_template_id`, `icon_emoji` hoặc `iconEmoji` tùy chọn (chuỗi rỗng sẽ xóa biểu tượng).
list_templates	Mẫu (`templateId`, tên, mô tả).	Không có.
get_template_schema	JSON chính xác cho bố cục: `blockId`, loại, `side` (`"front"` \| `"back"`), `configJson`, `valuesExample`, gợi ý `create_card`.	`templateId` hoặc `deckId` cho mẫu mặc định của bộ thẻ.
create_card	Tạo thẻ mới từ một mẫu. Trả về `cardId`, `templateId`, `usedDeckDefault`. `front` điền vào khối chính; khóa `block_text` bao gồm các khối mặt sau (`side` từ `get_template_schema`).	`deckId` bắt buộc. Tùy chọn `templateId`, `front`, `block_text`, `generate_audio`, `voice_id`, `audio_language`, `audio_gender`.
create_cards	Tạo hàng loạt. Tối đa 50 mỗi yêu cầu. Khi lỗi: `created` + `failedAt`.	`deckId`, mảng `cards` (bắt buộc). Tùy chọn cấp cao nhất `templateId`, `voice_id`, `generate_audio`.
update_card	Chỉnh sửa nội dung của thẻ.	`deckId`, `cardId`; tùy chọn `values` / `blocks_snapshot`, hoặc gộp `front` / `block_text`.
delete_card	Xóa mềm một thẻ (vào thùng rác). Máy chủ sẽ từ chối trừ khi `user_confirmed` là true. Chỉ dùng sau khi có sự đồng ý rõ ràng của con người.	`deckId`, `cardId`, `user_confirmed` (boolean bắt buộc).
delete_cards	Xóa mềm hàng loạt trong một bộ thẻ. Cùng quy tắc đồng ý như `delete_card`. Tối đa 50 mỗi yêu cầu.	`deckId`, `card_ids` (mảng không rỗng), `user_confirmed`.
generate_audio_for_card	TTS ElevenLabs cho một thẻ hiện có.	`deckId`, `cardId`. Truyền `voice_id` hoặc `audio_language` + `audio_gender`. Tùy chọn `text`, `block_id`, `replace_existing`.
export_deck	JSON của bộ thẻ + thẻ. Bao gồm `truncated`, `exportType`. Bản xuất đầy đủ bao gồm `blocksSnapshot` cho từng thẻ với `side` + `values`.	`deckId` (bắt buộc); tùy chọn `max_cards` (mặc định 2000, tối đa 5000), `export_type`: `full` hoặc `values_only`.
create_template	Tạo mẫu mới (bố cục khối). Trả về `templateId` và ID khối. Mặc định Hỏi+Đáp nếu bỏ qua `block_types`.	`name` (bắt buộc); tùy chọn: mô tả, `block_types` / `blocks` (với `side` cho từng khối), `voice_id`, `audio_language`, `audio_gender`, `mainBlockId` / `subBlockId`.
update_template	Cập nhật siêu dữ liệu và/hoặc bố cục. Tăng `version`.	`templateId` (bắt buộc); tùy chọn: tên, mô tả, `block_types` / `blocks`, `voice_id`, `audio_language` + `audio_gender`, `mainBlockId` / `subBlockId`.

Các công cụ đọc dữ liệu của bạn yêu cầu token OAuth hoặc khóa API hợp lệ. list_template_block_types và list_block_schemas trả về dữ liệu tĩnh (không cần xác thực). list_elevenlabs_voices không đọc Firestore. Các yêu cầu chưa xác thực trả về 401.

Tài nguyên

Máy chủ cung cấp tài nguyên MCP cho các tài liệu trong docs/public/:

resources/list

Một tài nguyên cho mỗi tệp .md trong docs/public/ (ví dụ: deckbase://docs/public/MCP.md).

resources/read

Tải nội dung tài liệu theo URI đó.

Ví dụ: bộ thẻ, mẫu và thẻ

1
Cấu hình ứng dụng khách của bạn với URL MCP và token bearer: Authorization: Bearer YOUR_API_KEY (hoặc token truy cập OAuth từ trang Kết nối).
2
Gọi list_templates. Nếu trống, hãy dùng list_template_block_types và create_template trước.
3
Gọi get_template_schema với templateId đã chọn để biết chính xác các khóa blockId và giá trị side.
4
Gọi create_deck với title, description tùy chọn và icon_emoji khi tác nhân nên chọn biểu tượng phù hợp với chủ đề.
5
Gọi create_card với deckId và tùy chọn templateId, front (khối chính), cùng block_text cho các khối khác, bao gồm mặt sau.

Chi tiết kỹ thuật

Giao thứcMCP 2024-11-05

Tên máy chủdeckbase-mcp

Lưu trữJSON-RPC 2.0 qua POST. Dùng token truy cập OAuth hoặc khóa API trên bảng điều khiển (Bearer), không phải token ID Firebase.

Cấu trúc thẻcreate_card sao chép bố cục khối của mẫu. Mỗi khối bao gồm side từ mẫu; giá trị rỗng theo mặc định. Dữ liệu được lưu trong Firestore và đồng bộ với bảng điều khiển và ứng dụng di động.

Để thiết lập ứng dụng khách (Cursor, VS Code, Claude, v.v.), xem Kết nối với Deckbase MCP • Để xem các liên kết khác, xem Tài nguyên