Gradescope MCP Server

Gradscope MCP服务器

一 MCP（模型上下文协议） 服务器 等级范围 这暴露了课程管理， MCP的评分、重新评分审查、统计和人工智能辅助评分工作流程 客户。

该服务器专为希望使用AI代理的讲师和助教而设计 真实的Gradescope数据，同时将写操作控制在显式后面 确认。

此存储库还包括可重用的本地技能 skills/gradescope-assisted-grading/SKILL.md 用于人类认可的分级 工作流程。

当前状态

• 34个MCP工具
• 3 MCP资源
• 7个MCP提示
• 30个自动化测试
• Python 3.10+
• 包管理器： uv

项目提供什么

面向阅读的工作流程

• 课程发现和作业列表
• 在线和扫描PDF作业的作业大纲解析
• 使用自定义HTML解析器进行名册检查
• 多种任务类型的提交列表
• 评分进度、量规背景、答案组、重新评分和统计数据
• 缓存分级工件并回答关键快照的工作流助手

/tmp/gradescope-mcp

面向编写的工作流

• 上传提交内容
• 设置学生扩展名
• 修改分配日期
• 重命名作业
• 申请成绩
• 创建、更新和删除评价项目
• 对答案组进行批量评分

所有支持写入的工具都是先预览的，需要 confirm_write=True 在执行任何突变之前。

工具清单

核心

讲师/TA管理

评分阅读

评分写作

人工智能辅助/工作流助手

答案组

雷格拉德斯

统计

资源

提示

建筑

入口点

• src/gradescope_mcp/__main__.py：负载 .env，配置日志记录，运行

FastMCP服务器

• src/gradescope_mcp/server.py：注册所有工具、资源和提示

认证

• src/gradescope_mcp/auth.py：维护单例 GSConnection
• 凭据来自 GRADESCOPE_EMAIL 和 GRADESCOPE_PASSWORD
• .env 启动时会自动加载 python -m gradescope_mcp

工具模块

• tools/courses.py：课程列表和名册解析
• tools/assignments.py：作业列表和作业写入操作
• tools/submissions.py：上传、提交列表、评分者发现
• tools/extensions.py：扩展读写
• tools/grading.py：大纲解析、分数导出、评分进度
• tools/grading_ops.py：评分上下文、写作、量规CRUD、导航
• tools/grading_workflow.py: /tmp/gradescope-mcp 工件、答案键、准备就绪、页面

缓存、智能阅读

• tools/answer_groups.py：人工智能辅助答案组检查和批量写入
• tools/regrades.py：重新分级列表和详细检查
• tools/statistics.py：分配统计
• tools/safety.py：预览突变的第一个确认助手

重要行为和约束

写安全

• 修改工具在以下情况下返回预览 confirm_write=False
• 实际的变化只发生在 confirm_write=True
• 评分标准的编辑和删除可以级联到现有的成绩
• tool_grade_answer_group 可以同时影响多个提交，需要额外的

关心

提交ID

• tool_get_assignment_submissions 返回分配级别的全局提交

鉴定

• 评分工具需要问题提交ID
• 使用 tool_list_question_submissions, tool_get_next_ungraded，或分级

获取正确ID的上下文工具

评分方向

• 成绩范围问题可能是 positive 或 negative 评分
• 在这两种模式下，评估权重都以正数存储
• 评分模式决定了已检查的评分项目是增加还是减少

点

扫描/手写作业

• 结构化参考答案通常不可用
• 这是意料之中的，不一定是解析失败
• 工作流助手被构建为使用裁剪区域、完整页面、相邻页面、，

量规文本和用户提供的参考注释

快速开始

1.先决条件

• Python 3.10+
• 紫外线

2.安装

git clone https://github.com/Yuanpeng-Li/gradescope-mcp.git
cd gradescope-mcp
cp .env.example .env

然后编辑 .env 使用您的Gradescope证书。

3.在本地运行

uv run python -m gradescope_mcp

4.配置MCP客户端

客户端配置示例：

{
  "mcpServers": {
    "gradescope": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/gradescope-mcp",
        "python",
        "-m",
        "gradescope_mcp"
      ],
      "env": {
        "GRADESCOPE_EMAIL": "your_email@example.com",
        "GRADESCOPE_PASSWORD": "your_password"
      }
    }
  }
}

5.使用MCP检查器进行调试

npx @modelcontextprotocol/inspector uv run python -m gradescope_mcp

6.运行测试

uv run pytest -q

辅助评分技能

该存储库包括一个项目本地技能：

• gradescope-assisted-grading

其目的是：

• 预览第一评分
• 突变前的量规审查
• 扫描式考试评分
• 应答组分诊
• 在写任何成绩之前，都要经过明确的人工批准

在本地安装技能

mkdir -p /tmp/gradescope-mcp/skills
ln -s "$(pwd)/skills/gradescope-assisted-grading" /tmp/gradescope-mcp/skills/gradescope-assisted-grading

如果您喜欢复制：

mkdir -p /tmp/gradescope-mcp/skills
cp -R skills/gradescope-assisted-grading /tmp/gradescope-mcp/skills/

验证安装

ls /tmp/gradescope-mcp/skills/gradescope-assisted-grading
cat /tmp/gradescope-mcp/skills/gradescope-assisted-grading/SKILL.md

使用以下命令从客户端调用它：

• Use the gradescope-assisted-grading skill
• $gradescope-assisted-grading

项目结构

gradescope-mcp/
├── .env.example
├── AGENT.md
├── DEVLOG.md
├── OPERATIONS_LOGS/
│   └── RECORDS.md
├── README.md
├── pyproject.toml
├── skills/
│   └── gradescope-assisted-grading/
│       └── SKILL.md
├── src/
│   └── gradescope_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       ├── auth.py
│       ├── server.py
│       └── tools/
│           ├── __init__.py
│           ├── answer_groups.py
│           ├── assignments.py
│           ├── courses.py
│           ├── extensions.py
│           ├── grading.py
│           ├── grading_ops.py
│           ├── grading_workflow.py
│           ├── regrades.py
│           ├── safety.py
│           ├── statistics.py
│           └── submissions.py
└── tests/
    ├── test_answer_groups.py
    ├── test_assignments_and_grading_ops.py
    ├── test_extensions_and_answer_key.py
    ├── test_grading_workflow.py
    └── test_write_safety.py

开发说明

• AGENT.md 总结了当前的架构和维护期望
• DEVLOG.md 记录实施历史
• OPERATIONS_LOGS/RECORDS.md 是真实账户的突变日志模板

测试

已知警告

1. 成绩范围行为因作业类型而异；几个工具依赖于

HTML解析或反向工程端点。

1. 名册解析使用自定义解析器，因为上游库解析器

存在部分时不可靠。

1. 某些分配类型不支持扩展API，即使对于员工用户也是如此。
2. 扫描作业通常不提供结构化的答案。
3. 问题评分需要问题提交ID，而不是分配级别全局

提交ID。