quiz MCP

mcp测验

让AI模型通过真正的浏览器UI将交互式测验传递给人类。

该模型将测验描述为JSON，用户在 http://localhost: ，答案作为结构化数据流回模型。

对于使用人工智能构建测验的教师、进行结构化访谈的研究人员或需要人类真实输入的任何代理都很有用。

Quiz runner showing the bundled JavaScript basics demo

快速启动

尝试演示测试（不安装，不克隆）

直接从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.

克劳德代码

添加 .mcp.json 在项目根目录中（或 ~/.claude.json 适用于整个用户）：

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

开源代码

添加 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（MCP服务器）中打开MCP设置面板→ 编辑全局MCP）并添加：

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

相同 command/args pair适用于任何遵循标准的MCP客户端 mcpServers 形状（克劳德桌面、光标、风帆等）。

使用托管的远程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 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流；访问令牌随后被缓存。跑 /mcp 在Claude Code内部检查连接状态或重新进行身份验证。

想托管自己的实例吗？看 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 如果测验结束后水槽出现故障。

______________________________________________________________________

存储库结构

需求

发展

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

测验模式

这 Quiz 格式在中定义 packages/core 作为Zod模式导出为JSON模式 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

软件包自述文件

• apps/cli/README.md --MCP工具、生命周期行为、CLI命令
• apps/runner/README.md --独立运行器CLI标志、退出代码、体系结构
• apps/remote-mcp-oauth/README.md --托管远程MCP服务器、OAuth设置、Cloudflare部署
• -域架构，对API进行分级，验证，添加问题类型
• --REST端点、SSR服务器选项， QuizService 界面，主题化
• --客户端包内部、Vite清单、自定义部署
• — `` 元素API、事件、主题化、框架集成