作业批改 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

配置

1. 获取魔搭社区 API 密钥

   • 访问 魔搭社区
   • 注册账号并获取 API 密钥

2. 设置环境变量

   创建 .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 配置

1. 安装 Cline 插件在 VS Code 扩展商店搜索并安装 "Cline" 插件

2. 配置 MCP 服务器在 VS Code 设置中搜索 "MCP"找到 Cline 的 MCP 配置

3. 添加服务器配置

{
  "mcpServers": {
    "homework-grading": {
      "command": "npx",
      "args": ["@pickstar-2002/homework-grading-mcp@latest"],
      "env": {
        "MODELSCOPE_API_KEY": "your-modelscope-api-key-here"
      }
    }
  }
}

1. 重启 VS Code配置完成后重启 VS Code 使配置生效

Claude Desktop 配置

1. 找到配置文件

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 编辑配置文件添加 MCP 服务器配置

{
  "mcpServers": {
    "homework-grading": {
      "command": "npx",
      "args": ["@pickstar-2002/homework-grading-mcp@latest"],
      "env": {
        "MODELSCOPE_API_KEY": "your-modelscope-api-key-here"
      }
    }
  }
}

1. 重启 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

本地开发

1. 克隆项目

   git clone https://github.com/pickstar-2002/homework-grading-mcp.git
   cd homework-grading-mcp
   

2. 安装依赖

   npm install
   

3. 配置环境

   cp .env.example .env
   # 编辑 .env 文件填入 API 密钥
   

4. 开发运行

   npm run dev
   

5. 构建项目

   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

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

更新日志

v1.0.0 (2025-01-01)

• 初始版本发布
• 支持单份作业批改
• 支持批量作业批改
• 支持多种题型
• 提供详细批改结果

常见问题

Q: 模型连接失败怎么办

A: 请检查

1. API 密钥是否正确配置
2. 网络连接是否正常
3. 魔搭社区服务是否可用

Q: 支持哪些图片格式

A: 支持 JPEGPNGGIFBMPWebP 等常见格式

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