Vocabit

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 です。学習者がどのカードを難しいとマークしたか、どのカードにまだ取り組んでいないか、それぞれのカードに何回の復習が必要だったかを確認できます。次のセットは推測ではなく、その結果をもとに作成されます。

30 秒で試す

バックエンドもアカウントも API キーも不要です。

npx -y vocabit-mcp --demo

デモモードでは、2 つのセットがあらかじめ登録されたメモリ内の Vocabit に対して、同じサーバーが動作します。セットを作成して結果を尋ねると、決定論的な代役の学習者がそのセットに取り組んだ結果が返されます。レスポンスではシミュレーションであることが明示されるため、実際のデータと間違えることはありません。

UI で試すには、次のようにします。

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

インストール

io.github.JohnBilousov/vocabit-mcpとしてMCP Registryに登録されているため、レジストリを参照するクライアントが自動的に見つけられます。

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"
      }
    }
  }
}

ツール

また、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, plus the HTTP client against a mocked fetch
npm run lint      # eslint
npm run format    # prettier --write
npm run inspect   # demo mode in the MCP Inspector

CI では、プッシュとプルリクエストのたびに typecheck、lint、format:check、test、build を実行します。

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
test/
  server.test.ts       tool surface + full loop — over an in-memory MCP transport
  client/
    http.test.ts       query encoding, error-body parsing, timeouts — against a mocked fetch

リリース

公開には npm の信頼された公開（OIDC）を使用します。 NPM_TOKEN シークレットは不要で、漏えいや期限切れの心配もありません。npmjs.com で一度だけ設定します。パッケージの Settings → Trusted publishing → GitHub Actions から、組織に JohnBilousov、この リポジトリ、ワークフローファイル名に publish.yml を指定します。

リリースするには、package.json、server.json、src/server.ts の VERSION のバージョンを 一緒に更新します（ずれがないことをテストで検証します）。変更をコミットしてプッシュした後、 対応する vX.Y.Z タグを付けた GitHub Release を公開します。これにより .github/workflows/publish.yml が実行され、テストスイートを実行してから、 来歴情報付きで npm に公開します。パッケージページには、レジストリ上の名前だけでなく、 このコミットとワークフローの実行に戻る検証済みリンクが表示されます。

ロードマップ

• stdio と併用できる Streamable HTTP トランスポート
• バックエンドのデフォルト UID に依存しない複数学習者への対応
• 音声付き発音カード

ライセンス

MIT © Ivan Bilousov