Quiz Mcp

quiz-mcp

AI モデルが、実際のブラウザー UI を通じてインタラクティブなクイズを人間に引き継げるようにします。

成果物として HTML フォームを生成したり、チャットで質問を 1 つずつ尋ねたりする代わりに、モデルはクイズを JSON で記述します。ユーザーは http://localhost:<port> で回答を入力し、その回答は構造化データとしてモデルに返されます。

AI を使ってクイズを作成する教師、構造化インタビューを実施する研究者、人間からの実際の入力が必要なエージェントに役立ちます。

クイックスタート

デモクイズを試す（インストール不要、クローン不要）

GitHub から同梱の JavaScript 基礎クイズ（7 問）を直接実行します。

npx @quiz-mcp/runner \
  --url https://raw.githubusercontent.com/karerckor/quiz-mcp/main/demo/js-quiz.json \
  --output ./answers.json \
  --open

--open を指定すると、URL がシステムブラウザーで開きます。送信すると、回答は ./answers.json に書き込まれます。

MCP サーバーとして登録する

接続すると、モデルは 4 つのツール start_quiz、get_answers、get_quiz_format、stop_runner を利用できるようになります。

Claude Code

プロジェクトルートの .mcp.json（またはユーザー全体に適用する場合は ~/.claude.json）に追加します。

{
  "mcpServers": {
    "quiz-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@quiz-mcp/cli", "mcp"]
    }
  }
}

OpenCode

opencode.json（プロジェクト用）または ~/.config/opencode/opencode.json（グローバル用）に追加します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "quiz-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@quiz-mcp/cli", "mcp"],
      "enabled": true
    }
  }
}

Kilo Code

Kilo Code の MCP 設定パネル（MCP Servers → Edit Global MCP）を開き、次を追加します。

{
  "mcpServers": {
    "quiz-mcp": {
      "command": "npx",
      "args": ["-y", "@quiz-mcp/cli", "mcp"]
    }
  }
}

同じ command/args の組み合わせは、標準の mcpServers 形式に従うすべての MCP クライアント（Claude Desktop、Cursor、Windsurf など）で使用できます。

ホスト型リモート MCP サーバーを使用する

ローカルに何もインストールしたくない場合は、Cloudflare Workers 上で稼働する、OAuth で保護されたホスト型の quiz-mcp があります。

https://quiz-mcp-oauth.karerckor.workers.dev/mcp

ローカルサーバーと同じツールに加えて、ユーザーごとの状態を管理する get_quizzes と cleanup_quiz を公開しています。ユーザーごとに独立したクイズ用ワークスペースが割り当てられます。初回のツール呼び出し時に WorkOS AuthKit を通じてログインします。

Note: 回答は Cloudflare KV に保存されますが、結果整合性が適用されます。ユーザーがクイズを送信した直後は、get_answers が一時的に空または古いデータを返すことがあります。モデルから回答が見つからないと報告された場合は、数秒待ってから再試行してください。

Claude Code

claude CLI でリモートサーバーを登録します（登録情報は ~/.claude.json に保存されます）。

claude mcp add --transport http quiz-mcp-remote https://quiz-mcp-oauth.karerckor.workers.dev/mcp

または .mcp.json（プロジェクト用）／~/.claude.json（ユーザー全体に適用）に手動で追加します。

{
  "mcpServers": {
    "quiz-mcp-remote": {
      "type": "http",
      "url": "https://quiz-mcp-oauth.karerckor.workers.dev/mcp"
    }
  }
}

初回の呼び出し時（例：start_quiz）、Claude Code は OAuth フローのためにブラウザーを開きます。以降、アクセストークンはキャッシュされます。Claude Code 内で /mcp を実行すると、接続状態の確認や再認証ができます。

独自のインスタンスをホストしたい場合は、apps/remote-mcp-oauth/README.md にある完全なセットアップ手順（Cloudflare KV の名前空間、WorkOS のシークレット、wrangler deploy）を参照してください。

独自のクイズをひな形から作成して実行する

# scaffold a new quiz skeleton → ./javascript-basics.quiz.json
npx @quiz-mcp/cli create "JavaScript basics"

# serve it in a browser and write answers to a file
npx @quiz-mcp/runner --file ./javascript-basics.quiz.json --output ./answers.json --open

生成されるファイルには $schema の参照先が含まれています。これにより、クイズの構造を入力しながら、エディターで検証やオートコンプリートを利用できます。

Webhook の送信先を使ってリモートクイズを配信する

npx @quiz-mcp/runner \
  --url https://example.com/quiz.json \
  --on-complete https://example.com/hooks/quiz \
  --output ./answers.json

クイズが正常に完了するとランナーは終了コード 0 で終了します。読み込みまたは検証に失敗した場合は 1、クイズの完了後に送信先が失敗した場合は 2 で終了します。

---

リポジトリ構成

パス	パッケージ／アプリ	説明
apps/cli	@quiz-mcp/cli	公開されているバイナリ（quiz-mcp）です。MCP stdio サーバー、遅延実行のランナーライフサイクル、create スキャフォールディングコマンドを提供します。
apps/runner	@quiz-mcp/runner	ファイル／URL／標準入力からクイズを読み込み、ブラウザーで配信し、回答をファイルまたは Webhook に書き込むスタンドアロン CLI です。
apps/remote-mcp-oauth	@quiz-mcp/remote-mcp-oauth	OAuth で保護されたリモート MCP サーバーをホストする Cloudflare Worker（WorkOS AuthKit + Durable Objects）です。https://quiz-mcp-oauth.karerckor.workers.dev を提供します。
packages/core	@quiz-mcp/core	ドメインの基盤です。Zod スキーマ、型、採点エンジン、回答の検証を提供します。クイズ形式の唯一の信頼できる情報源です。
packages/runner-api	@quiz-mcp/runner-api	クイズランタイム用の Hono HTTP サーバーおよび SSR シェルです。REST エンドポイント、テーマ設定、i18n を提供します。単体では公開されていません。
packages/runner-ui	@quiz-mcp/runner-ui	Vite/Hono-JSX クライアントバンドルです。SSR シェルをハイドレートし、<quiz-player> のイベントを REST API に接続します。アセットのみで、ランタイムのインポート対象ではありません。
packages/web-components	@quiz-mcp/web-components	フレームワークに依存しない <quiz-player> カスタム要素（Svelte 5 + Shadow DOM + DaisyUI 5）です。
demo/	—	クイズの JSON サンプルファイルです。
schema/	—	Quiz 型用の生成済み JSON Schema（schema/quiz.schema.json）です。
scripts/	—	JSON Schema の生成と AJV による検証を行うビルド時ユーティリティです。

要件

ツール	バージョン
Node.js	≥ 20
pnpm	10.8.1（packageManager で固定）

開発

git clone https://github.com/karerckor/quiz-mcp.git
cd quiz-mcp
pnpm install

コマンド	用途
pnpm build	すべてのパッケージをビルドします（Turborepo が ^build グラフに従います）。
pnpm test	テストスイート全体を実行します。
pnpm typecheck	すべてのパッケージの型をチェックします。
pnpm dev	パッケージ間で並列に実行するウォッチモードです。

クイズスキーマ

Quiz 形式は packages/core で Zod スキーマとして定義され、JSON Schema として schema/quiz.schema.json にエクスポートされます。

トップレベルの構造：

{
  "id": "my-quiz-1",
  "title": "Quiz title",
  "description": "Optional description",
  "questions": [ /* Question[] */ ]
}

サポートされる問題形式（_kind）：

single_choice、multiple_choice、short_text、long_text、dropdown、fill_gaps、match、scale、sorting、upload

スキーマの再生成または検証：

pnpm schema:gen    # writes schema/quiz.schema.json
pnpm schema:check  # validates the generated schema with AJV

スキーマは、ファイルに埋め込まれている正規 URL からも利用できます。 https://raw.githubusercontent.com/karerckor/quiz-mcp/main/schema/quiz.schema.json

パッケージの README

• apps/cli/README.md — MCP ツール、ライフサイクルの動作、CLI コマンド
• apps/runner/README.md — スタンドアロンランナー CLI のフラグ、終了コード、アーキテクチャ
• apps/remote-mcp-oauth/README.md — ホスト型リモート MCP サーバー、OAuth の設定、Cloudflare へのデプロイ
• packages/core/README.md — ドメインスキーマ、採点 API、検証、問題形式の追加
• packages/runner-api/README.md — REST エンドポイント、SSR サーバーのオプション、QuizService インターフェース、テーマ設定
• packages/runner-ui/README.md — クライアントバンドルの内部構造、Vite マニフェスト、カスタムデプロイ
• packages/web-components/README.md — <quiz-player> 要素の API、イベント、テーマ設定、フレームワークとの連携