Quizzard

Quizzard

Quizzard 是一款面向知识问答和测验爱好者的 MCP 服务。本项目的总体目标是尽可能提供多种实用功能，帮助答题者保持最佳状态。项目已集成多种热门测验资源（参见“数据来源和归属”一节）：

• Open Trivia DB
• J! Archive
• 用户上传的 PDF，以及
• 用户输入的 URL（例如 Wikipedia 页面）。

尽管这些资源已涵盖常见知识问答类别的广度和深度，但仍亟需扩展资源列表，加入其他常用来源（Jetpunk、Sporcle 等；这些来源目前受到 Cloudflare 相关限制），并代用户处理他们在这些平台上的活动和统计信息。项目已通过工具实现多种核心功能（完整列表请参见“功能”和“工具”两节）：

• 持续追踪进度
• 检测薄弱领域
• 个性化推荐。

测试时选择的 MCP 客户端是 Windows 上的 Claude Desktop；目前尚未在其他客户端上测试（不过它似乎不太可能与其他客户端不兼容）。欢迎通过 issues 报告 Bug、提交功能请求或分享任何相关想法。

---

功能

• 多个测验来源——OpenTDB（超过 4k 道题）、Jeopardy!（超过 200k 条线索），以及你添加的任何自定义来源
• 自定义来源——导入 PDF、网页，或手动输入问题。例如，你可以用自己的学习资料进行自测
• 混合测验——在一场测验中从多个来源抽取问题
• 进度追踪——每场测验都会保存到本地 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 创建本地数据库。

---

用法

只需自然地与大模型对话（同样，仅在 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! 数据集（约 75MB，一次性操作）
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/ 中创建一个文件，并在 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! 线索 — 由 jwolle1 汇编的数据集，来源为 J! Archive
• Jeopardy! 是 Jeopardy Productions, Inc. 的注册商标。本项目与 Jeopardy Productions, Inc. 无关，也未获得其认可。

本项目仅供个人非商业用途。

---