StudySolo Wiki

MCP(studysolo-mcp)

在 Claude Desktop、Cursor 等 MCP Host 中通过 studysolo-mcp 使用 Personal Access Token 调用 StudySolo:账户与用量、工作流与画布编辑、启动与监控运行。

最后更新:2026-10-05

MCP(studysolo-mcp)

StudySolo 提供官方 Model Context Protocol 服务器 studysolo-mcp:由 MCP Host 在本地启动子进程,通过 stdio(标准输入输出)与 Host 交换 JSON-RPC;服务端再使用 HTTPS + Authorization: Bearer 访问 StudySolo 后端。

传输方式:当前仅支持 stdio,不提供 HTTP/SSE 形态的 MCP 端点。

前置条件

  1. 已安装 Python 环境,并可执行包入口 studysolo-mcp(开发克隆仓库后通常使用 pip install -e packages/mcp-server)。
  2. 在 StudySolo 前端 设置 → 开发者 / API Token 创建 Personal Access Token(PAT),前缀一般为 sk_studysolo_。明文仅在创建成功时返回一次。
  3. 若连接自建后端,准备后端根地址(例如 http://127.0.0.1:2038);否则使用你环境对应的线上 API 基址。

环境变量

变量说明
STUDYSOLO_TOKENPAT,必填(除非你的 Host 以其他方式注入等价配置)。
STUDYSOLO_API_BASEAPI 根 URL,默认随部署而定;自建时请指向实际 FastAPI 地址。

安全:不要把 PAT 粘贴到聊天、Issue 或仓库中;只放在 Host 配置文件或本机环境变量里。

Claude Desktop 配置示例

编辑 macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json,或 Windows 上的 %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "studysolo": {
      "command": "studysolo-mcp",
      "env": {
        "STUDYSOLO_API_BASE": "http://127.0.0.1:2038",
        "STUDYSOLO_TOKEN": "sk_studysolo_你的令牌"
      }
    }
  }
}

Cursor 配置示例

在仓库或本机的 MCP 配置(例如 .cursor/mcp.json)中增加同名块,字段与上表一致:command 为 studysolo-mcp,env 中填写 STUDYSOLO_API_BASE 与 STUDYSOLO_TOKEN。

工具一览(与当前服务端实现一致)

下列 20 个工具在 studysolo-mcp 中注册(按用途分组,以 packages/mcp-server/src/studysolo_mcp/server.py 的 _HANDLERS 为准)。失败时工具结果会带结构化错误对象(如 HTTP 状态码与 message),便于模型与用户排查。

包还没有发布到 PyPI。在本仓库执行 pip install -e packages/mcp-server 之后,命令 studysolo-mcp 才会出现在 PATH 里。服务只有 stdio,没有 HTTP / SSE 形态的 MCP 端点。

账户与额度

工具说明
get_me当前账户基础信息(如邮箱、会员 tier)。
get_quota工作流与执行相关配额。

AI 使用数据

工具说明
get_usage_overview指定时间窗口内的调用总览。
get_usage_timeseries按时间桶聚合的用量序列。
get_usage_live最近一段时间的实时用量快照。

工作流清单与节点目录

工具说明
list_workflows工作流列表。
get_workflow指定工作流内容/画布元信息(节点与边摘要,具体字段以后端为准)。
get_nodes_manifest可配置的节点类型及字段说明(编辑画布前应先查阅)。

画布(真实节点与边)

以下工具操作的是持久化在 nodes_json / edges_json 中的 真实 React Flow 实例,而不是仅显示名称或标签:

工具说明
create_workflow创建空工作流,返回 workflow_id 等。
get_workflow_canvas读取完整画布 JSON 与 updated_at(并发修改时用于 base_updated_at)。
get_workflow_node读取单个节点及其入边/出边。
apply_workflow_canvas_patch批量创建/更新/删除节点与边;复杂变更建议先 dry_run=true。
validate_workflow_canvas校验当前画布或拟议操作(未知节点类型、断边、环等)。
get_node_config_options读取某节点类型某配置字段的动态可选项(如知识库列表)。

重要语义:

  • node_type 来自 get_nodes_manifest,表示可执行节点类型;label 仅为展示文案,不能代替节点实例。
  • 复杂编辑请 先 dry_run=true 预览,再 dry_run=false 提交;非 ASCII 的文案与 JSON 配置按 UTF-8 传递。

子智能体

工具说明
list_agents列出进程内的 5 个子智能体:study-tutor、visual-site、code-review、news、deep-research。
run_agent调用 POST /api/agents/{agent}/chat。按量计费。CLI 没有对应命令。

运行(Run API v2)

工具说明
start_workflow_run异步启动一次运行,返回 run_id。
get_run_progress聚合进度(阶段、完成度等)。
get_run_events节点级事件增量;轮询时应使用返回的 next_seq 作为 after_seq,直到 is_terminal。
run_workflow_and_wait组合「启动 + 轮询/流式等待 + 终态」的端到端工具;mode 可选 stream(高频事件)与 poll(按间隔看进度)。

stdio 与「流式」:MCP stdio 本身不是浏览器 SSE;mode="stream" 在实现上通过短间隔轮询 /events 模拟流式输出。浏览器内仍可使用既有 SSE 执行接口。

典型调用顺序

仅查询「我是谁、还剩多少额度」
get_me → get_quota。

列出并确认工作流后执行
list_workflows → get_workflow(确认触发与输入)→ run_workflow_and_wait 或 start_workflow_run + 自行轮询 get_run_progress / get_run_events。

用 MCP 改画布
get_nodes_manifest →(若无 id)create_workflow → get_workflow_canvas → apply_workflow_canvas_patch(先 dry run)→ 再读 get_workflow_canvas 确认 → 需要时再 run_workflow_and_wait。

错误与排查

现象建议
401 / 认证失败检查 PAT 是否过期、是否在前端被撤销;更新 Host 配置中的 STUDYSOLO_TOKEN。
403 与模型/会员相关文案工作流中某节点模型超出当前会员等级,需升级或更换模型。
429触发频率或日配额限制,稍后重试或调整用量。
事件重复或遗漏确认 get_run_events 始终传入上次响应的 after_seq。

更完整的 PAT 生命周期、Run API 路径与安全边界见仓库内《MCP 与 CLI 功能流程》与《API 规范》文档;本页面向 Wiki 读者保持与当前 studysolo-mcp 实现一致。