Quiz Mcp

quiz-mcp

让 AI 模型通过真实的浏览器界面，将互动测验交给人类完成。

模型无需生成 HTML 表单作为产物，也无需在聊天中逐个提问；它只需用 JSON 描述测验，用户在 http://localhost:<port> 填写答案，答案便会以结构化数据的形式返回给模型。

适用于使用 AI 创建测验的教师、进行结构化访谈的研究人员，或任何需要人类提供真实输入的 Agent。

快速开始

试用演示测验（无需安装或克隆）

直接从 GitHub 运行捆绑的 7 题 JavaScript 基础知识测验：

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 服务

连接后，模型会获得四个工具：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"]
    }
  }
}

对于任何遵循标准 mcpServers 结构的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等），都可以使用相同的 command/args 配对。

使用托管的远程 MCP 服务

如果你不想在本地安装任何内容，可以使用运行在 Cloudflare Workers 上、受 OAuth 保护的托管版 quiz-mcp：

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

它提供与本地服务相同的工具，另外还有用于管理每位用户状态的 get_quizzes 和 cleanup_quiz。每位用户都会获得独立的测验工作区；首次调用工具时，通过 WorkOS AuthKit 完成登录。

**注意：**答案会持久化到 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	独立 CLI，可从文件 / URL / stdin 加载测验，在浏览器中提供测验，并将答案写入文件或 webhook。
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 模式，并导出为 schema/quiz.schema.json 中的 JSON Schema。

顶层结构：

{
  "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、事件、主题设置、框架集成