# 小工具 MCP 使用指南

`redapp-mcp` 将现有小工具 CLI 暴露为本地 stdio MCP 工具。Agent 调用工具时，服务启动同一 npm 包内的 `redapp` 子进程，复用登录、token 续期、环境隔离、参数校验、文件大小限制和确认哈希。不会调用 PATH 中可能版本不同的全局 `redapp`。

此功能需要包含 `cli/redapp/mcp.mjs` 的版本。仓库改动不代表 npm 已发布；发布前使用下面的本地绝对路径配置。Node.js 18+；dev 需要 20+。使用官方 MCP SDK v1 维护线，以兼容现有 Node.js 18 运行要求和 stdio 客户端。

## 启动与接入

在仓库执行 `npm ci` 后：

```bash
node cli/redapp/mcp.mjs --env prod --source thirdAgent
```

启动后等待 MCP 客户端输入是正常现象，不是卡住。stdout 专用于 JSON-RPC。生产环境默认 `prod`；beta 使用 `--env beta`，不会因接口失败自动切换环境。

支持本地 stdio MCP 的客户端可按其配置格式添加以下服务，例如 Claude Desktop、Cursor、Claude Code 使用的 `mcpServers` 配置：

```json
{
  "mcpServers": {
    "redapp": {
      "command": "node",
      "args": [
        "/absolute/path/to/skill-cli/cli/redapp/mcp.mjs",
        "--env", "prod",
        "--source", "thirdAgent"
      ]
    }
  }
}
```

把仓库路径换成真实绝对路径；桌面客户端找不到 Node 时，将 `command` 换为 Node 可执行文件的绝对路径。客户端接入位置以其自身 MCP 配置界面为准。

Codex 使用 TOML 配置：

```toml
[mcp_servers.redapp]
command = "node"
args = ["/absolute/path/to/skill-cli/cli/redapp/mcp.mjs", "--env", "prod", "--source", "thirdAgent"]
```

包含 MCP 的 npm 版本发布并全局安装后，也可以使用 `redapp-mcp --env prod --source thirdAgent`。这是本地进程服务，不提供 HTTP 地址，也不适用于只接受远程 HTTP MCP 的客户端。

同一服务的环境在启动时固定，工具参数不能切换环境或 API 地址。需要同时使用 beta/prod 时配置两个服务。默认与 CLI 共用 `~/.skillhub-upload`（beta 使用其 beta 子目录）；可在客户端服务环境变量中设置 `SKILLHUB_UPLOAD_HOME`。`SKILLHUB_UPLOAD_API_BASE` 延续 CLI 的覆盖规则，仅用于用户确认的可信网关。不要将 token 写入 MCP 配置或工具参数。

## 可用工具

| MCP 工具 | 用途与主要参数 |
| --- | --- |
| `redapp_list` | 查询列表：`source?`、`pageNum?`、`pageSize?`（最多 100） |
| `redapp_config` | 查询类目/权限：`source?` |
| `redapp_status` | 状态/驳回原因：`appId`、`source?` |
| `redapp_history` | 历史版本：`appId`、`source?`；审核状态 -1 表示历史版本 |
| `redapp_whoami` | 当前环境登录状态，不返回原始 token |
| `redapp_login` | 登录/续期；需要扫码时返回二维码和授权链接 |
| `redapp_logout` | 退出当前环境登录，清除凭证 |
| `redapp_upload` | `file` 绝对路径、`type: pkg/image`、`confirm?` |
| `redapp_preview` | `payload` 对象、`source?`、`confirm?`；执行后返回手机预览二维码 |
| `redapp_submit` | `payload`、`source?`、`confirm?`、`previewJobId?`、`previewApproved?` |
| `redapp_edit` | `payload`、`source?`、`confirm?` |
| `redapp_dev` | `dir` 静态产物绝对路径；不自动打开浏览器，返回本地 URL |
| `redapp_job_status` | `jobId`、`waitMs?`（0–10000，默认 1000） |
| `redapp_job_stop` | `jobId`；停止登录等待、dev 或其他运行中任务 |

`source` 省略时使用启动配置，默认 `thirdAgent`。本地路径是 MCP 服务所在机器的路径。此服务拥有当前用户的本地文件和 CLI 账号权限，请仅接入受信任的 Agent。

## 查询、登录与长任务

查询列表参数：

```json
{"pageNum": 1, "pageSize": 20}
```

工具回执包含 `jobId`、`command`、`environment`、`state`，以及 `result`、`prompt` 或 `progress`。`result` 保留 CLI 的 `RESULT_JSON`；业务错误通过 `isError` 返回，不能将 HTTP 200 当作成功。

- `state=running`：调用 `redapp_job_status` 继续查询，不要重复发起业务操作。
- 出现 `prompt.type=auth_device_code`：必须同时展示登录二维码、`prompt.userCode` 授权码、`authorizeH5Url` 授权链接和 `expiresInSeconds` 有效期，不能只展示图片。MCP 会附带可读文本，适用于主动登录及业务命令触发的自动登录。让用户扫码，或用手机浏览器打开链接并按页面提示使用授权码，保留原任务继续轮询。有效期以提示生成时为准；未返回授权码时如实告知，不用 jobId/deviceCode 代替。
- `state=completed`：读取 `result`；`dry_run` 仅是计划，`submitted` 仅是送审。
- `state=failed`：查看 `result.code/message`，按原始错误排查。
- dev 返回 `result.status=ready` 时可打开其中 URL，任务仍保持 running；用 `redapp_job_stop` 关闭。

为避免登录凭证及写入冲突，一次只运行一个业务任务和一个 dev 任务。任务保存在当前 MCP 会话内，最多保留 100 条，重启或过期后 jobId 失效。退出 MCP 会停止子进程。停止登录等待不等于撤销授权码；再次登录仍复用 CLI 的有效待授权状态。

## 上传、预览与送审

1. 检查素材和表单，读取 `redapp_config` 获取真实类目编码。图片/ZIP 上限 10 MiB，ZIP 解压总量上限 30 MiB；其余限制见 [CLI 文档](redapp-cli.md)。
2. 调用写入工具时不传 `confirm`，只生成 dry-run 计划。向用户说明效果；用户已有明确授权时无需重复询问。
3. 再次调用同一工具，保持参数一致，增加 `confirm: "<result.plan.planHash>"` 执行。账号、环境或文件改变时重新生成计划。首次未登录时先完成登录，再重新生成绑定账号的计划。
4. 上传得到 `fileId`、`md5` 后，调用 `redapp_preview`，先计划再执行。payload 示例：

```json
{
  "appName": "我的小工具",
  "iconFileId": "上传返回的图标ID",
  "version": "1.0.0",
  "pkgFileId": "上传返回的ZIP文件ID",
  "md5": "上传返回的32位MD5"
}
```

5. 展示预览工具回传的 PNG 图片和 URL，让用户扫码体验，必须取得明确的“预览通过”。客户端无法显示图片时，可用返回的 URL 在本地生成并交付二维码；二维码生成失败不能直接送审。
6. 调用 `redapp_submit` 生成计划，payload 示例：

```json
{
  "appName": "我的小工具",
  "slogan": "一句话简介",
  "iconFileId": "上传返回的图标ID",
  "coverFileId": "上传返回的封面ID",
  "version": "1.0.0",
  "pkgFileId": "上传返回的ZIP文件ID",
  "md5": "上传返回的32位MD5",
  "categories": ["config返回的类目编码"],
  "authorizations": []
}
```

新建不填 `appId`；升级已有工具时添加真实 `appId`。执行送审时附上 `confirm`、**成功执行预览的** `previewJobId`（不是 dry-run 任务）、`previewApproved: true`。MCP 会验证本会话预览任务成功，以及来源、包 ID、MD5、版本、名称和图标均一致；不一致必须重新预览。`previewApproved` 是 Agent 对用户反馈的记录，不能自行推定用户已预览。

编辑工具只需 `appId` 加至少一个待修改字段：`appName/slogan/iconFileId/coverFileId`。未修改字段省略并保留原值；不能传 null 或空白。只改名的 payload 例如 `{"appId":"真实ID","appName":"今日运势预测"}`，无需查找图标 ID。名称和简介最多 14 个字符（UTF-16 计数），MCP 和 CLI 均在请求前检查。查询的 `description` 对应写入的 `slogan`；图片 URL 不能当作 fileId。所有写入继续校验确认哈希，编辑也会进入审核流程。

局部编辑需配套后端 validateBaseInfo 修复上线；旧服务仍拒绝缺省字段时报告部署差异，不猜测参数或自动重试。

## 失败与恢复

- `UPLOAD_SDK_LOAD_FAILED` / `Cannot find module 'uri-js'`：上传 SDK 尚未加载，文件尚未上传。当前包已显式声明 uri-js；旧的 npx 安装目录可能残缺，需使用新的 npm 缓存目录安装并重启 MCP，不能靠重复 confirm 修复。保留环境和 source，不删除整个用户缓存。示例在 MCP 配置中增加 `env: {"npm_config_cache":"/你有写权限的绝对路径/redapp-npm-cache-v2"}`（应选择尚未使用过的目录），包版本使用已发布且包含本次修复的版本；本地改动尚未发布时不能宣称 npm 用户已修复。
- `API_REJECTED`：保留后端文案，不更换环境重试，不编造参数绕过业务校验。
- `OUTCOME_UNKNOWN`：先查询列表/状态/历史版本核对远端结果；停止进程不能回滚已发生的远端写入。
- MCP 重启后任务记录失效：先核对远端结果，不能直接重复上传或送审；送审预览门禁需要当前会话内的预览任务。
- `dev` 第一次可能需要网络安装模拟器；返回 ready 前不要声称启动成功。

实现依据：[官方 MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x)。本仓库测试覆盖 stdio 握手、工具发现、CLI 真实子进程及本地模拟 API；真实线上请求和各客户端界面接入需分别验收。
