Homework Grading MCP

Homework Grading MCP

Enables automated grading of student homework images using Qwen3-VL multimodal model, supporting multiple subjects and question types with detailed feedback and batch processing capabilities.

Category
访问服务器

README

📝 作业批改 MCP

<div align="center">

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

</div>

🌟 项目简介

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

  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: 支持 JPEG、PNG、GIF、BMP、WebP 等常见格式

Q: 批改准确率如何？

A: 基于 Qwen3-VL 多模态模型，准确率较高，但建议人工复核重要作业

Q: 可以自定义评分标准吗？

A: 目前使用内置评分标准，后续版本将支持自定义评分规则

📄 许可证

本项目基于 MIT 许可证 开源。

👤 作者

pickstar-2002

🙏 致谢

<div align="center">

⭐ 如果这个项目对你有帮助，请给个 Star！

Made with ❤️ by pickstar-2002

</div>

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选