Homework Grading

You can run Homework Grading MCP to automatically identify and grade student submission images using a multi‑modal model. It supports single and batch grading across multiple subjects, accepts images via URL or Base64, and integrates with MCP clients for flexible workflows.

How to use

You interact with the server through an MCP client. Start the MCP server locally and then send grading requests using image sources (URL or Base64), specify the subject and student name, and optionally provide per-question details. You can perform single submissions or batch grade several submissions at once. The server returns structured grading results with per-question feedback and overall score.

Practical usage patterns include:

• Grade a single homework image by URL with subject and student name.
• Submit a Base64 image for grading when you cannot host the image publicly.
• Batch grade multiple submissions by providing an array of submissions with image URLs or Base64 data.
• Optionally specify per-question information such as question id, type, content, standard answer, and points to influence scoring.

How to install

Prerequisites: ensure Node.js is installed (version 18 or newer) and you have npm or pnpm. You also need a ModelScope API key to access the model services.

# Global installation (recommended for quick start)
npm install -g @pickstar-2002/homework-grading-mcp@latest

# Local installation (in your project)
npm install @pickstar-2002/homework-grading-mcp@latest

Set up the API key in your environment before running the server.

cp .env.example .env

# Edit the .env file to include your API key
MODELSCOPE_API_KEY=your-modelscope-api-key-here

Configuration and running notes

You can run the MCP client locally using the stdio mode, which starts a local process for the MCP server. The following configuration uses the npx command to run the package and passes your API key via environment variables.

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

Examples of usage patterns

Example 1: Grade using an image URL for Mathematics, with a student name.

{
  "tool": "grade_homework",
  "arguments": {
    "imageUrl": "https://example.com/homework.jpg",
    "subject": "数学",
    "studentName": "张三"
  }
}

Example 2: Grade using Base64 image data.

{
  "tool": "grade_homework",
  "arguments": {
    "imageData": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
    "subject": "数学",
    "studentName": "张三"
  }
}

Example 3: Batch grade multiple submissions.

{
  "tool": "batch_grade_homework",
  "arguments": {
    "submissions": [
      {
        "imageUrl": "https://example.com/student1-homework.jpg",
        "subject": "数学",
        "studentName": "张三"
      },
      {
        "imageUrl": "https://example.com/student2-homework.jpg",
        "subject": "数学",
        "studentName": "李四"
      }
    ]
  }
}

Optional per-question details

If you have per-question metadata, you can specify it to influence scoring and explanations for each question.

{
  "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
      }
    ]
  }
}

结果与反馈

完成批改后，你将收到一个结构化的结果对象，其中包含总分、满分、等级、逐题结果、学生答案、正确答案、解析与个性化反馈，以及批改时间。这样你可以快速整理作业并给出明确的改进建议。

开发与贡献提示

若你计划自建或本地调试，请按以下步骤进行开发与测试。确保在开发环境中使用真实的 MODELSCOPE_API_KEY。

# 克隆仓库并进入目录
git clone https://github.com/pickstar-2002/homework-grading-mcp.git
cd homework-grading-mcp

# 安装依赖
npm install

# 配置环境
cp .env.example .env
# 编辑 .env，填入 MODELSCOPE_API_KEY

# 开发运行
npm run dev

# 构建项目
npm run build

常见问题与注意事项

确保 API 密钥配置正确、网络连接正常，且魔搭社区的服务可用。支持常见图片格式（JPEG、PNG、GIF、BMP、WebP 等）。批改准确性取决于多模态模型，重要作业请人工复核。当前版本使用内置评分标准，未来版本可能支持自定义规则。

Available tools

grade_homework

Grades a single homework image by subject, student name, and optional per-question details; returns per-question results plus overall score and feedback.

batch_grade_homework

Processes multiple submissions in one call, each with image source, subject, and student name; returns aggregated results.