# 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 配置文件后容易泄露，泄露时可在账户页单独吊销。

## 配置

| 环境变量 | 必填 | 说明 |
|---|---|---|
| `SKILLSMASTER_API_KEY` | 是 | 附加 key，作为 `X-Customer-Key` 只发送到 API 源，不会发给存储签名地址 |
| `SKILLSMASTER_API_URL` | 否 | 默认 `https://api.skillsmaster.net`；非 localhost 必须是 https |
| `SKILLSMASTER_MCP_ROOTS` | 否 | 允许读写的目录，按系统路径分隔符（Linux/macOS 为 `:`）分隔；默认是启动目录 |
| `SKILLSMASTER_MCP_OUTPUT_DIR` | 否 | 结果默认保存目录，默认 `<第一个 root>/skillsmaster-results`，必须位于 roots 内 |

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

```bash
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`。

## 工具

| 工具 | 作用 |
|---|---|
| `list_modes` | 列出可用 mode；传 `mode` 返回该 mode 的完整参数 JSON Schema、输入限制与计费口径 |
| `submit_run` | `files` 填本地路径（主输入字段为 `file`），自动上传后提交；文本放在 `params.input_text`。立即返回 `run_id` |
| `get_run` | 查询状态、排队位置与计费；`wait_seconds`（≤50）会在期间轮询并推送进度 |
| `download_result` | 把成功结果保存到本地并返回路径；同名文件不覆盖，自动加 `-1`、`-2` 后缀 |
| `cancel_run` | 取消仍在排队的任务，不收费；已开始的任务返回 `run_not_cancellable` |
| `get_account` | 查询余额、欠费状态与各 key 的消费上限和剩余额度 |

## 行为边界

- **路径限制**：所有输入与输出路径在解析符号链接后必须位于 `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` 鉴权：

```bash
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 分钟内引用，过期后自动删除：

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

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

```bash
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，不会覆盖已有对象。

## 开发

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

## 发布（维护者）

### 发布约定

| 项目 | 约定 |
|---|---|
| 包名 / 组织 | `@skillsmaster/mcp-server`，npm 组织 `skillsmaster`（以产品命名，不绑定个人或公司账号） |
| 可见性 / 许可 | 公开，MIT（`LICENSE`，版权方ジャイソル株式会社）；`publishConfig.access: public` 已设置 |
| 发布内容 | 只发布 `files` 白名单：`dist/src`、`README.md`、`LICENSE`（`package.json` 自动包含） |
| 版本号 | 以 `package.json` 的 `version` 为唯一来源，MCP 服务上报的 `serverInfo.version` 也从中读取 |
| 构建 | `prepublishOnly` 先清空 `dist/` 再编译和测试，已从 `src/` 删除的文件不会残留在发布包里 |
| 日常发布 | 推送 tag `v<version>`，由 `.github/workflows/publish.yml` 通过 Trusted Publishing（OIDC）发布并附带 provenance |

### 前提

- 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 不可用），在干净的检出上执行，避免把未提交的改动打进包里：

```bash
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 中写明）。

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

2. 提交、建 PR、合并到 `main`。
3. 在合并后的提交上打 tag 并推送，tag 必须与 `version` 完全一致，否则 workflow 会失败：

   ```bash
   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** 运行结果。

### 发布后验证

```bash
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 握手正常，避免漏发文件。