字段	类型	必填	说明
student_id	string	是	学生学号或 ID
points	number	是	积分值（正数为加分，负数为扣分）
reason	string	否	操作理由
category	string	否	理由分类

请求示例：

curl -X POST http://localhost:3000/api/add_score \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "student_id": "2025001",
    "points": 5,
    "reason": "积极回答问题",
    "category": "课堂表现"
  }'

响应示例（成功）：

{
  "success": true,
  "data": {
    "record_id": "rec_123456",
    "student_id": "2025001",
    "student_name": "张三",
    "points": 5,
    "total_points": 87,
    "reason": "积极回答问题",
    "timestamp": "2026-03-29T14:35:00+08:00"
  }
}

响应示例（失败）：

{
  "success": false,
  "error": "STUDENT_NOT_FOUND",
  "message": "未找到学号为 2025001 的学生"
}

2.2 获取学生列表 `GET /api/list_students`

获取班级中的所有学生信息。

查询参数：

字段	类型	必填	说明
group	string	否	按小组筛选
keyword	string	否	按姓名或学号搜索

请求示例：

curl -X GET "http://localhost:3000/api/list_students?keyword=张三" \
  -H "X-API-Key: your-api-key"

响应示例：

{
  "success": true,
  "data": {
    "total": 1,
    "students": [
      {
        "id": "2025001",
        "name": "张三",
        "group": "第一组",
        "total_points": 87,
        "rank": 3
      }
    ]
  }
}

2.3 获取学生详情 `GET /api/student/:id`

获取单个学生的详细信息和积分记录。

路径参数：

字段	类型	必填	说明
id	string	是	学生学号或 ID

请求示例：

curl -X GET "http://localhost:3000/api/student/2025001" \
  -H "X-API-Key: your-api-key"

响应示例：

{
  "success": true,
  "data": {
    "id": "2025001",
    "name": "张三",
    "group": "第一组",
    "total_points": 87,
    "rank": 3,
    "records": [
      {
        "id": "rec_123456",
        "points": 5,
        "reason": "积极回答问题",
        "timestamp": "2026-03-29T14:35:00+08:00"
      }
    ]
  }
}

2.4 获取排行榜 `GET /api/leaderboard`

获取班级积分排行榜。

查询参数：

字段	类型	必填	说明
limit	number	否	返回数量上限（默认 10，最大 50）
group	string	否	按小组筛选

请求示例：

curl -X GET "http://localhost:3000/api/leaderboard?limit=5" \
  -H "X-API-Key: your-api-key"

响应示例：

{
  "success": true,
  "data": {
    "total_students": 45,
    "leaderboard": [
      {
        "rank": 1,
        "id": "2025015",
        "name": "李四",
        "group": "第二组",
        "total_points": 125
      },
      {
        "rank": 2,
        "id": "2025008",
        "name": "王五",
        "group": "第一组",
        "total_points": 112
      }
    ]
  }
}

2.5 获取理由列表 `GET /api/list_reasons`

获取预设的积分操作理由列表。

查询参数：

字段	类型	必填	说明
category	string	否	按分类筛选
type	string	否	按类型筛选（`positive`/`negative`）

请求示例：

curl -X GET "http://localhost:3000/api/list_reasons?type=positive" \
  -H "X-API-Key: your-api-key"

响应示例：

{
  "success": true,
  "data": {
    "reasons": [
      {
        "id": "reason_1",
        "title": "积极回答问题",
        "points": 5,
        "category": "课堂表现",
        "type": "positive"
      },
      {
        "id": "reason_2",
        "title": "作业完成优秀",
        "points": 10,
        "category": "作业表现",
        "type": "positive"
      }
    ]
  }
}

2.6 健康检查 `GET /api/health`

检查 MCP 服务是否正常运行。

请求示例：

curl -X GET "http://localhost:3000/api/health"

响应示例：

{
  "status": "healthy",
  "version": "1.2.0",
  "timestamp": "2026-03-29T14:40:00+08:00"
}

3. 认证与安全

3.1 API 密钥认证

所有 API 请求必须在请求头中携带 API 密钥：

X-API-Key: your-api-key

未提供或提供错误的 API 密钥将返回 401 Unauthorized：

{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "无效的 API 密钥"
}

3.2 密钥管理

API 密钥在系统设置中生成，可随时重置
建议为不同客户端使用不同密钥（如未来版本支持多密钥）
密钥应妥善保管，不要在公开场合泄露

3.3 网络访问限制

MCP HTTP 服务仅监听 localhost（127.0.0.1）
默认情况下，外部网络无法直接访问
如需远程访问，建议使用反向代理并配置 HTTPS

3.4 操作日志

所有通过 MCP API 执行的操作都会记录在 SecScore 的操作日志中，包括：

操作时间
操作类型（add_score 等）
操作用户（API 密钥标识）
操作结果

4. AI 助手集成示例

4.1 Claude Desktop 配置

在 Claude Desktop 的 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "secscore": {
      "command": "curl",
      "args": [
        "-X", "POST",
        "-H", "Content-Type: application/json",
        "-H", "X-API-Key: your-api-key",
        "http://localhost:3000/api/add_score",
        "-d"
      ]
    }
  }
}

注：实际配置方式取决于 MCP 客户端类型，上述仅为示例。

4.2 Cursor 编辑器集成

在 Cursor 的 MCP 设置中添加 HTTP 服务端点：

Endpoint: http://localhost:3000
API Key: your-api-key

4.3 使用场景示例

场景一：课堂实时评分

用户：给刚才回答问题的张三加 5 分
AI：已为学生张三（学号 2025001）添加 5 分，当前总分 87 分。

场景二：查询学生表现

用户：帮我看看李四这周的积分情况
AI：李四（学号 2025015）当前积分 125 分，排名班级第 1。
本周积分记录：
- 周一：作业完成优秀 +10
- 周二：帮助同学 +5
- 周三：课堂表现积极 +5

场景三：批量操作

用户：给第一组的所有同学各加 2 分参与分
AI：已为第一组的 12 名学生各添加 2 分，共计 24 分。

5. 错误代码参考

错误代码	说明	处理建议
`UNAUTHORIZED`	API 密钥无效或缺失	检查请求头中的 `X-API-Key`
`STUDENT_NOT_FOUND`	学生不存在	确认学号正确，或使用搜索接口查找
`INVALID_POINTS`	积分值无效	检查 points 字段是否为数字
`REQUIRED_FIELD_MISSING`	缺少必填字段	检查请求参数是否完整
`SERVICE_UNAVAILABLE`	服务暂时不可用	检查 SecScore 是否运行，MCP 服务是否启用
`RATE_LIMITED`	请求过于频繁	降低请求频率