guess-mcp

v1.0.3

Published

a year ago

小猜助手 - AI智能题目生成和管理系统

0High
0Medium
0Low

tianmin

mcp question-generator guess-mcp quiz education ai prompt-engineering model-context-protocol

小猜助手

小猜助手 - AI智能题目生成和管理系统

智能题目生成和审核系统 - Model Context Protocol (MCP) 服务

开发者：天明

功能特性

🎯 支持5种题型：单选题、多选题、判断题、填空题、排序题
📝 智能提示词生成：大纲整理、细节补充、题目生成
🔄 题目审核流程：重新完善、答案核实、批量保存
💾 数据库集成：直接保存题目到小猜系统
🌍 多环境支持：开发环境和生产环境
🔍 题目搜索：支持关键词、题型、难度、分类等多维度搜索
🎲 相似度检测：保存前自动检测重复题目
📋 最近题目：快速查看最近生成的题目
⚡ 智能默认：未指定题目类型时自动使用单选题

安装

npm install guess-mcp

或全局安装：

npm install -g guess-mcp

或使用 npx 直接运行（推荐）：

npx guess-mcp

快速开始

1. 初始化配置

npx guess-mcp init

根据提示选择环境和配置API Token。

2. 启动MCP服务

# 开发环境
npx guess-mcp start

# 生产环境
npx guess-mcp start --env prod

3. 测试连接

npx guess-mcp test

4. 交互式生成题目

npx guess-mcp generate

配置说明

方式一：使用 .env 文件（推荐）

在项目根目录创建 .env 文件：

# 环境：development（开发）或 production（生产）
NODE_ENV=development

# API Token（必填）- 请填写您自己的token
API_TOKEN=your_api_token_here

# 日志级别
LOG_LEVEL=info
VERBOSE=false

方式二：配置到 Claude Desktop

macOS/Linux

编辑配置文件：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "小猜助手": {
      "command": "npx",
      "args": ["-y", "guess-mcp", "start"],
      "env": {
        "API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Windows

编辑配置文件：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "小猜助手": {
      "command": "npx.cmd",
      "args": ["-y", "guess-mcp", "start"],
      "env": {
        "API_TOKEN": "your_api_token_here"
      }
    }
  }
}

方式三：配置到 Cursor 或其他 MCP 客户端

在 MCP 客户端配置文件中添加：

{
  "mcpServers": {
    "小猜助手": {
      "command": "npx",
      "args": ["-y", "guess-mcp", "start"],
      "env": {
        "API_TOKEN": "your_api_token_here"
      }
    }
  }
}

环境配置

开发环境 (development): http://127.0.0.1:8000
生产环境 (production): https://ask.he29.com

配置参数说明

| 参数 | 必填 | 默认值 | 说明 | |-----|------|-------|------| | NODE_ENV | 否 | development | 运行环境：development 或 production | | API_TOKEN | ⚠️ 是 | - | API认证令牌（必须填写您自己的token） | | LOG_LEVEL | 否 | info | 日志级别：debug、info、warn、error | | VERBOSE | 否 | false | 是否输出详细日志 |

🎯 智能默认行为

题目类型默认值：

当用户未指定 question_type 时，系统自动使用单选题（question_type = 1）
当用户未指定 difficulty 时，系统自动使用中等难度（difficulty = 3）

使用示例：

// 用户只提供主题，系统自动使用单选题
{
  "topic": "甄嬛传人物关系"
}
// 等同于
{
  "question_type": 1,
  "topic": "甄嬛传人物关系",
  "difficulty": 3
}

⚠️ 重要：交互式确认流程

关键原则：

🔄 必须等待用户确认：预览题目后，系统必须等待用户明确回复
❌ 禁止自动操作：不要自动保存题目或生成下一道题
✅ 用户主导：只有用户明确回复后，才能使用相应的工具

正确流程：

生成题目 → 预览题目 → 等待用户确认
用户回复"确认" → 使用 confirm_question 工具保存
用户回复"修改" → 使用 edit_question 工具编辑
用户回复"跳过" → 使用 skip_question 工具跳过
保存/跳过完成后 → 生成下一道题

相似度检查流程：

用户确认题目 → 系统检查相似度
相似度 ≤ 50% → 直接保存
相似度 > 50% → 显示相似度警告，等待用户确认
用户回复"确认保存" → 使用 force_save_question 工具强制保存
用户回复"重新编辑" → 使用 edit_question 工具编辑
用户回复"跳过" → 使用 skip_question 工具跳过

⚠️ 安全提醒

🔒 不要将 API_TOKEN 提交到版本控制系统
🔒 不要在公开的配置文件中暴露您的token
🔒 建议使用环境变量或配置文件管理敏感信息

MCP工具列表

1. get_question_types

获取支持的题目类型列表

输入：无

输出：

{
  "success": true,
  "data": [
    {
      "type": 1,
      "name": "单选题",
      "min_options": 2,
      "max_options": 6
    }
  ]
}

2. generate_outline_prompt

生成题目大纲整理提示词

输入：

{
  "question_type": 1,
  "topic": "JavaScript闭包",
  "difficulty": 3,
  "custom_requirements": "需要实际代码示例"
}

注意：如果未指定 question_type，系统默认使用单选题（question_type = 1）

输出：

{
  "success": true,
  "prompt": "# 题目大纲整理\n...",
  "metadata": {
    "question_type": 1,
    "topic": "JavaScript闭包",
    "difficulty": 3
  }
}

3. generate_detail_prompt

生成细节补充提示词

输入：

{
  "question_type": 1,
  "topic": "JavaScript闭包",
  "difficulty": 3,
  "outline": "整理后的大纲内容...",
  "user_feedback": "需要更多实例"
}

4. generate_question_prompt

生成完整题目生成提示词

输入：

{
  "question_type": 1,
  "topic": "JavaScript闭包",
  "difficulty": 3,
  "enhanced_outline": "增强后的大纲内容...",
  "custom_requirements": "包含代码示例"
}

5. save_question

保存题目到数据库

输入：

{
  "question_data": {
    "question_type": 1,
    "title": "以下关于JavaScript闭包的描述，哪个是正确的？",
    "description": "考察对闭包概念的理解",
    "difficulty": 3,
    "category": "JavaScript",
    "options": [
      {"text": "闭包是函数和其词法环境的组合", "is_correct": 1},
      {"text": "闭包只能在全局作用域中创建", "is_correct": 0},
      {"text": "闭包不能访问外部变量", "is_correct": 0},
      {"text": "闭包会导致内存泄漏", "is_correct": 0}
    ],
    "correct_answer": "A",
    "explanation": "闭包是函数和其声明时所在的词法环境的组合...",
    "hint": "考虑函数作用域和变量访问"
  },
  "category_id": 1
}

输出：

{
  "success": true,
  "data": {
    "id": 123,
    "question_id": "q_20250118_abc123",
    "message": "题目保存成功"
  }
}

6. batch_save_questions

批量保存题目

7. update_question

更新题目

8. delete_question

删除题目

9. get_question

获取题目详情

输入：

{
  "question_id": "q_20250118_abc123"
}

10. get_categories

获取题目分类列表

输出：

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "JavaScript",
      "description": "JavaScript相关题目"
    }
  ]
}

11. search_questions

搜索题目

输入：

{
  "keyword": "闭包",
  "question_type": 1,
  "difficulty": 3,
  "category_id": 1,
  "status": "published",
  "page": 1,
  "limit": 20,
  "sort_by": "create_time",
  "sort_order": "desc"
}

输出：

{
  "success": true,
  "data": {
    "list": [...],
    "total": 100,
    "page": 1,
    "limit": 20
  }
}

12. check_similarity

检测题目相似度（保存前调用，防止重复）

输入：

{
  "title": "以下关于JavaScript闭包的描述，哪个是正确的？",
  "question_id": null
}

输出：

{
  "success": true,
  "data": {
    "has_similar": true,
    "similar_questions": [
      {
        "id": 123,
        "title": "关于JavaScript闭包的描述正确的是？",
        "similarity": 85.5
      }
    ]
  }
}

13. find_recent_questions

查找最近的题目（默认20条，最大99条）

输入：

{
  "limit": 20
}

输出：

{
  "success": true,
  "data": [
    {
      "id": 123,
      "question_id": "q_20250118_abc123",
      "title": "题目标题",
      "type": 1,
      "type_name": "单选题",
      "difficulty": 3,
      "category": "JavaScript",
      "create_time": "2025-01-18 10:30:00"
    }
  ]
}

14. generate_refine_prompt

生成题目重新完善提示词

输入：

{
  "question_data": {...},
  "issues": "选项D的描述不够准确"
}

15. generate_verify_prompt

生成答案核实提示词

输入：

{
  "question_data": {...},
  "doubt_reason": "不确定选项B是否正确"
}

16. preview_question

预览题目内容（用于交互式确认）

输入：

{
  "question_data": {...},
  "question_index": 1,
  "total_questions": 5
}

输出：

📝 第 1/5 题预览
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
题目类型: 单选题
难度等级: 中等
分类: 甄嬛传

题目内容:
在《甄嬛传》中，甄嬛最初入宫时的位分是什么？

选项:
A. 答应 ✅
B. 常在
C. 贵人
D. 嫔

正确答案: A

答案解析:
甄嬛最初入宫时被封为答应，这是清朝后宫妃嫔等级中最低的一级。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❓ 请确认这道题目是否符合要求？
回复格式：
- 输入 "确认" 或 "可以" 保存这道题并继续下一题
- 输入 "修改" 或 "编辑" + 具体修改意见
- 输入 "跳过" 放弃这道题继续下一题

17. confirm_question

确认题目并保存到数据库（自动检查相似度）

输入：

{
  "question_data": {...},
  "category_id": 1,
  "force_save": false
}

输出（无相似题目）：

{
  "success": true,
  "data": {
    "id": 123,
    "question_id": "q_20250118_abc123"
  },
  "message": "题目已保存成功！",
  "similarity_checked": true
}

输出（发现相似题目）：

⚠️ 相似度检查警告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
发现数据库中存在相似题目：

1. 相似度: 85.2%
   题目: 甄嬛传中甄嬛的位分是什么？
   题目ID: 123

2. 相似度: 72.1%
   题目: 甄嬛入宫时的身份是什么？
   题目ID: 124

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❓ 是否仍要保存这道题目？

⚠️ 重要：发现相似题目，必须等待用户确认！

回复格式：
- 输入 "确认保存" 或 "强制保存" 忽略相似度警告，直接保存
- 输入 "重新编辑" 或 "修改" + 具体修改意见
- 输入 "跳过" 放弃这道题继续下一题

🔄 请用户明确回复后，再使用 force_save_question、edit_question 或 skip_question 工具

18. edit_question

编辑题目内容（根据用户反馈修改）

输入：

{
  "question_data": {...},
  "feedback": "选项A应该是常在，不是答应"
}

输出：

{
  "success": true,
  "edit_prompt": "根据用户反馈，需要修改题目...",
  "message": "已生成题目编辑提示词，请根据反馈重新生成题目"
}

19. skip_question

跳过当前题目，继续下一题

输入：

{
  "reason": "题目内容不符合要求"
}

输出：

{
  "success": true,
  "message": "题目已跳过（原因：题目内容不符合要求），继续下一题",
  "skipped": true
}

20. force_save_question

强制保存题目（忽略相似度警告）

输入：

{
  "question_data": {...},
  "category_id": 1
}

输出：

{
  "success": true,
  "data": {
    "id": 123,
    "question_id": "q_20250118_abc123"
  },
  "message": "题目已强制保存成功！（已忽略相似度警告）",
  "force_saved": true
}

使用流程

🎯 交互式逐题确认流程（推荐）

1. 用户提出出题需求（如：帮我生成5道甄嬛传相关的题）
   ↓
2. MCP生成第1道题 (generate_single_question)
   ↓
3. 大模型根据提示词生成第1道题
   ↓
4. MCP预览第1道题 (preview_question)
   ↓
5. 用户确认：符合要求？
    ├─ 符合 → MCP检查相似度并保存题目 (confirm_question)
    │   ├─ 无相似题目 → 直接保存 → 生成第2道题
    │   └─ 有相似题目（>50%）→ 显示相似度警告 → 用户再次确认
    │       ├─ 确认保存 → MCP强制保存 (force_save_question) → 生成第2道题
    │       ├─ 重新编辑 → MCP编辑题目 (edit_question) → 重新生成 → 再次确认
    │       └─ 跳过 → MCP跳过题目 (skip_question) → 生成第2道题
    ├─ 不符合 → MCP编辑题目 (edit_question) → 重新生成 → 再次确认
    └─ 放弃 → MCP跳过题目 (skip_question) → 生成第2道题
   ↓
6. 重复步骤2-5，直到所有题目处理完成

📝 交互式确认示例

用户: "帮我生成5道甄嬛传相关的题"

MCP:

🎯 第 1/5 题生成
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
题目类型: 单选题
主题: 甄嬛传
难度: 中等
特殊要求: 无

请使用以下提示词生成题目：

[题目生成提示词内容...]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 请根据上述提示词生成题目，然后使用 preview_question 工具预览题目内容

大模型生成题目后，MCP预览:

📝 第 1/5 题预览
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
题目类型: 单选题
难度等级: 中等
分类: 甄嬛传

题目内容:
在《甄嬛传》中，甄嬛最初入宫时的位分是什么？

选项:
A. 答应 ✅
B. 常在
C. 贵人
D. 嫔

正确答案: A

答案解析:
甄嬛最初入宫时被封为答应，这是清朝后宫妃嫔等级中最低的一级。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❓ 请确认这道题目是否符合要求？

⚠️ 重要：请等待用户确认后再进行下一步操作！

回复格式：
- 输入 "确认" 或 "可以" 保存这道题并继续下一题
- 输入 "修改" 或 "编辑" + 具体修改意见
- 输入 "跳过" 放弃这道题继续下一题

🔄 请用户回复确认后，再使用 confirm_question、edit_question 或 skip_question 工具

用户: "确认"

MCP:

⚠️ 相似度检查警告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
发现数据库中存在相似题目：

1. 相似度: 85.2%
   题目: 甄嬛传中甄嬛的位分是什么？
   题目ID: 123

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❓ 是否仍要保存这道题目？
回复格式：
- 输入 "确认保存" 或 "强制保存" 忽略相似度警告，直接保存
- 输入 "重新编辑" 或 "修改" + 具体修改意见
- 输入 "跳过" 放弃这道题继续下一题

用户: "确认保存"

MCP: "✅ 题目已强制保存成功！（已忽略相似度警告）继续第2题..."

用户: "修改：选项A应该是常在，不是答应"

MCP: "🔄 已生成题目编辑提示词，请根据反馈重新生成题目..."

传统批量流程（不推荐）

1. 用户选择题型和主题
   ↓
2. MCP生成大纲整理提示词 (generate_outline_prompt)
   ↓
3. 大模型整理大纲
   ↓
4. 用户确认大纲
   ↓
5. MCP生成细节补充提示词 (generate_detail_prompt)
   ↓
6. 大模型补充细节
   ↓
7. 用户确认细节
   ↓
8. MCP生成题目生成提示词 (generate_question_prompt)
   ↓
9. 大模型生成题目
   ↓
10. 用户核验题目
    ↓
11. MCP保存题目到数据库 (save_question)

题目审核流程

如果题目不正确，可以：

重新完善：使用 generate_refine_prompt 生成重新完善提示词
核实答案：使用 generate_verify_prompt 生成答案核实提示词
删除题目：使用 delete_question 删除当前题目

题目数据格式

单选题

{
  "question_type": 1,
  "title": "题目内容",
  "difficulty": 3,
  "category": "分类名称",
  "options": [
    {"text": "选项A", "is_correct": 1},
    {"text": "选项B", "is_correct": 0},
    {"text": "选项C", "is_correct": 0},
    {"text": "选项D", "is_correct": 0}
  ],
  "correct_answer": "A",
  "explanation": "答案解析"
}

多选题

{
  "question_type": 2,
  "title": "题目内容（多选）",
  "options": [
    {"text": "选项A", "is_correct": 1},
    {"text": "选项B", "is_correct": 1},
    {"text": "选项C", "is_correct": 0},
    {"text": "选项D", "is_correct": 0}
  ],
  "correct_answer": "AB"
}

判断题

{
  "question_type": 3,
  "title": "判断陈述",
  "options": [
    {"text": "正确", "is_correct": 1},
    {"text": "错误", "is_correct": 0}
  ],
  "correct_answer": "A"
}

填空题

{
  "question_type": 4,
  "title": "题目内容，用____表示填空",
  "options": [],
  "correct_answer": "标准答案"
}

排序题

{
  "question_type": 5,
  "title": "将以下选项按正确顺序排列",
  "options": [
    {"text": "第一项", "is_correct": 0, "correct_order": 1},
    {"text": "第二项", "is_correct": 0, "correct_order": 2},
    {"text": "第三项", "is_correct": 0, "correct_order": 3}
  ],
  "correct_answer": "1-2-3"
}

开发调试

# 克隆项目
git clone <repository-url>

# 安装依赖
cd mcp
npm install

# 开发模式
npm run dev

# 测试
npm run test

注意事项

API Token: 确保配置正确的API Token
网络连接: 确保能访问API服务器
题目质量: 大模型生成的题目需要人工审核
数据格式: 严格按照JSON格式提交题目数据

许可证

MIT License

常见问题

Q: 如何获取 API_TOKEN？

A: 请联系系统管理员获取您的专属API令牌。

Q: 为什么连接失败？

A: 请检查：

API_TOKEN 是否正确配置
网络连接是否正常
环境配置是否正确（dev/prod）
API服务器是否正常运行

Q: 如何在 Claude Desktop 中使用？

A: 按照上面的"配置到 Claude Desktop"章节配置后，重启 Claude Desktop 即可在对话中使用 QMaker MCP 的所有功能。

Q: 支持哪些 MCP 客户端？

A: QMaker MCP 支持所有遵循 Model Context Protocol 标准的客户端，包括：

Claude Desktop
Cursor
其他支持 MCP 的 IDE 和工具

更新日志

v1.0.3 (2025-01-18)

✅ 更新作者信息为天明
✅ 优化版本管理
✅ 完善文档说明

v1.0.2 (2025-01-18)

✅ 支持5种题型（单选、多选、判断、填空、排序）
✅ 智能提示词生成系统
✅ 题目搜索功能
✅ 相似度检测（防重复）
✅ 最近题目查询
✅ 完整的题目审核流程
✅ 多环境支持（dev/prod）

v1.0.0 (2025-01-18)

✅ 初始版本发布

联系方式

NPM包地址: guess-mcp
项目地址: GitHub
问题反馈: Issues