npm package: @pickstar-2002/oneclick-test-generation-mcp
Description: 一键生成试题的MCP服务端 - One-click test generation MCP server
Author: pickstar-2002
Latest version: 1.0.1

# ✨ 一键生成试题 MCP 服务端

[![npm version](https://img.shields.io/npm/v/@pickstar-2002/oneclick-test-generation-mcp?color=green)](https://www.npmjs.com/package/@pickstar-2002/oneclick-test-generation-mcp)
[![License: MIT](https://img.shields.io/npm/l/@pickstar-2002/oneclick-test-generation-mcp)](https://opensource.org/licenses/MIT)
[![Node.js >=18](https://img.shields.io/badge/Node.js-%3E%3D18-blue)](https://nodejs.org/)

基于 Model Context Protocol (MCP) 的智能试题生成服务端，通过调用魔搭社区 Qwen3-235B-A22B-Instruct-2507 模型，一键生成高质量的学科试题。

## 🚀 功能特性

- **📚 多学科支持**：语文、数学、英语、物理、化学、生物、历史、地理、政治等
- **🎯 全年级覆盖**：从小学到大学，适配不同年级难度
- **📝 丰富题型**：单选题、多选题、判断题、填空题、简答题、论述题
- **⚙️ 智能难度**：简单、中等、困难三级难度设置
- **🔍 知识点精准**：基于指定知识点生成相关题目
- **💡 详细解析**：可选题目解析，帮助学生理解
- **🎨 自然语言**：支持自然语言形式的生成请求
- **🔒 类型安全**：完整的 TypeScript 类型定义和验证

## 📦 安装

### 全局安装（推荐）

```bash
npm install -g @pickstar-2002/oneclick-test-generation-mcp@latest
```

### 本地安装

```bash
npm install @pickstar-2002/oneclick-test-generation-mcp@latest
```

## 🔧 配置

### 1. 获取 ModelScope API 密钥

1. 访问 [魔搭社区](https://www.modelscope.cn/)
2. 注册/登录账号
3. 进入 [API密钥管理](https://www.modelscope.cn/my/myaccesstoken)
4. 创建新的 API 密钥

### 2. 配置环境变量

创建 `.env` 文件：

```bash
# ModelScope API Configuration
MODELSCOPE_API_KEY=your_modelscope_api_key_here
MODELSCOPE_BASE_URL=https://api-inference.modelscope.cn/v1
QWEN_MODEL=Qwen/Qwen3-235B-A22B-Instruct-2507

# MCP Server Configuration
MCP_SERVER_NAME=oneclick-test-generation-mcp
MCP_SERVER_VERSION=1.0.0
```

## 🚀 使用方式

### 命令行启动

```bash
# 直接运行（需要配置环境变量）
npx @pickstar-2002/oneclick-test-generation-mcp

# 或者使用环境变量文件
export MODELSCOPE_API_KEY=your_api_key
npx @pickstar-2002/oneclick-test-generation-mcp
```

### MCP 客户端配置

在支持 MCP 的 IDE（如 Cursor、Windsurf）中配置：

```json
{
  "mcpServers": {
    "test-generation": {
      "command": "npx",
      "args": ["@pickstar-2002/oneclick-test-generation-mcp@latest"],
      "env": {
        "MODELSCOPE_API_KEY": "your_modelscope_api_key_here"
      }
    }
  }
}
```

## 🛠️ 工具接口

### generate_test_questions

生成指定参数的学科试题。

#### 输入参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `subject` | string | ✅ | 学科类型：chinese, math, english, physics, chemistry, biology, history, geography, politics, other |
| `grade` | string | ✅ | 年级：grade_1-12, university, other |
| `knowledgePoint` | string | ✅ | 知识点描述 |
| `questionType` | string | ✅ | 题型：single_choice, multiple_choice, true_false, fill_blank, short_answer, essay |
| `difficulty` | string | ✅ | 难度：easy, medium, hard |
| `questionCount` | number | ✅ | 题目数量（1-50） |
| `includeExplanation` | boolean | ❌ | 是否包含解析（默认：true） |
| `naturalLanguageInput` | string | ❌ | 自然语言形式的额外要求 |

#### 使用示例

```json
{
  "name": "generate_test_questions",
  "arguments": {
    "subject": "math",
    "grade": "grade_7",
    "knowledgePoint": "一元一次方程",
    "questionType": "single_choice",
    "difficulty": "medium",
    "questionCount": 5,
    "includeExplanation": true,
    "naturalLanguageInput": "题目要贴近生活实际，包含应用题"
  }
}
```

#### 返回结果

成功时返回结构化的 JSON 格式试题：

```json
{
  "success": true,
  "questions": [
    {
      "id": "question_1",
      "questionNumber": 1,
      "question": "解方程：2x + 5 = 15",
      "options": ["x = 5", "x = 10", "x = 15", "x = 20"],
      "correctAnswer": "x = 5",
      "explanation": "将方程两边同时减去5，得到2x = 10，然后两边同时除以2，得到x = 5。",
      "difficulty": "medium",
      "questionType": "single_choice",
      "knowledgePoint": "一元一次方程"
    }
  ],
  "metadata": {
    "totalQuestions": 5,
    "subject": "math",
    "grade": "grade_7",
    "knowledgePoint": "一元一次方程",
    "difficulty": "medium",
    "questionType": "single_choice",
    "generatedAt": "2025-12-05T10:30:00.000Z"
  }
}
```

错误时返回错误信息：

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "输入参数验证失败",
    "details": "subject: 必填字段"
  }
}
```

## 📚 支持的学科和题型

### 学科列表
- 🈴 **chinese** - 语文
- 🔢 **math** - 数学  
- 🌍 **english** - 英语
- ⚛️ **physics** - 物理
- 🧪 **chemistry** - 化学
- 🧬 **biology** - 生物
- 📜 **history** - 历史
- 🗺️ **geography** - 地理
- 🏛️ **politics** - 政治
- 📖 **other** - 其他

### 题型列表
- ☑️ **single_choice** - 单选题
- ✅ **multiple_choice** - 多选题  
- ◯ **true_false** - 判断题
- 📝 **fill_blank** - 填空题
- 📄 **short_answer** - 简答题
- 📃 **essay** - 论述题

### 难度等级
- 🟢 **easy** - 简单
- 🟡 **medium** - 中等
- 🔴 **hard** - 困难

## 🔧 开发

### 本地开发

```bash
# 克隆项目
git clone https://github.com/pickstar-2002/oneclick-test-generation-mcp.git
cd oneclick-test-generation-mcp

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建项目
npm run build

# 运行构建后的版本
npm start
```

### 环境要求

- Node.js >= 18.0.0
- npm 或 pnpm
- ModelScope API 密钥

## 🤝 贡献

暂不接受外部贡献。如有建议或问题，请在 [Issues](https://github.com/pickstar-2002/oneclick-test-generation-mcp/issues) 中提出。

## 📄 许可证

MIT License © 2025 pickstar-2002

## 🔗 相关链接

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [魔搭社区 ModelScope](https://www.modelscope.cn/)
- [Qwen3 模型](https://www.modelscope.cn/models/Qwen/Qwen3-235B-A22B-Instruct-2507)
- [npm 包页面](https://www.npmjs.com/package/@pickstar-2002/oneclick-test-generation-mcp)

## ⚠️ 注意事项

1. **API 密钥安全**：请妥善保管您的 ModelScope API 密钥，不要将其提交到代码仓库
2. **使用限制**：请遵守魔搭社区的使用条款和 API 调用限制
3. **内容质量**：生成的试题内容仅供参考，建议人工审核后使用
4. **网络要求**：需要稳定的网络连接以访问 ModelScope API

## 📞 支持

如遇到问题，请：
1. 检查环境变量配置是否正确
2. 确认 ModelScope API 密钥有效
3. 查看服务器日志获取详细错误信息
4. 在 [GitHub Issues](https://github.com/pickstar-2002/oneclick-test-generation-mcp/issues) 提交问题