📝 作业批改 MCP
🌟 项目简介
作业批改 MCP 是一个基于 Model Context Protocol (MCP) 的智能作业批改服务，通过集成魔搭社区的 Qwen3-VL-235B-A22B-Instruct 多模态模型，实现对学生作业图片的智能识别和批改。
✨ 核心功能
- 🎯 智能识别: 自动识别作业图片中的题目和学生答案
- 🔍 精准批改: 逐题判断答案正确性，提供详细评分
- 💡 智能解析: 为每道题提供简洁明了的解析说明
- 📊 结构化输出: 按照标准格式输出批改结果
- 🚀 批量处理: 支持同时批改多份作业
- 🎨 多科支持: 支持数学、语文、英语等多个学科
- 🌐 URL支持: 支持Base64和URL两种方式上传图片
- ⚡ CDN兼容: 支持各种CDN图片链接，自动处理重定向
🚀 快速开始
📋 环境要求
- Node.js >= 18.0.0
- npm 或 pnpm 包管理器
- 魔搭社区 API 密钥
📦 安装
全局安装（推荐）
npm install -g @pickstar-2002/homework-grading-mcp@latest
本地安装
npm install @pickstar-2002/homework-grading-mcp@latest
⚙️ 配置
-
获取魔搭社区 API 密钥
- 访问 魔搭社区
- 注册账号并获取 API 密钥
-
设置环境变量
创建
.env文件：cp .env.example .env编辑
.env文件，填入你的 API 密钥：MODELSCOPE_API_KEY=your-modelscope-api-key-here
🔧 使用说明
🏃♂️ 命令行启动
# 直接运行
homework-grading-mcp
# 或使用 npx（推荐）
npx @pickstar-2002/homework-grading-mcp@latest
🔌 IDE 集成配置
VS Code + Cline 配置
-
安装 Cline 插件：在 VS Code 扩展商店搜索并安装 "Cline" 插件
-
配置 MCP 服务器：在 VS Code 设置中搜索 "MCP"，找到 Cline 的 MCP 配置
-
添加服务器配置：
{
"mcpServers": {
"homework-grading": {
"command": "npx",
"args": ["@pickstar-2002/homework-grading-mcp@latest"],
"env": {
"MODELSCOPE_API_KEY": "your-modelscope-api-key-here"
}
}
}
}
- 重启 VS Code：配置完成后重启 VS Code 使配置生效
Claude Desktop 配置
-
找到配置文件：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
编辑配置文件，添加 MCP 服务器配置：
{
"mcpServers": {
"homework-grading": {
"command": "npx",
"args": ["@pickstar-2002/homework-grading-mcp@latest"],
"env": {
"MODELSCOPE_API_KEY": "your-modelscope-api-key-here"
}
}
}
}
- 重启 Claude Desktop：保存配置后重启应用
其他 MCP 客户端
任何支持 MCP 协议的客户端都可以使用，配置方式类似：
{
"command": "npx",
"args": ["@pickstar-2002/homework-grading-mcp@latest"],
"env": {
"MODELSCOPE_API_KEY": "your-api-key"
}
}
🎯 使用示例
方式1：使用图片URL（推荐）
{
"tool": "grade_homework",
"arguments": {
"imageUrl": "https://example.com/homework.jpg",
"subject": "数学",
"studentName": "张三"
}
}
方式2：使用Base64图片数据
{
"tool": "grade_homework",
"arguments": {
"imageData": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
"subject": "数学",
"studentName": "张三"
}
}
方式3：批量批改作业
{
"tool": "batch_grade_homework",
"arguments": {
"submissions": [
{
"imageUrl": "https://example.com/student1-homework.jpg",
"subject": "数学",
"studentName": "张三"
},
{
"imageUrl": "https://example.com/student2-homework.jpg",
"subject": "数学",
"studentName": "李四"
}
]
}
}
方式4：指定题目信息（可选）
{
"tool": "grade_homework",
"arguments": {
"imageUrl": "https://example.com/homework.jpg",
"subject": "数学",
"studentName": "张三",
"questions": [
{
"id": "q1",
"type": "calculation",
"content": "计算 2 + 3 = ?",
"standardAnswer": "5",
"points": 5
},
{
"id": "q2",
"type": "choice",
"content": "下列哪个是偶数？A. 3 B. 4 C. 5",
"standardAnswer": "B",
"points": 5
}
]
}
}
实际使用场景示例
场景1：数学老师批改几何作业
{
"tool": "grade_homework",
"arguments": {
"imageUrl": "https://5b0988e595225.cdn.sohucs.com/images/20180108/86e7ed5ce5154f5e8df5ae422ce61f93.jpeg",
"subject": "数学",
"studentName": "王同学"
}
}
场景2：语文老师批改作文
{
"tool": "grade_homework",
"arguments": {
"imageData": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
"subject": "语文",
"studentName": "李同学"
}
}
📊 返回结果格式
批改结果结构
interface HomeworkGradingResponse {
submissionId: string; // 提交ID
totalScore: number; // 总得分
maxTotalScore: number; // 满分
grade: 'A' | 'B' | 'C' | 'D' | 'F'; // 等级
results: GradingResult[]; // 每题详细结果
overallFeedback: string; // 总体反馈
gradedAt: string; // 批改时间
}
interface GradingResult {
questionId: string; // 题目ID
isCorrect: boolean; // 是否正确
studentAnswer: string; // 学生答案
correctAnswer: string; // 正确答案
explanation: string; // 解析说明
score: number; // 得分
maxScore: number; // 满分
feedback: string; // 反馈意见
}
🛠️ 开发指南
📁 项目结构
├── src/
│ ├── config.ts # 配置文件
│ ├── types.ts # TypeScript 类型定义
│ ├── index.ts # 主入口文件
│ ├── services/ # 服务层
│ │ ├── modelService.ts # 模型服务
│ │ └── gradingService.ts # 批改服务
│ ├── tools/ # MCP工具
│ │ └── gradingTools.ts # 批改工具定义
│ └── utils/ # 工具函数
│ ├── logger.ts # 日志工具
│ └── image.ts # 图片处理工具
├── package.json
├── tsconfig.json
└── README.md
🏗️ 本地开发
-
克隆项目
git clone https://github.com/pickstar-2002/homework-grading-mcp.git cd homework-grading-mcp -
安装依赖
npm install -
配置环境
cp .env.example .env # 编辑 .env 文件，填入 API 密钥 -
开发运行
npm run dev -
构建项目
npm run build
🧪 测试
# 运行测试（如果有）
npm test
# 启动开发服务器进行测试
npm run dev
🔧 环境变量
| 变量名 | 说明 | 默认值 |
|---|---|---|
MODELSCOPE_API_KEY | 魔搭社区 API 密钥 | 必填 |
MCP_SERVER_NAME | MCP 服务器名称 | homework-grading-mcp |
MCP_SERVER_VERSION | MCP 服务器版本 | 1.0.0 |
LOG_LEVEL | 日志级别 | info |
🎨 支持的题型
- ✅ 选择题 (choice)
- ✅ 填空题 (fill)
- ✅ 计算题 (calculation)
- ✅ 作文题 (essay)
📚 支持的科目
- 📐 数学 - 计算题、应用题、几何题等
- 📖 语文 - 阅读理解、作文、古诗词等
- 🌍 英语 - 语法、翻译、作文等
- 🧪 物理 - 计算题、实验题等
- ⚗️ 化学 - 方程式、计算题等
- 🌏 地理 - 地图题、简答题等
- 🏛️ 历史 - 简答题、材料题等
- 🧬 生物 - 简答题、实验题等
🤝 贡献指南
欢迎提交 Issue 和 Pull Request！
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add some amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
📝 更新日志
v1.0.0 (2025-01-01)
- 🎉 初始版本发布
- ✨ 支持单份作业批改
- 📚 支持批量作业批改
- 🎯 支持多种题型
- 📊 提供详细批改结果
🐛 常见问题
Q: 模型连接失败怎么办？
A: 请检查：
- API 密钥是否正确配置
- 网络连接是否正常
- 魔搭社区服务是否可用
Q: 支持哪些图片格式？
A: 支持 JPEG、PNG、GIF、BMP、WebP 等常见格式
Q: 批改准确率如何？
A: 基于 Qwen3-VL 多模态模型，准确率较高，但建议人工复核重要作业
Q: 可以自定义评分标准吗？
A: 目前使用内置评分标准，后续版本将支持自定义评分规则
📄 许可证
本项目基于 MIT 许可证 开源。
👤 作者
pickstar-2002
- 📧 邮箱: pickstar-2002@example.com
- 🌐 GitHub: @pickstar-2002
🙏 致谢
- Model Context Protocol - 提供 MCP 协议支持
- 魔搭社区 - 提供 Qwen3-VL 模型服务
- OpenAI - 提供 OpenAI SDK
⭐ 如果这个项目对你有帮助，请给个 Star！
Made with ❤️ by pickstar-2002