educoder-skill/SKILL.md

name	description
educoder-skill	提供 Educoder 用户与课堂相关查询能力，当前支持用户基本信息、课堂列表、课堂作业列表、作业学生列表、课堂考试列表、考试学生列表查询。

MCP 服务地址

• 线上地址：http://47.98.32.66:48000/mcp
• 本地开发：http://localhost:8001/mcp

使用 streamable-http 模式连接，不使用 SSE。

接入方式

• 客户端应使用 streamable-http MCP 客户端
• 使用 OpenClaw 安装本 skill 时，MCP 服务地址直接填写线上地址：http://47.98.32.66:48000/mcp
• 不要使用 sse_client
• 本地开发端口默认是 8001，线上端口使用 48000
• MCP 路径默认是 /mcp

安装完成提示

安装完成后，面向用户只介绍当前 skill 提供的功能，不展示 MCP 地址、配置文件路径、token 保存方式、headers 规则等接入细节。

推荐展示文案：

Educoder skill 已安装完成。当前支持查询：
- 当前用户基本信息
- 当前用户的课堂列表
- 课堂中的作业列表
- 某次作业下的学生列表
- 课堂中的考试列表
- 某场考试下的学生列表

前置配置

接入 OpenClaw 时，使用单用户 Authorization token。第一次安装 skill 时，把 MCP 服务地址和 token 一起写到固定的 OpenClaw MCP 配置文件；后续调用 MCP 时，从该配置文件读取 token 并放到请求头里。

Authorization 配置

配置文件路径必须固定为：

.openclaw/educoder-skill/.mcp.json

安装 skill 时写入 MCP 服务地址，并将用户输入的EDUCODER_AUTHORIZATION token写入该配置文件。

MCP 配置示例：

{
  "educoder-mcp": {
    "url": "http://47.98.32.66:48000/mcp",
    "transport": "streamable-http",
    "headers": {
      "Authorization": "xxxxx"
    }
  }
}

Authorization 的值直接写 token 原文，不要写成 Bearer xxxxx。不要把 token 放到工具参数里。

后续调用 MCP 时，从 MCP 配置读取 headers.Authorization 并注入请求头：

mcp_config = openclaw_mcp_config.get("educoder-mcp")
token = mcp_config["headers"]["Authorization"]

headers = {
    "Authorization": token
}

Authorization 的 header 值直接传 token 原文，不要拼接 Bearer 前缀。例如：

Authorization: xxxxx

不要传成：

Authorization: Bearer xxxxx

创建 MCP 连接时透传：

async with streamable_http_client(self.server_url, headers=headers or None) as (read, write, _):
    yield read, write

Authorization 走 MCP 连接层请求头，不放在工具参数里。

单用户 Token

当前 skill 使用单用户 token。安装后不需要每个会话重复输入 token；每次调用 MCP 时读取配置里的 headers.Authorization 即可。

401 Token 过期处理

如果调用 MCP 工具或后端接口时返回 401 Unauthorized，说明当前 token 已过期或无效。

处理流程：

1. 停止继续使用当前 token 重试
2. 提示用户重新输入新的 Authorization
3. 将用户输入的新 token 写入 MCP 配置文件中的 headers.Authorization
4. 重新创建 MCP 连接，并从 MCP 配置读取最新 token
5. 使用新 token 重新发起本次工具调用

示例提示：

当前 Educoder 授权已过期，请重新输入 Authorization token。

更新 token 后必须重新建立 MCP 连接，不能复用已经携带旧 headers 的连接。

OpenClaw 接入建议

如果使用 OpenClaw，推荐按下面的方式接入：

1. 安装 skill 时，MCP 服务地址填写：http://47.98.32.66:48000/mcp
2. 安装 skill 时，要求用户输入 Educoder Authorization token
3. OpenClaw 将 MCP 地址和 token 写入 MCP 配置文件，其中 token 放到 headers.Authorization
4. 当前用户发起工具调用时，后端创建 MCPClient
5. MCPClient 建连时从 MCP 配置读取 token
6. MCPClient 把读取到的 token 原文放进 MCP headers，不要添加 Bearer 前缀
7. 如果调用返回 401 Unauthorized，提示用户重新输入 token，更新 MCP 配置后重新建连并重试

参考流程：

tool_server_url = "http://47.98.32.66:48000/mcp"

mcp_config = openclaw_mcp_config.get("educoder-mcp")
token = mcp_config["headers"]["Authorization"]

client = MCPClient(mcp_config=mcp_config, authorization=token)

tool_result = await client.call_tool(tool_name, tool_arguments)

MCPClient 示例：

class MCPClient:
    def __init__(self, mcp_config: dict, authorization: str):
        self.server_url = mcp_config["url"]
        self.authorization = authorization

    def _build_headers(self) -> dict[str, str]:
        headers = {}
        if self.authorization:
            headers["Authorization"] = self.authorization
        return headers

不推荐的做法：

• 让用户在每个会话里重复输入 Authorization
• 把 Authorization 放到工具参数里
• 给 Authorization 自动拼接 Bearer 前缀
• 把 token 写入 OpenClaw .env 后要求用户重启才能生效
• 把 token 写到其他位置，导致新会话读取不到 headers.Authorization

触发场景

意图 → 工具 速查表

用户意图	调用工具
查询当前用户基本信息	educoder_user_info
查询当前用户的课堂列表	educoder_user_course_list
查询某个课堂中的作业列表	educoder_course_homeworks
查询某次作业下的学生列表	educoder_homework_student_works
查询某个课堂中的考试列表	educoder_course_exercises
查询某场考试下的学生列表	educoder_exercise_users

不要触发的情况

• 与课堂、作业、考试数据查询无关的问题
• 需要新增、修改、删除数据的写操作
• 纯闲聊场景

组合调用示例

用户说：“帮我查一下我有哪些课堂，再看看某个课堂里的作业和考试”

依次调用：

1. educoder_user_info
2. educoder_user_course_list
3. educoder_course_homeworks
4. educoder_course_exercises

用户说：“帮我看一下这次作业和这场考试的学生列表”

依次调用：

1. educoder_homework_student_works
2. educoder_exercise_users

---

工具详细说明

全局规则

• 当前工具都是查询类工具，没有写操作
• 调用时必须传入完整的结构化 JSON 参数对象
• 参数名必须严格匹配工具定义
• 当前查询逻辑还是占位实现，后续会接外部 HTTP 接口
• course_id 和 exercise_id 当前按字符串传入
• 客户端每次连接 MCP 服务时，请从 OpenClaw MCP 配置读取 token 原文，并在 transport headers 中传 Authorization，不要添加 Bearer 前缀

---

1. educoder_user_info

获取当前用户基本信息。

参数：

参数	必填	说明
school	否	可选的 school 查询参数

典型问法：

• “查询当前用户信息”
• “我是谁”
• “获取我的基本资料”

---

2. educoder_user_course_list

获取当前用户课堂列表。

参数： 无

典型问法：

• “查询我有哪些课堂”
• “我的课堂列表”
• “获取当前用户的课堂信息”

返回字段：

• status
• message
• data
• size

---

3. educoder_course_homeworks

获取课堂中的作业列表。

参数：

参数	必填	说明
course_id	是	课堂 ID

典型问法：

• “查询课堂中的作业列表”
• “这个课堂有哪些作业”
• “帮我看一下课堂作业”

---

4. educoder_homework_student_works

获取某次作业下的学生列表。

参数：

参数	必填	说明
exercise_id	是	作业 ID

典型问法：

• “查询某次作业下的学生列表”
• “这次作业有哪些学生提交了”
• “帮我看一下作业学生情况”

---

5. educoder_course_exercises

获取课堂中的考试列表。

参数：

参数	必填	说明
course_id	是	课堂 ID

典型问法：

• “查询课堂中的考试列表”
• “这个课堂有哪些考试”
• “帮我看一下课堂考试”

---

6. educoder_exercise_users

获取某场考试下的学生列表。

参数：

参数	必填	说明
exercise_id	是	考试 ID

典型问法：

• “查询某场考试下的学生列表”
• “这场考试有哪些学生”
• “帮我看一下考试参与学生”

---

客户端调用示例

import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client


async def main(openclaw_mcp_config):
    mcp_config = openclaw_mcp_config.get("educoder-mcp")
    token = mcp_config["headers"]["Authorization"]

    headers = {
        "Authorization": token
    }

    async with httpx.AsyncClient(headers=headers) as http_client:
        async with streamable_http_client("http://47.98.32.66:48000/mcp", http_client=http_client) as (read, write, _):
            async with ClientSession(read, write) as session:
                await session.initialize()

                tools = await session.list_tools()
                print([tool.name for tool in tools.tools])

                result = await session.call_tool("educoder_user_info", {})
                print(result)

注意事项

• 当前服务使用 streamable-http，不是 SSE
• 如果客户端使用了 sse_client，将无法正常调用当前服务
• 调用接口返回 401 Unauthorized 时，视为 token 过期或无效，应要求用户重新输入 token，并更新 MCP 配置文件中的 headers.Authorization
• 新开会话直接从 MCP 配置文件读取 headers.Authorization
• MCP 配置文件路径固定为 .openclaw/educoder-skill/.mcp.json，不要写入或读取 .openclaw/mcp.json、.openclaw/config/mcp.json
• 当前工具返回空 data 数组属于预期行为，因为外部接口尚未接入
• 后续新增或调整工具时，需要同步更新本文件