flycode-mcp 1.14.1 → 1.14.3

package/README.md

@@ -28,10 +28,14 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the
 
 > **两道防线**：① 工具返回体一律**紧凑序列化**（`JSON.stringify(data)`，不带缩进）——全仓库已无 `null, 2` 式美化输出；② `mcp_catalog` 返回体带**硬上限熔断**（`CATALOG_MAX_CHARS` = 32KB），超限会自动分级降级：先截断工具描述 → 再清空描述只留工具名 → 最后才丢弃工具清单，并在响应里回 `truncated` 与 `note`。降级顺序刻意牺牲描述、保住工具清单，因为「哪些工具可用」才是 catalog 的核心价值。回归用例见 `test/unit/catalog-budget.test.ts`。
 
+> **第三道防线（公告 schema 压缩）**：`tools/list` 里每个工具的 `inputSchema` 也可压缩——SDK 会把 zod schema 投影成完全内联的 JSON Schema（本仓库实测最大单 schema 14.9KB），叠加部分客户端存在 per-schema 硬上限（如 Kimi 约 15KB 直接拒绝）。`FLYCODE_MCP_INPUT_SCHEMA_PROFILE=compact` 时，`tools/list` 响应中每个工具的 `inputSchema` 被压缩到单 schema 13KiB 预算内：先剥离嵌套注解（description/examples/default/title，校验关键字保留）；仍超预算或超深度的回退「浅形」——只保留根属性的 type/description/enum 并注明为精简公告。**工具级描述一字不减、服务端 canonical 校验原样保留**，客户端看到的只是引导参数生成的公告形态。实测 27 工具公告 155KB → 103KB，最大单 schema 14.9KB → 1.4KB。实现见 `src/utils/compact-input-schema.ts`，回归用例见 `test/unit/compact-input-schema.test.ts` 与 `test/unit/tools-list-size.test.ts`。
+
 环境变量：
 
 - `PROGRESSIVE_DISCLOSURE=on`（默认）：启用渐进式披露。
 - `PROGRESSIVE_DISCLOSURE=off`：退化回「全部 25 个工具始终启用」的原有行为，作为客户端未实现 `tools/list_changed` 重拉时的兜底。若 `mcp_activate` 启用某域后调用域工具仍报 `tool not found`，说明当前客户端不支持该通知，请设为 `off`。
+- `FLYCODE_MCP_INPUT_SCHEMA_PROFILE=full`（默认）：`tools/list` 公告原始 schema，保持兼容。
+- `FLYCODE_MCP_INPUT_SCHEMA_PROFILE=compact`：启用公告 schema 压缩（见上「第三道防线」）。推荐给有 per-schema 大小限制或上下文预算紧张的客户端。
 
 ---
 
@@ -58,7 +62,7 @@ npm run typecheck
 npm run dev
 ```
 
-构建产物为单个压缩文件 `dist/flycode-mcp.min.js`（已在 `package.json` 的 `bin` 中注册为 `flycode-mcp`；minify 后折叠为单行以减小体积，运行时依赖 `@modelcontextprotocol/sdk` / `axios` / `zod` 保持外置）。
+构建产物有两份：`dist/flycode-mcp.min.js`（MCP server，minify 后折叠为单行以减小体积）与 `dist/cli.js`（命令行入口，不 minify、不折叠——内含界面文案）；`package.json` 的 `bin` 将 `flycode-mcp` 命令注册到 `dist/cli.js`。运行时依赖 `@modelcontextprotocol/sdk` / `axios` / `zod` / `@clack/prompts` 保持外置。
 
 > **注意（构建期易踩坑）**：单行折叠由 `scripts/collapse.mjs` 完成，**不可**退化为 `code.replace(/\n/g, '')`。
 > esbuild 为省一个字符会把含换行的字符串打印成「内含真实换行字符的模板字符串」（`` `\<LF>` ``，而非转义写法 `"\n"`），
@@ -69,6 +73,52 @@ npm run dev
 
 ---
 
+## CLI（flycode-mcp 命令）
+
+全局安装后即可使用 `flycode-mcp` 命令：
+
+```bash
+npm install -g flycode-mcp
+```
+
+| 命令                                | 说明                                                                                   |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| `flycode-mcp` / `flycode-mcp mcp`   | 启动 MCP stdio server（兼容 `key=value` 启动参数写法，行为与直跑 `dist/flycode-mcp.min.js` 一致） |
+| `flycode-mcp setup`                 | 交互安装配套 skill 到所选智能体（初版支持 WorkBuddy / Trae CN），不写任何 `mcp.json`              |
+| `flycode-mcp update`                | 自更新全局包，并刷新本工具安装过的 skill                                                        |
+| `flycode-mcp --version` / `--help`  | 版本与帮助                                                                              |
+
+### setup：安装 skill
+
+```bash
+flycode-mcp setup                                  # 交互：选 WorkBuddy / Trae CN → 预览计划 → 回车确认
+flycode-mcp setup -c workbuddy -c trae-cn --yes    # 非交互执行
+flycode-mcp setup --dry-run                        # 只打印安装计划，零写入
+```
+
+安装目标（初版只装 skill）：
+
+| 客户端    | skill 目录                                   |
+| --------- | -------------------------------------------- |
+| WorkBuddy | `~/.workbuddy/skills/flycode-mcp-skill/`     |
+| Trae CN   | `~/.trae-cn/skills/flycode-mcp-skill/`       |
+
+保护机制：
+
+- **已存在即更新替换**：目标目录已有 skill（无论当初是 CLI 安装还是手工放置）都会直接更新到当前版本；内容与版本均已一致时跳过写入。
+- **旧目录移入废纸篓**：替换时**不在同目录留任何备份**——旧目录整体移入系统废纸篓（macOS 废纸篓 / Windows 回收站 / Linux `gio trash`），需要时可从废纸篓手动恢复，绝不 `rm -rf`。
+- **事务写入**：先复制到临时 staging 目录并回读校验（文件清单 + `SKILL.md` + marker），校验通过、旧目录成功进废纸篓之后才原子切换为正式目录；全程 fail-closed，任何一步失败旧目录都原封不动。
+
+### update：自更新
+
+```bash
+flycode-mcp update
+```
+
+自动检测安装方式（npm / bun 全局安装）→ 从 npm registry 查最新版本 → 全局升级 → 回读包根校验版本 → 刷新已安装的 skill 目录（未安装的智能体跳过，旧目录移入废纸篓）。`npx` 临时安装或本地源码运行时给出对应的手动升级提示，不会盲改；失败路径（registry 不可达 / 安装命令失败 / 版本校验失败）均给出 remediation 提示。
+
+---
+
 ## 配置
 
 服务启动时需要一组连接参数，格式为**命令行参数字符串**，以 `&` 拼接的 `key=value` 形式传入（与 `URLSearchParams` 解析一致）：