内容
# quiz-mcp
让 AI 模型将交互式测验移交给人类，通过真正的浏览器 UI。
与生成 HTML 表单作为制品或在聊天中逐一提问不同，模型将测验描述为 JSON，用户在 `http://localhost:<port>` 填写，答案作为结构化数据流回模型。
适用于教师使用 AI 构建测验，研究人员进行结构化访谈，或任何需要人类真实输入的代理。
## 快速开始
### 尝试演示测验（无需安装，无需克隆）
直接从 GitHub 运行捆绑的 7 题 JavaScript 基础测验：
```bash
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`。
<video width="320" height="240" controls>
<source src="docs/demo_local.mp4" type="video/mp4">
</video>
#### Claude 代码
添加到项目根目录的 `.mcp.json`（或用户全局的 `~/.claude.json`）：
```json
{
"mcpServers": {
"quiz-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@quiz-mcp/cli", "mcp"]
}
}
}
```
#### OpenCode
添加到 `opencode.json`（项目）或 `~/.config/opencode/opencode.json`（全局）：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"quiz-mcp": {
"type": "local",
"command": ["npx", "-y", "@quiz-mcp/cli", "mcp"],
"enabled": true
}
}
}
```
#### Kilo 代码
在 Kilo 代码中打开 MCP 设置面板（MCP 服务器 → 编辑全局 MCP），并添加：
```json
{
"mcpServers": {
"quiz-mcp": {
"command": "npx",
"args": ["-y", "@quiz-mcp/cli", "mcp"]
}
}
}
```
相同的 `command`/`args` 对适用于任何遵循标准 `mcpServers` 形状的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）。
### 使用托管的远程 MCP 服务器
如果您不想在本地安装任何内容，quiz-mcp 有一个托管的、受 OAuth 保护的版本在 Cloudflare Workers 上运行：
```
https://quiz-mcp-oauth.karerckor.workers.dev/mcp
```
它公开了与本地服务器相同的工具，以及用于管理每个用户状态的 `get_quizzes` 和 `cleanup_quiz`。每个用户都有一个隔离的测验工作区；登录通过 WorkOS AuthKit 在第一个工具调用上处理。
> **注意：** 答案存储在 Cloudflare KV 中，这是一致的。用户提交测验后，`get_answers` 可能会短暂返回空或过时的数据 — 请等待几秒钟，然后重试，如果模型报告缺少答案。
<video width="320" height="240" controls>
<source src="docs/demo_remote.mp4" type="video/mp4">
</video>
#### Claude 代码
使用 `claude` CLI 将远程服务器注册到 `~/.claude.json`：
```bash
claude mcp add --transport http quiz-mcp-remote https://quiz-mcp-oauth.karerckor.workers.dev/mcp
```
或手动将其添加到 `.mcp.json`（项目）/ `~/.claude.json`（用户全局）：
```json
{
"mcpServers": {
"quiz-mcp-remote": {
"type": "http",
"url": "https://quiz-mcp-oauth.karerckor.workers.dev/mcp"
}
}
}
```
在第一次调用（例如 `start_quiz`）时，Claude 代码将为您打开浏览器进行 OAuth 流；之后，访问令牌将被缓存。运行 `/mcp` 进入 Claude 代码以检查连接状态或重新身份验证。
想要托管您自己的实例？请参阅 [`apps/remote-mcp-oauth/README.md`](apps/remote-mcp-oauth/README.md) 以获取完整设置（Cloudflare KV 命名空间、WorkOS 机密、 `wrangler deploy`）。
### 搭建和运行您自己的测验
```bash
# 搭建一个新的测验骨架 → ./javascript-basics.quiz.json
npx @quiz-mcp/cli create "JavaScript 基础"
# 在浏览器中提供服务并将答案写入文件
npx @quiz-mcp/runner --file ./javascript-basics.quiz.json --output ./answers.json --open
```
搭建的文件包含一个 `$schema` 指针，以便编辑器可以验证并在您填写测验结构时自动完成。
### 使用 webhook 接收器提供远程测验
```bash
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` | Cloudflare Worker，托管受 OAuth 保护的远程 MCP 服务器（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 shell，用于测验运行时。REST 端点，主题，国际化。未单独发布。 |
| `packages/runner-ui` | `@quiz-mcp/runner-ui` | Vite/Hono-JSX 客户端捆绑包。为 SSR shell 提供支持，并将 `<quiz-player>` 事件连接到 REST API。仅限资产，不导入运行时。 |
| `packages/web-components` | `@quiz-mcp/web-components` | 框架无关的 `<quiz-player>` 自定义元素（Svelte 5 + Shadow DOM + DaisyUI 5）。 |
| `demo/` | — | 示例测验 JSON 文件。 |
| `schema/` | — | 生成的 JSON 模式，用于 `Quiz` 类型（`schema/quiz.schema.json`）。 |
| `scripts/` | — | 构建时实用程序：JSON 模式生成和验证对抗 AJV。 |
## 要求
| 工具 | 版本 |
|---|---|
| Node.js | ≥ 20 |
| pnpm | 10.8.1（通过 `packageManager` 固定） |
## 开发
```bash
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/quiz.schema.json`。
顶级形状：
```json
{
"id": "my-quiz-1",
"title": "测验标题",
"description": "可选描述",
"questions": [ /* 问题[] */ ]
}
```
支持的问题类型（ `_kind` ）：
`single_choice`、`multiple_choice`、`short_text`、`long_text`、`dropdown`、`fill_gaps`、`match`、`scale`、`sorting`、`upload`
重新生成或验证模式：
```bash
pnpm schema:gen # 写入 schema/quiz.schema.json
pnpm schema:check # 使用 AJV 验证生成的模式
```
模式也可在嵌入文件的规范 URL 上获取：
`https://raw.githubusercontent.com/karerckor/quiz-mcp/main/schema/quiz.schema.json`
## 包 README
- [`apps/cli/README.md`](apps/cli/README.md) — MCP 工具，生命周期行为，CLI 命令
- [`apps/runner/README.md`](apps/runner/README.md) — 独立运行 CLI 标志，退出代码，架构
- [`apps/remote-mcp-oauth/README.md`](apps/remote-mcp-oauth/README.md) — 托管远程 MCP 服务器，OAuth 设置，Cloudflare 部署
- [`packages/core/README.md`](packages/core/README.md) — 领域模式，评分 API，验证，添加问题类型
- [`packages/runner-api/README.md`](packages/runner-api/README.md) — REST 端点，SSR 服务器选项，`QuizService` 接口，主题
- [`packages/runner-ui/README.md`](packages/runner-ui/README.md) — 客户端捆绑包内部，Vite 清单，自定义部署
- [`packages/web-components/README.md`](packages/web-components/README.md) — `<quiz-player>` 元素 API，事件，主题，框架集成
