📝 作业批改 MCP 服务端

npm version License: MIT Node.js Version TypeScript MCP Downloads Last Commit

🌟 项目简介

作业批改 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
编辑配置文件，添加 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