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 구독자에게 제공됩니다. 전체 레퍼런스는 read_doc을 통해 docs/public/MCP.md에서 확인하세요.

도구

문서

도구	설명	매개변수
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`(이모지 1개; 사용자가 옵트아웃하지 않으면 AI 클라이언트가 제목에 맞는 이모지를 선택해야 해요).
update_deck	제목, 설명, 기본 템플릿 또는 덱 아이콘을 업데이트합니다.	`deckId` (필수); 선택적 title, description, `default_template_id`, `icon_emoji` 또는 `iconEmoji`(빈 문자열이면 아이콘을 삭제합니다).
list_templates	템플릿(`templateId`, 이름, 설명)을 표시합니다.	없음.
get_template_schema	레이아웃의 정확한 JSON: `blockId`, type, `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	카드 1개를 소프트 삭제합니다(휴지통). `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`.

데이터를 읽는 도구는 유효한 OAuth 토큰 또는 API 키가 필요해요. list_template_block_types와 list_block_schemas는 정적 데이터를 반환하며 인증이 필요 없습니다. list_elevenlabs_voices는 Firestore를 읽지 않아요. 인증되지 않은 요청은 401을 반환합니다.

리소스

서버는 docs/public/ 문서에 대한 MCP 리소스를 노출합니다:

resources/list

docs/public/의 .md 파일당 리소스 1개(예: deckbase://docs/public/MCP.md).

resources/read

해당 URI로 문서 콘텐츠를 가져옵니다.

예시: 덱, 템플릿, 카드

1
클라이언트에 MCP URL과 Bearer 토큰을 설정하세요: Authorization: Bearer YOUR_API_KEY(또는 Connect 페이지의 OAuth 액세스 토큰).
2
list_templates를 호출하세요. 비어 있으면 먼저 list_template_block_types와 create_template을 사용하세요.
3
선택한 templateId로 get_template_schema를 호출해 정확한 blockId 키와 side 값을 확인하세요.
4
title, 선택적 description, 그리고 에이전트가 주제에 맞는 아이콘을 선택하도록 할 경우 icon_emoji와 함께 create_deck을 호출하세요.
5
deckId와 선택적 templateId, front(기본 블록), 그리고 뒷면을 포함한 다른 블록용 block_text로 create_card를 호출하세요.

기술 세부 정보

프로토콜MCP 2024-11-05

서버 이름deckbase-mcp

호스팅POST 기반 JSON-RPC 2.0입니다. OAuth 액세스 토큰 또는 대시보드 API 키(Bearer)를 사용하세요. Firebase ID 토큰은 사용하지 마세요.

카드 형태create_card는 템플릿의 블록 레이아웃을 복사해요. 각 블록에는 템플릿의 side가 포함되며, 값은 기본적으로 비어 있습니다. 데이터는 Firestore에 저장되고 대시보드와 모바일 앱에 동기화됩니다.

클라이언트 설정(Cursor, VS Code, Claude 등)은 다음을 참고하세요: Deckbase MCP 연결하기 • 기타 링크는 다음을 참고하세요: 리소스