Quizzard

Quizzard

Quizzard は、トリビアやクイズを楽しむ人向けの MCP サーバーです。このプロジェクトの大きな目標は、クイズを楽しむ人が腕を磨き続けるのに役立つ機能をできるだけ多く提供することです。人気のクイズリソースをいくつか統合しています（「データソースとクレジット」セクションを参照してください）。

• Open Trivia DB
• J! Archive
• ユーザーがアップロードした PDF、および
• ユーザーが入力した URL（Wikipedia ページなど）

これらのリソースで一般的なトリビアのカテゴリを十分に幅広く、深くカバーできますが、よく使われるリソース（Jetpunk、Sporcle など。現時点では Cloudflare 関連の制限があります）もいくつか追加することが重要です。また、これらのプラットフォームにおけるユーザーの利用状況や統計情報を、ユーザーに代わって管理する機能も必要です。中核となる機能のいくつかはツールとして実装されています（一覧については「機能」と「実装済みツール」のセクションを参照してください）。

• 進捗の永続的な追跡
• 苦手分野の検出
• パーソナライズされたおすすめ

テストに使用した MCP クライアントは Windows 上の Claude Desktop です。他のクライアントではまだテストしていません（ただし、互換性の問題がある可能性は低いと考えています）。バグ、機能のリクエスト、その他関連するご意見は、issue からお知らせください。

---

機能

• 複数のクイズソース - OpenTDB（4,000 問以上）、Jeopardy!（20 万問以上の手がかり）、および追加したカスタムソース
• カスタムソース - PDF やウェブページを取り込むか、質問を手動で入力できます。たとえば、自分の学習教材でクイズに挑戦できます
• ミックスクイズ - 1 回のセッションで複数のソースから質問を出題します
• 進捗の追跡 - 各セッションをローカルの SQLite データベースに保存します
• 苦手分野の検出 - 正答率が最も低いカテゴリを特定します
• 自己ベスト - カテゴリと難易度ごとに最高スコアを記録します
• スマートなおすすめ - 履歴に基づいて、次にプレイするクイズを提案します

---

インストール

1. リポジトリをクローンする

git clone https://github.com/hrmtsh2/quizzard.git
cd quizzard

2. 仮想環境を作成して有効化する

python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux [NOT TESTED YET]
source venv/bin/activate

3. 依存関係をインストールする

pip freeze で生成された requirements.txt を使ってインストールします。

pip install -r requirements.txt

または、特に重要なものだけをインストールします。

pip install fastmcp httpx beautifulsoup4 pdfplumber

4. MCP クライアントを設定する

たとえば Claude Desktop の場合、次の設定を claude_desktop_config.json に追加します。

• Windows： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json［未テスト］

{
  "mcpServers": {
    "quizzard": {
      "command": "C:/path/to/quizzard/venv/Scripts/python.exe",
      "args": ["C:/path/to/quizzard/server.py"]
    }
  }
}

パスを実際のプロジェクトパスに置き換えてください。Windows でもスラッシュ（/）を使用してください。

5. Claude Desktop の場合 - Claude Desktop を再起動する

初回起動時に Quizzard が自動的に初期化され、~/.quizzard/quizzard.db にローカルデータベースが作成されます。

---

使用方法

LLM に自然な言葉で話しかけてください（こちらも Claude Sonnet 4.6 でテストしています）。まずは、次のプロンプトをお試しください。

"Quiz me on geography, medium difficulty, 10 questions"
"Quiz me on Jeopardy! science clues"
"Enable Jeopardy as a source"
"What are my weak areas?"
"What should I play next?"
"Ingest this PDF and quiz me on it"
"Quiz me on a mix of OpenTDB and Jeopardy"
"Show my recent sessions"
"What sources do I have?"

---

実装済みツール

ツール	説明
quiz_me	追跡対象のクイズセッションを開始する
submit_quiz_results	クイズ後に結果を保存する（自動的に呼び出されます）
get_questions	セッションを開始せずに質問を閲覧・プレビューする
start_session	重複排除を有効にし、同じ質問が繰り返し出ないようにする
list_categories	ソースで利用可能なカテゴリを一覧表示する
search_categories	キーワードでカテゴリを検索する
enable_jeopardy	Jeopardy! のデータセットをダウンロードしてインポートする（約 75 MB、初回のみ）
ingest_pdf	PDF から質問を抽出し、カスタムソースとして保存する
ingest_url	ウェブページから質問を抽出し、カスタムソースとして保存する
save_custom_questions	質問セットを手動でカスタムソースとして保存する
list_sources	利用可能なクイズソースをすべて一覧表示する
recommend_quiz	履歴に基づいて、パーソナライズされたクイズをおすすめする
my_weak_areas	最も苦手なカテゴリを表示する（最低 5 回の挑戦が必要）
my_personal_bests	カテゴリと難易度ごとの最高スコアを表示する
my_recent_sessions	最近のクイズセッションを表示する
my_stats	すべてのカテゴリの正答率統計を表示する

---

アーキテクチャ

Quizzard は、これまでに含まれている数少ないソースも含め、ソースに依存しない設計になっています。各クイズソースは共通のインターフェースを実装するため、server.py が接続先のソースを把握する必要はありません。

quizzard/
├── server.py          # core FastMCP server with all the tools
├── client.py          # httpx wrapper for external APIs
├── db.py              # SQLite database for storing sessions, attempts, stats
└── sources/
    ├── base.py        # QuizSource class (the common interface)
    ├── opentdb.py     # Open Trivia Database
    ├── jeopardy.py    # Jeopardy! dataset (local SQLite)
    └── user.py        # User-defined sources

新しいソースを追加する場合、理想的には sources/ にファイルを1つ作成し、server.py の question_sources に登録するだけで済み、それ以外の変更は必要ありません。

ユーザーデータは次の場所にローカル保存されます。

~/.quizzard/
├── quizzard.db          # all sessions, attempts, stats, custom questions
└── data/
    └── combined_season1-41.tsv   # Jeopardy dataset (downloaded on first enable)

---

データソースとクレジット

• 一般知識クイズ — Open Trivia Database。ライセンスは CC BY-SA 4.0 です。
• Jeopardy! の問題 — J! Archive を出典とする、jwolle1 がまとめたデータセット
• Jeopardy! は Jeopardy Productions, Inc. の登録商標です。このプロジェクトは Jeopardy Productions, Inc. と提携しておらず、同社の承認も受けていません。

このプロジェクトは、個人的かつ非営利目的での利用に限られます。

---