MidooLearn Studio

Agent 接入

把 midoo Learn Studio 接入你的 Agent：通过 MCP 服务，Claude Code、Claude 桌面版、Cursor 等可以直接调用工具创建计划、搜索社区并保存到 midoo 账号。格式与 midoo App 原生计划一致，导入后可以继续在 Studio 中对话修改。

  1. 创建访问令牌

    令牌代表你的账号，只在创建时显示一次。不用时随时撤销。

    权限（只勾选 Agent 需要的）

  2. 连接 MCP 服务

    服务地址 https://test-studio.midooai.cn/api/mcp（Streamable HTTP）。把令牌放进环境变量 MIDOO_TOKEN，再按你的客户端添加：

    claude mcp add --transport http midoo-studio https://test-studio.midooai.cn/api/mcp \
  --header "Authorization: Bearer $MIDOO_TOKEN"
    {
  "mcpServers": {
    "midoo-studio": {
      "type": "http",
      "url": "https://test-studio.midooai.cn/api/mcp",
      "headers": {
        "Authorization": "Bearer ${MIDOO_TOKEN}"
      }
    }
  }
}

    可用工具：创建与校验计划、读取我的计划、添加到 midoo、分享到社区、搜索/收藏社区计划。Agent 只能看到令牌权限允许的工具。

  3. 或者：把说明交给不支持 MCP 的 Agent

    复制下面这段话，粘贴到 ChatGPT、Claude Code 等 Agent 中，并告诉它你的令牌。

    你可以帮我在 midoo AI Learn Studio 创建语言学习计划，并保存到我的 midoo 账号。

接口地址：https://test-studio.midooai.cn/api/agent/v1
认证：请求头 Authorization: Bearer <我的访问令牌>
格式说明：GET https://test-studio.midooai.cn/api/agent/v1/schema（JSON Schema 和完整示例，无需令牌）

步骤：
1. 先问清我的学习语言、当前水平（CEFR A0–C2）、目标场景、周期和每天可学时间。
2. 按 schema 写出计划 JSON：require_profile 描述学习者，plan.stages[].day_lessons[].lessons[] 是课时。
   每节课的 lesson_desc 写清学习步骤，并在末尾附 ```yaml 代码块列出 topic_kps 知识点
   （knowledge_id、pattern、pattern_trans 中文翻译、level、function、chunks、examples）。
3. POST https://test-studio.midooai.cn/api/agent/v1/plans/validate 校验，按返回的 errors 修正，warnings 尽量处理。
4. POST https://test-studio.midooai.cn/api/agent/v1/plans 导入；如果我同意，加 ?add_to_midoo=true 直接保存到 midoo。
5. 把返回的 studioUrl 发给我，我可以在 Studio 里预览和继续修改。
也可以：GET /community?q= 搜索社区计划，POST /community/{id}/add-to-midoo 添加，POST /community/{id}/bookmark 收藏。

    支持读取网页的 Agent 也可以直接读取 https://test-studio.midooai.cn/llms.txt。

  4. 校验并导入

    导入后返回 Studio 链接。校验接口会指出具体字段的问题，适合让 Agent 自行修正。

    # 校验（无需令牌）
curl -X POST https://test-studio.midooai.cn/api/agent/v1/plans/validate \
  -H 'Content-Type: application/json' -d @plan.json

# 导入并保存到 midoo
curl -X POST 'https://test-studio.midooai.cn/api/agent/v1/plans?add_to_midoo=true' \
  -H 'Authorization: Bearer $MIDOO_TOKEN' \
  -H 'Content-Type: application/json' -d @plan.json

安全

  • 令牌只在创建时显示一次，服务端只保存哈希；可随时撤销，最长有效期 1 年。
  • 按权限范围授权：未勾选的能力，Agent 既看不到对应工具，也无法调用。
  • 每个令牌独立限流（每小时 300 次调用、60 次写操作），每次调用都有审计记录。
  • 只接受服务端或命令行发起的请求；来自其他网站的浏览器请求会被拒绝。
  • Agent 只能访问令牌所属账号自己的计划，添加到 midoo 使用你最近一次登录的会话。

HTTP 接口

方法路径说明
GET/api/agent/v1/schema计划格式 JSON Schema 与完整示例（无需令牌）
POST/api/agent/v1/plans/validate校验计划，返回错误、提示和统计（无需令牌）
GET/api/agent/v1/me当前令牌对应的账号
POST/api/agent/v1/plans导入计划到 Studio；加 ?add_to_midoo=true 同时保存到 midoo
GET/api/agent/v1/plans列出我的计划
GET/api/agent/v1/plans/{id}读取计划当前版本（原生格式）
POST/api/agent/v1/plans/{id}/add-to-midoo把计划保存到 midoo 账号
POST/api/agent/v1/plans/{id}/publish分享到社区
GET/api/agent/v1/community?q=&language=&sort=搜索社区计划
GET/api/agent/v1/community/{id}社区计划详情
POST/api/agent/v1/community/{id}/bookmark收藏（DELETE 取消）
POST/api/agent/v1/community/{id}/add-to-midoo把社区计划保存到 midoo 账号

计划格式

require_profile
学习者：learn_lan 学习语言（en、ja、ko、es、fr、de 等），teaching_lan 讲解语言，current_level 水平（A0–C2），background_goal 背景与目标。
plan.name / analyst
计划标题与说明。
plan.stages[]
1–12 个阶段：stage_title、stage_desc、stage_time，以及 1–60 个主题 day_lessons。
day_lessons[].lessons[]
每个主题 1–20 节课：lesson_title 与 lesson_desc。lesson_desc 末尾的 yaml 代码块 topic_kps 是 App 展示的知识点。
{
  "require_profile": {
    "learn_lan": "ja",
    "teaching_lan": "zh-Hans",
    "background_goal": "下个月去大阪旅行，想自己点餐和问路",
    "current_level": "A0",
    "other": ""
  },
  "plan": {
    "name": "大阪旅行日语：点餐与问路",
    "analyst": "零基础，两周内掌握旅行中最常用的点餐和问路表达。",
    "stages": [
      {
        "stage_title": "在餐厅点餐",
        "stage_desc": "能看懂菜单、点餐并结账。",
        "stage_time": "第1周",
        "day_lessons": [
          {
            "day_lesson_title": "进店与点餐",
            "lessons": [
              {
                "lesson_title": "说出想要的菜",
                "lesson_desc": "1. 作为顾客告诉店员想要哪道菜。2. 说明数量。\n知识点：\n```yaml\ntopic_kps:\n  - topic_id: 1\n    topic_key: ordering\n    knowledge_points:\n      - knowledge_id: kp-1\n        pattern: これを ___ ください。\n        pattern_trans: 请给我___这个。\n        level: A0\n        function: speaking\n        chunks: [一つ, 二つ]\n        examples:\n          - これを一つください。\n```"
              }
            ]
          }
        ]
      }
    ]
  }
}

完整 JSON Schema：/api/agent/v1/schema。保存到 midoo 使用你最近一次手机号登录的账号会话，超过 7 天未登录时需要重新登录。