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

デモモードでは、シード済みセットを2つ持つインメモリの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ブロックを削除してください。

ツール

また、vocabit://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もキーも設定しなければ、サーバーはデモモードで起動します。どちらか一方だけ設定すると、起動を拒否します。中途半端な設定はヒントではなく、誤りです。

設計ノート

デモモードはスタブのおとしではなく、一級のクライアントです。 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 Registry へ公開する

ライセンス

MIT © Ivan Bilousov