vocabit-mcp

플래시카드 앱인 Vocabit용 MCP 서버입니다. AI 어시스턴트가 실제 휴대폰의 실제 앱에 학습 세트를 작성하고, 학습자가 실제로 그 세트를 어떻게 소화했는지 다시 읽어올 수 있게 해줍니다.

대부분의 MCP 서버는 API에서 읽어옵니다. 하지만 이 서버는 루프를 닫습니다:

flowchart LR
    A["Assistant<br/>teaches a topic"] --> B["create_study_set"]
    B --> C["Set appears in the<br/>Vocabit app"]
    C --> D["Learner works<br/>through it"]
    D --> E["get_set_results"]
    E -->|weak cards| A

흥미로운 도구는 create_study_set이 아닙니다. 무엇이든 플래시카드를 생성할 수 있으니까요. 중요한 것은 get_set_results입니다. 학습자가 hard로 표시한 카드, 전혀 도달하지 못한 카드, 각 카드에 몇 번의 복습이 필요했는지가 담겨 있습니다. 다음 세트는 추측이 아니라 그 결과를 바탕으로 만들어집니다.

30초 안에 사용해 보기

백엔드도, 계정도, API 키도 필요 없습니다:

npx -y vocabit-mcp --demo

데모 모드는 시드된 세트 두 개가 들어 있는 인메모리 Vocabit을 대상으로 동일한 서버를 실행합니다. 세트를 만들고 결과를 요청하면, 결정적인(항상 동일한 결과를 내는) 가상 학습자가 그 세트를 모두 학습한 상태로 나옵니다. 응답에는 시뮬레이션 결과임이 표시되므로 실제 데이터로 오인될 일이 없습니다.

UI로 살펴보려면:

npx @modelcontextprotocol/inspector npx -y vocabit-mcp --demo

설치

MCP Registry에 io.github.JohnBilousov/vocabit-mcp로 등재되어 있어, 레지스트리를 읽는 클라이언트는 서버를 직접 찾을 수 있습니다.

claude mcp add vocabit -- npx -y vocabit-mcp

{
  "mcpServers": {
    "vocabit": {
      "command": "npx",
      "args": ["-y", "vocabit-mcp"],
      "env": {
        "VOCABIT_BASE_URL": "https://your-vocabit-backend.example.com",
        "VOCABIT_AGENT_KEY": "your-agent-key"
      }
    }
  }
}

데모 모드로 실행하려면 env 블록을 제거하세요.

도구

또한 vocab://set/{setId} 리소스(JSON 형태의 세트, 목록 조회 가능)와 study-session 프롬프트도 노출되며, 후자는 전체 루프를 따라가도록 안내합니다.

카드 상태

진도는 어시스턴트가 아니라 앱의 간격 복습 엔진에서 나옵니다.

세트에서 new 상태인 카드가 하나도 남지 않으면 completed: true가 보고됩니다.

라이브 모드

서버가 에이전트 API가 활성화된 Vocabit 백엔드를 가리키게 설정하세요:

export VOCABIT_BASE_URL=https://your-vocabit-backend.example.com
export VOCABIT_AGENT_KEY=...   # must match one of AGENT_API_KEYS on the backend
npx -y vocabit-mcp

URL과 키를 모두 설정하지 않으면 서버는 데모 모드로 시작합니다. 둘 중 하나만 설정하면 시작을 거부합니다. 절반만 설정하는 것은 힌트가 아니라 실수이기 때문입니다.

디자인 노트

데모 모드는 스텁이 아니라 first-class 클라이언트입니다. HttpVocabitClient와 DemoVocabitClient는 동일한 VocabitClient 인터페이스를 구현하므로, 어떤 도구에도 "지금 실제로 실행하는지 여부"를 분기로 처리하는 코드가 없습니다. 검토자는 자격 증명이 없이도 서버를 실행할 수 있고, 테스트 스위트는 SDK를 흉내내는 대신 실제 MCP 전송을 통해 실제 도구 표면을 검증합니다.

오류는 치명적이 아니라 복구 가능합니다. 실패한 호출은 isError로 반환되며, 백엔드 자체 메시지와 함께 모델을 위한 힌트가 붙습니다. 404는 "어떤 세트가 있는지 보려면 list_study_sets를 호출하세요"라고 알려 주고, 401은 "VOCABIT_DEMO=1로 실행해 보세요"라고 안내합니다. 서로 배타적인 인자는 추측 대신 설명과 함께 거부됩니다.

출력 스키마는 가장자리에서 느슨하게 유지됩니다. 식별에 필요한 필드는 필수로 하고 나머지는 모두 선택 사항으로 둡니다. 그래서 백엔드에 새 필드가 추가되어도 동작 중인 도구가 검증 오류로 변하지를 않습니다.

어노테이션은 정직합니다. delete_study_set에는 destructiveHint가 표시되고, 읽기 도구에는 readOnlyHint가 표시됩니다. notify_learner는 실제 사람에게 메시지를 보내며, 설명에도 아껴서 사용하라고 되어 있습니다.

개발

git clone https://github.com/JohnBilousov/vocabit-mcp && cd vocabit-mcp
npm install
npm run build
npm test          # tool surface + full loop over an in-memory MCP transport
npm run inspect   # demo mode in the MCP Inspector

src/
  index.ts        CLI entry, stdio transport
  config.ts       env → Config, demo-mode resolution
  server.ts       tool / resource / prompt registration
  schemas.ts      zod input and output shapes
  format.ts       human-readable summaries next to structuredContent
  client/
    types.ts      wire types + VocabitClient contract
    http.ts       live backend
    mock.ts       in-memory backend for demo mode

로드맵

• stdio와 함께 스트림 가능한 HTTP 전송

• 백엔드 기본 UID 없이 여러 학습자 지원

• 오디오 발음 카드

• MCP 레지스트리에 등록

라이선스

MIT © Ivan Bilousov