Skills Master MCP Server（本地 stdio）

让 Claude Code、Cursor、Claude Desktop 等 AI Agent 通过 MCP 调用 Skills Master 的推理能力。 服务运行在用户本机，是公网 /v1 API 的客户端：它在本机读取输入文件、自动完成预签名上传， 提交任务、等待完成，并把结果下载到本地目录。

准备 key

在账户页「API 密钥 → 附加密钥」创建专用 key。任何 key 都可调用全部 mode，建议：

• 设置 PT 消费上限与有效期；

• 不要使用账户默认 key。key 写进 Agent 配置文件后容易泄露，泄露时可在账户页单独吊销。

Related MCP server: Jungle Grid MCP Server

配置

Claude Code 示例（需要 Node.js 18.17 或更高版本，npx 会自动下载本包）：

claude mcp add skillsmaster \
  -e SKILLSMASTER_API_KEY=<附加 key> \
  -e SKILLSMASTER_MCP_ROOTS="$PWD" \
  -- npx -y @skillsmaster/mcp-server

全局安装后也可以直接使用命令 skillsmaster-mcp：npm install -g @skillsmaster/mcp-server。

工具

行为边界

• 路径限制：所有输入与输出路径在解析符号链接后必须位于 SKILLSMASTER_MCP_ROOTS 内，否则返回 path_outside_workspace，且不发出任何请求。

• 幂等：每次 submit_run 生成新的 Idempotency-Key；遇到 502/503/504 或网络错误时用同一个 key 重试， 服务端返回原任务，不会重复创建或计费。返回值中的 idempotency_key 只用于恢复同一次提交。

• 账户排队：同一账户同一时间只运行一个任务。上一任务未结算时 submit_run 按服务端建议的间隔等待并用同一 Idempotency-Key 重新提交，最长等待 queue_wait_seconds（默认 50，最大 600），期间推送进度；超时返回 account_busy 错误，可稍后再调用。多个进程共用一把 key 时同样安全。

• 错误：API 拒绝以工具错误返回 { error, status, detail }，例如 key_budget_exceeded； 429 附带 retry_after_seconds。

• 计费：结果交付时按实际能耗结算，download_result 返回本次 billing。

• 授权声明：digital_human 的 avatar_rights_confirmed 等声明参数须由用户在对话中明确确认，工具不会代填。

远程端点与 upload 命令

不能在本机运行本包的客户端可以直接连接服务端的远程 MCP 端点（Streamable HTTP），用 X-Customer-Key 鉴权：

claude mcp add --transport http skillsmaster https://api.skillsmaster.net/mcp \
  --header "X-Customer-Key: <附加 key>"

远程端点的工具与本地版相同，只有两点区别：

• submit_run 不接受本地路径，文件改用 input_objects 传入已上传对象的 id；

• 用 get_result 取得结果的预签名下载地址，代替 download_result。

文件先用本包的 upload 命令上传，id 要在 15 分钟内引用，过期后自动删除：

SKILLSMASTER_API_KEY=<附加 key> npx -y @skillsmaster/mcp-server upload photo.png mask.png
# [{ "file": "photo.png", "input_object_id": "…", "expires_at": "…" }, …]

任务完成后，用 download 命令把结果保存到本地；同名文件不覆盖，并输出本次计费：

SKILLSMASTER_API_KEY=<附加 key> npx -y @skillsmaster/mcp-server download <run_id> -o results/
# { "run_id": "…", "path": "results/<run_id>.png", "bytes": …, "billing": { … } }

upload 与 download 由用户直接执行，不受 SKILLSMASTER_MCP_ROOTS 限制；每次上传都生成新的 id，不会覆盖已有对象。

开发

npm ci
npm test      # tsc 编译后用 node:test 运行，HTTP 全部为模拟

发布（维护者）

发布约定

前提

• npm 账号已开启 2FA，并且是组织 skillsmaster 的 owner。组织至少保留两名 owner；交接时先加新 owner， 再移除旧 owner，不需要转移账号。npm 的 2FA 现在使用安全密钥（Passkey）：命令行发布时会给出一个链接， 在注册了 Passkey 的浏览器中确认即可，不需要输入 6 位一次性密码。

• 本机发布使用 Node 18.17 以上即可；CI 中的 Trusted Publishing 需要 npm ≥ 11.5.1，workflow 因此使用 Node 24。

Trusted Publisher 配置（只做一次）

0.1.0 已由维护者在本机手动发布。在 npmjs.com 打开包页面 → Settings：

1. Trusted Publisher 选 GitHub Actions：Organization jaisol-inc、Repository skillsmaster-mcp、 Workflow filename publish.yml（必须带扩展名），Environment 留空。

2. 确认 workflow 能发布后，在 Publishing access 选择要求 2FA 且禁止 token 发布。

需要在本机手动发布时（例如 Trusted Publisher 不可用），在干净的检出上执行，避免把未提交的改动打进包里：

git status --short                 # 必须没有输出
npm login && npm whoami            # 确认是组织 owner 账号
npm ci
npm publish --dry-run              # 核对包名、版本、文件清单（应只有 dist/src、README.md、LICENSE、package.json）
npm publish                        # 按提示在浏览器中用 Passkey 确认

本机发布不要加 --provenance：provenance 只能在受支持的 CI 中生成。

日常发布

1. 按语义化版本修改版本号：只修 bug 用 patch，新增工具或参数用 minor，删除工具、改参数含义或改命令用法用 major （0.x 期间 minor 也可以包含不兼容变更，但要在 PR 中写明）。

   npm version patch --no-git-tag-version   # 只改 package.json 与 package-lock.json，不打 tag

2. 提交、建 PR、合并到 main。

3. 在合并后的提交上打 tag 并推送，tag 必须与 version 完全一致，否则 workflow 会失败：

   git switch main && git pull
   git tag v$(node -p "require('./package.json').version")
   git push origin v$(node -p "require('./package.json').version")

4. 在 GitHub Actions 中查看 Publish 运行结果。

发布后验证

npm view @skillsmaster/mcp-server version dist-tags    # 新版本已出现，latest 指向它
npx -y @skillsmaster/mcp-server@<version> download     # 能下载并运行，打印用法说明即正常

新发布的包可能需要几分钟处理才能被查询到（期间 npm view 返回 404）。再用附加 key 按「配置」一节接入 Claude Code，调用一次 get_account；npm 包页面应显示来自本仓库 workflow 的 provenance。

注意事项

• 版本号不能重复使用：发布过的版本即使撤回也不能再发同一个号。发现问题时发布新的 patch 版本，并用 npm deprecate @skillsmaster/mcp-server@<version> "<原因>" 标记有问题的版本；npm unpublish 只在发布后 72 小时内、且没有其他包依赖时可用，撤回后该版本号仍不可再用。

• scoped 包默认是私有发布：publishConfig.access: public 不能删，否则发布会因组织没有付费私有包而失败。

• npx 要写完整包名：npx skillsmaster-mcp 会去 npm 下载另一个名为 skillsmaster-mcp 的包；正确写法是 npx -y @skillsmaster/mcp-server [upload|download …]。只有全局安装后才能直接用 skillsmaster-mcp 命令。

• provenance 要求公开仓库：npm 只为公开源码仓库生成 provenance。本仓库若改为私有，必须同时去掉 workflow 中的 --provenance，否则发布会被拒绝。

• tag 推错了：在 workflow 发布成功前，可以删除远端 tag（git push origin :refs/tags/v<version>）后重推； 一旦发布成功，就只能发布新版本。

• 改名要同步配置：重命名 workflow 文件、迁移仓库或修改组织名后，必须同步更新 npmjs.com 上的 Trusted Publisher，否则 OIDC 校验不通过，发布会失败。

• 改命令用法要同步平台：Skills Master 远程 MCP 端点的工具描述会向模型推荐 npx -y @skillsmaster/mcp-server upload/download；修改命令名或参数后，要通知平台同步更新描述。

• 测试脚本要兼容新版 Node：Node 22 起 node --test <目录> 会把目录当成模块加载而失败，测试脚本因此写成 node --test dist/test/*.test.js；CI 在 Node 20、22、24 上运行。

• npm pack 不会编译：dist/ 不在 git 中，prepublishOnly 只在 npm publish（含 --dry-run）时执行； 直接 npm pack 前要先 npm run build，否则打出的包里没有代码。

• 发布前自查包内容：除了 npm publish --dry-run，可以 npm run build && npm pack 后把 tarball 安装到空目录， 确认 skillsmaster-mcp 命令和 stdio 握手正常，避免漏发文件。