record_safer_pro_mcp 1.0.31 → 1.0.32

package/README.md

@@ -1,87 +1,123 @@
-# Record Safer Pro MCP Server
+# Record Safer Pro MCP
 
-[Record Safer Pro](https://www.dadaoaudio.com) 的 AI 接口服务，基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 标准。它让 Claude Desktop、Kiro、Cursor、OpenCode 等客户端能够直接协助你的专业多通道录音工作流。
+Record Safer Pro 的官方 MCP Server。它让具备本机执行能力的 AI 客户端，可以直接接入专业多通道录音工作流，完成设备发现、录音准备、开始/停止录音、通道调整、标记管理等核心操作。
 
-由 **DADAO 大道声学（北京大道创响科技有限公司）** 开发。
+由 **DADAO 大道声学（北京大道创响科技有限公司）** 开发。  
+官网：[www.dadaoaudio.com](https://www.dadaoaudio.com)
 
-## 快速结论
+> **推荐安装方式：AI Direct Install**
+>
+> 把 [`INSTALL_AI.md`](./INSTALL_AI.md) 的全文直接发送给你的 AI Agent，并补充一句：
+>
+> `请按这份说明为我安装 Record Safer Pro MCP，只配置我当前正在使用的客户端，完成后执行 doctor 验证并告诉我结果。`
+>
+> 对大多数用户，这就是最快、最稳妥、最接近“零配置”的安装方式。
 
-- 当前真实 npm 包名和 CLI 命令名都是 `record_safer_pro_mcp`。
-- 标准本地接入方式是 `stdio`，推荐命令统一为 `npx -y record_safer_pro_mcp`。
-- 本地默认会自动发现 `~/.record_safer` 下的端口和授权 token，不需要手动填写端口。
-- 本地开发、解压包调试或未发布场景，再使用 `node /absolute/path/to/dist/index.js`。
+## 为什么优先用 `INSTALL_AI.md`
 
-## 安装与接入
+`INSTALL_AI.md` 不是一份给人手动照着点的普通说明书，而是一份为 AI Agent 编写的可执行安装指令。它的设计目标很明确：让 AI 在尽量少打扰用户的前提下，完成一次可靠、选择性、可验证的 MCP 接入。
 
-### 1. 安装 Node.js
+它会指导 AI：
 
-需要 Node.js `>= 18`。
+- 先识别你当前正在使用的客户端，而不是对所有平台一股脑写配置。
+- 统一使用 `npx -y record_safer_pro_mcp@latest`，避免全局安装、PATH、缓存版本不一致等常见问题。
+- 对 JSON 配置做结构化合并，尽量不破坏现有配置。
+- 在安装完成后执行 `--doctor` 做有效性验证，而不是只停留在“看起来写进去了”。
 
-安装完成后在终端验证：
+如果你的 AI 具备本机命令执行和文件写入能力，这种方式通常比人工逐项配置更快，也更不容易出错。
 
-```bash
-node -v
-npx -v
-```
+## 适用对象
 
-### 2. 启动 Record Safer Pro
+这种 AI 直装方式适用于：
 
-先启动 Record Safer Pro 桌面应用，再重启你的 AI 客户端。
+- Claude Desktop
+- Cursor
+- Gemini CLI
+- OpenCode
+- Kiro
+- Windsurf
 
-本地默认会自动发现后端地址与授权 token，无需手动配置端口。对于多数非只读控制操作，如果后端暂时不可达，macOS 上 MCP 也会尝试自动拉起桌面应用；只读查询工具仍建议你先手动打开应用。
+前提条件：
 
-### 3. 添加客户端配置
+- 已安装 Node.js `>= 18`
+- 已安装并可启动 Record Safer Pro 桌面应用
+- 你使用的 AI Agent 具备本机终端执行和本地配置文件修改能力
 
-以下示例都基于当前实际代码，统一使用 `record_safer_pro_mcp`。
+## 标准使用方式
 
-#### Claude Desktop
+最推荐的做法只有两步：
 
-编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：
+### 1. 把安装说明直接喂给 AI
 
-```json
-{
-  "mcpServers": {
-    "record-safer-pro": {
-      "command": "npx",
-      "args": ["-y", "record_safer_pro_mcp"]
-    }
-  }
-}
+打开 [`INSTALL_AI.md`](./INSTALL_AI.md)，将全文粘贴给你的 AI Agent。
+
+### 2. 追加一句明确指令
+
+可以直接使用下面这段话：
+
+```text
+请按这份 INSTALL_AI.md 为我安装 Record Safer Pro MCP。
+要求：
+1. 只配置我当前正在使用或已经安装的 AI 客户端。
+2. 不要修改我未使用的平台配置。
+3. 统一使用 npx -y record_safer_pro_mcp@latest。
+4. 修改 JSON 时保持原文件合法。
+5. 安装完成后执行 --doctor，并告诉我结果。
 ```
 
-#### Kiro
+这套方式的核心价值不是“让用户少看文档”，而是把安装本身变成一项可以交付给 AI 的标准化动作。
 
-编辑项目目录下的 `.kiro/settings/mcp.json`：
+## AI 安装完成后应有的结果
 
-```json
-{
-  "mcpServers": {
-    "record-safer-pro": {
-      "command": "npx",
-      "args": ["-y", "record_safer_pro_mcp"]
-    }
-  }
-}
+一个合格的安装结果，通常会同时满足以下几点：
+
+- AI 只修改了与你当前环境相关的 MCP 配置文件。
+- MCP 启动命令统一为 `npx -y record_safer_pro_mcp@latest`。
+- 需要重启或 reload 的客户端，AI 已明确提示你执行。
+- `npx -y record_safer_pro_mcp@latest --doctor` 返回成功结果。
+- Record Safer Pro 桌面应用可以被正常发现，且无需手动填写本地端口。
+
+## 手动配置
+
+只有在你的 AI 无法直接改本机文件，或者你明确希望人工接入时，才建议使用手动方式。
+
+当前实际 npm 包名和 CLI 命令名都是：
+
+```bash
+record_safer_pro_mcp
 ```
 
-#### Cursor
+推荐统一命令：
+
+```bash
+npx -y record_safer_pro_mcp@latest
+```
 
-在 Settings -> MCP 中添加，或编辑 `.cursor/mcp.json`：
+各客户端的常见接入位置如下：
+
+| 客户端 | 常见配置位置 | 配置方式 |
+| --- | --- | --- |
+| Gemini CLI | 命令行 | `gemini mcp add record-safer-pro --scope user npx -y record_safer_pro_mcp@latest` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | 在 `mcpServers` 中加入 `record-safer-pro` |
+| Cursor | `~/.cursor/mcp.json` 或项目内 `.cursor/mcp.json` | 在 `mcpServers` 中加入 `record-safer-pro` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | 在 `mcpServers` 中加入 `record-safer-pro` |
+| Kiro | `~/.kiro/settings/mcp.json` 或项目内 `.kiro/settings/mcp.json` | 在 `mcpServers` 中加入 `record-safer-pro` |
+| OpenCode | `~/.config/opencode/opencode.json(.jsonc)`、项目内 `opencode.json` 或 `.mcp.json` | 在 `mcp` 中加入 `record-safer-pro` |
+
+通用 `stdio` 配置形态如下：
 
 ```json
 {
   "mcpServers": {
     "record-safer-pro": {
       "command": "npx",
-      "args": ["-y", "record_safer_pro_mcp"]
+      "args": ["-y", "record_safer_pro_mcp@latest"]
     }
   }
 }
 ```
 
-#### OpenCode
-
-编辑 `opencode.json`：
+OpenCode 使用的结构略有不同：
 
 ```json
 {
@@ -89,64 +125,122 @@ npx -v
   "mcp": {
     "record-safer-pro": {
       "type": "local",
-      "command": ["npx", "-y", "record_safer_pro_mcp"],
-      "enabled": true,
-      "timeout": 30000
+      "command": ["npx", "-y", "record_safer_pro_mcp@latest"],
+      "enabled": true
     }
   }
 }
 ```
 
-## 验证安装是否成功
+更完整的平台级安装细节，直接参考 [`INSTALL_AI.md`](./INSTALL_AI.md)。
 
-不要只看 `npx -y record_safer_pro_mcp` 是否“卡住”。默认模式会启动 `stdio` MCP Server 并持续等待客户端接管，所以终端看起来像“没有输出”是正常现象。
+## 安装验证
 
-请用下面两个命令做一次性验证：
+不要把终端里运行 `npx -y record_safer_pro_mcp@latest` 后“没有输出”误判为失败。
+
+默认模式会启动 `stdio` MCP Server 并持续等待客户端接管，因此终端看起来像“卡住”是正常行为。正确的验证方式是：
 
 ```bash
-npx -y record_safer_pro_mcp --version
-npx -y record_safer_pro_mcp --doctor
+npx -y record_safer_pro_mcp@latest --version
+npx -y record_safer_pro_mcp@latest --doctor
 ```
 
 预期结果：
 
-- `--version` 会输出当前已发布版本。
-- `--doctor` 会输出 JSON，并包含当前实际代码返回的这些字段：`ok`、`packageName`、`version`、`nodeVersion`、`transport`。
+- `--version` 输出当前安装版本
+- `--doctor` 输出诊断结果 JSON
 
-## 本地 dist / 解压包配置
+如果这两个命令正常，说明安装链路和启动链路基本可用。
 
-如果你在本地开发 `record_safer_mcp`，或者正在使用解压后的 `dist/index.js`，改用下面这种配置。
+## 运行机制
 
-Claude Desktop 示例：
+当前默认接入方式是本地 `stdio`。
 
-```json
-{
-  "mcpServers": {
-    "record-safer-pro": {
-      "command": "node",
-      "args": ["/absolute/path/to/record_safer_mcp/dist/index.js"]
-    }
-  }
-}
+服务端会自动发现本机 Record Safer Pro 后端地址和授权 token，默认无需手动填写端口。对多数本地用户而言，安装完成后只需要：
+
+- 启动 Record Safer Pro 桌面应用
+- 重启或 reload 你的 AI 客户端
+- 直接开始使用自然语言调用录音能力
+
+当前实际行为：
+
+- 本地默认自动发现 `~/.record_safer` 下的端口和授权 token
+- macOS 下，部分非只读控制操作在后端暂时不可达时，会尝试自动拉起桌面应用
+- 只读查询工具更适合在桌面应用已打开的前提下使用
+
+## 能力范围
+
+当前 MCP Server 聚焦高频核心录音能力，适合在实际录音现场由 AI 协助完成以下工作：
+
+| 类别 | 能力 |
+| --- | --- |
+| 录音前准备 | 预览设置、确认设置、打开录音界面 |
+| 设备发现 | 列出当前可用音频输入设备 |
+| 录音控制 | 开始录音、停止录音、定时开始、定时停止、取消定时 |
+| 录音状态 | 获取通道、混音、健康状态、最小录音状态 |
+| 通道操作 | 重命名通道、调颜色、音量、声像、solo、mute、反相 |
+| 录音中管理 | 添加标记、列出轨道、列出标记、重命名标记 |
+
+当前仅暴露 24 个高频核心工具，不通过 MCP 暴露以下能力：
+
+- 系统设置
+- 更新
+- 激活
+- 存储管理
+- 文件分割等扩展功能
+
+## 关键行为边界
+
+为了让 AI 在录音流程中表现稳定，以下语义边界很重要：
+
+- `start_record_mcp` 的职责是打开录音界面并准备本次会话，不等于真正开始录音。
+- 真正开始录音需要后续显式调用 `start_recording`。
+- 如果 `get_status` 已返回 `ready=true`，应优先沿用当前已准备好的会话，而不是重复初始化。
+- 如果你没有指定声卡，AI 应先调用 `list_audio_devices`，再让你选择。
+- 如果你没有指定通道，默认使用所选声卡的全部输入通道。
+
+默认录音设置为：
+
+- 所选声卡当前或默认采样率
+- `24-bit`
+- `wav`
+- 安全模式
+- `~/Desktop`
+
+## 使用示例
+
+安装完成后，可以直接让 AI 这样操作：
+
+- “用 RME Babyface，通道 1-4，WAV，默认 48k/24bit 和桌面路径，帮我打开录音界面并准备录音”
+- “先列出当前可用声卡，我来选一个，然后按默认参数准备录音”
+- “5 分钟后开始录音，并在开始后 30 分钟自动停止”
+- “帮我看一下当前录音健康状态”
+- “我已经在录音界面，把 3 号通道静音”
+- “在当前位置添加一个标记，命名为‘第二段’”
+- “停止录音”
+
+## 本地开发与离线模式
+
+如果你在本地开发 `record_safer_mcp`，或者所处环境无法使用 npm 在线拉取包，可以直接指向本地 `dist/index.js`：
+
+```bash
+node /absolute/path/to/record_safer_mcp/dist/index.js
 ```
 
-OpenCode 示例：
+例如 Claude Desktop：
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
+  "mcpServers": {
     "record-safer-pro": {
-      "type": "local",
-      "command": ["node", "/absolute/path/to/record_safer_mcp/dist/index.js"],
-      "enabled": true,
-      "timeout": 30000
+      "command": "node",
+      "args": ["/absolute/path/to/record_safer_mcp/dist/index.js"]
     }
   }
 }
 ```
 
-本地默认同样会自动发现端口和 token。只有在你明确覆盖目标后端时，才需要额外设置环境变量，例如：
+如果你明确要覆盖目标后端地址，再额外设置环境变量，例如：
 
 ```json
 {
@@ -162,66 +256,9 @@ OpenCode 示例：
 }
 ```
 
-## 功能一览
-
-安装后，AI 助手可以帮你完成这些高频操作：
-
-| 类别 | 能力 |
-|------|------|
-| 录音前准备 | 预览设置、确认设置、打开录音界面 |
-| 设备发现 | 列出当前可用音频输入设备 |
-| 录音控制 | 显式开始/停止录音，或定时开始/定时停止/取消定时 |
-| 录音状态 | 获取通道、混音、健康状态、最小录音状态 |
-| 通道调整 | 重命名通道、调整颜色、调音量、调声像、solo、mute、切换反相 |
-| 录音中操作 | 添加标记、查看轨道、查看标记、重命名标记 |
-
-当前 MCP Server 只保留高频核心工具，共 24 个：
-
-- `list_audio_devices`
-- `preview_record_mcp_setup`
-- `confirm_record_mcp_setup`
-- `start_record_mcp`
-- `start_recording`
-- `schedule_start_recording`
-- `schedule_stop_recording`
-- `cancel_scheduled_recording`
-- `get_channels`
-- `get_mix`
-- `get_health`
-- `get_status`
-- `stop_recording`
-- `list_tracks`
-- `list_markers`
-- `add_marker`
-- `rename_marker`
-- `rename_channel`
-- `set_channel_color`
-- `set_channel_volume`
-- `set_channel_pan`
-- `set_channel_solo`
-- `set_channel_mute`
-- `set_channel_phase_invert`
-
-以下能力当前不通过 MCP 暴露，必须在 GUI 中手动完成：
-
-- 系统设置
-- 更新
-- 激活
-- 存储管理
-- 文件分割等扩展功能
-
-## 当前实际行为约束
-
-- `start_record_mcp` 的职责是“在你确认完整配置后，打开录音界面并准备本次会话”，不是“开始录音”。
-- `start_recording` 仍然是后续单独动作，必须在录音界面已经准备好后再显式确认。
-- 如果 `get_status` 已经返回 `ready=true`，MCP 应直接沿用当前准备好的录音会话，而不是强制重新走一遍初始化。
-- 如果你没有指定声卡，AI 应先调用 `list_audio_devices`，把这次返回的所有输入设备完整展示给你选择。
-- 如果你没有指定通道，默认会使用所选声卡的全部输入通道；确认清单里显示的通道数必须是实际会录进去的通道数。
-- 默认录音设置是：所选声卡当前或默认采样率、`24-bit`、`wav`、安全模式、`~/Desktop`。
-
 ## Streamable HTTP 远程模式
 
-为了兼容 OpenAI Developer Mode / remote MCP 场景，当前实际代码也支持可选的 `Streamable HTTP` 传输。
+当前代码也支持可选的 `streamable-http` 传输，适用于 OpenAI Developer Mode 或需要远程暴露 MCP 的场景。
 
 默认环境变量：
 
@@ -230,13 +267,13 @@ OpenCode 示例：
 - `RECORD_SAFER_MCP_HTTP_PORT=3010`
 - `RECORD_SAFER_MCP_HTTP_PATH=/mcp`
 
-切到远程模式：
+示例：
 
 ```bash
 RECORD_SAFER_MCP_TRANSPORT=streamable-http \
 RECORD_SAFER_MCP_HTTP_HOST=127.0.0.1 \
 RECORD_SAFER_MCP_HTTP_PORT=3010 \
-npx -y record_safer_pro_mcp
+npx -y record_safer_pro_mcp@latest
 ```
 
 启动后默认端点：
@@ -246,67 +283,37 @@ npx -y record_safer_pro_mcp
 
 安全约束：
 
-- 当 `RECORD_SAFER_MCP_HTTP_HOST` 是非回环地址，例如 `0.0.0.0`，必须同时设置 `RECORD_SAFER_MCP_HTTP_BEARER_TOKEN`。
-- 可选设置 `RECORD_SAFER_MCP_HTTP_ALLOWED_HOSTS=your-domain.com,localhost` 来限制允许的 Host 头。
-- 如果要给公网客户端或 OpenAI Developer Mode 使用，必须通过 HTTPS 对外暴露，建议放在 HTTPS 反向代理之后。
-- 如果你把 `RECORD_SAFER_URL` 指向非回环地址，当前代码默认会拒绝把本机 `~/.record_safer/auth_token` 发给远端；这时请显式设置 `RECORD_SAFER_TOKEN`，或使用远端 token 白名单环境变量。
-
-带鉴权的示例：
-
-```bash
-RECORD_SAFER_MCP_TRANSPORT=streamable-http \
-RECORD_SAFER_MCP_HTTP_HOST=0.0.0.0 \
-RECORD_SAFER_MCP_HTTP_PORT=3010 \
-RECORD_SAFER_MCP_HTTP_BEARER_TOKEN=replace-with-a-long-random-token \
-RECORD_SAFER_MCP_HTTP_ALLOWED_HOSTS=your-domain.com \
-npx -y record_safer_pro_mcp
-```
-
-## 使用示例
-
-配置完成后，你可以直接用自然语言让 AI 操作 Record Safer Pro：
-
-- "用 RME Babyface，通道 1-4，WAV，默认 48k/24bit 和桌面路径，帮我打开录音界面并准备录音"
-- "帮我开始一个录音，先列出当前可用声卡让我选择；如果我没特别说明，就按 wav、24-bit、安全模式和桌面路径准备"
-- "5 分钟后开始录音，并在开始后 30 分钟自动停止"
-- "帮我列出当前所有音频输入设备"
-- "现在有哪些通道？"
-- "帮我看一下当前录音健康状态"
-- "我已经在录音控制台了，直接帮我开始录音"
-- "我已经进了录音界面，把 3 号通道静音"
-- "在当前位置添加一个标记，命名为'第二段'"
-- "把 3 号通道改名为 Vocal"
-- "列出当前所有标记"
-- "停止录音"
+- 当 `RECORD_SAFER_MCP_HTTP_HOST` 为非回环地址，例如 `0.0.0.0`，必须同时设置 `RECORD_SAFER_MCP_HTTP_BEARER_TOKEN`
+- 可选使用 `RECORD_SAFER_MCP_HTTP_ALLOWED_HOSTS` 限制允许的 Host
+- 对公网客户端暴露时，必须通过 HTTPS 反向代理对外提供服务
+- 如果 `RECORD_SAFER_URL` 指向非回环地址，默认不会把本机 `~/.record_safer/auth_token` 自动发送到远端
 
 ## 常见问题
 
 **Q: AI 提示无法连接 Record Safer Pro？**
 
-先确认 Record Safer Pro 桌面应用已经启动并完成初始化。MCP 依赖本机录音服务和授权 token。若仍失败，再重启 AI 客户端后重试。
-
-**Q: 提示找不到 npx 命令？**
-
-需要安装 Node.js `>= 18`。访问 [nodejs.org](https://nodejs.org) 下载安装。
+先确认 Record Safer Pro 桌面应用已经启动并完成初始化。MCP 依赖本机录音服务和授权 token。若仍失败，重启 AI 客户端后再重试。
 
-**Q: 我在终端里运行 `npx -y record_safer_pro_mcp` 后没有任何输出，是不是安装失败了？**
+**Q: 提示找不到 `npx` 命令？**
 
-不是。默认模式就是等待客户端接管的 `stdio` Server。请改用：
+需要先安装 Node.js `>= 18`。安装完成后确认：
 
 ```bash
-npx -y record_safer_pro_mcp --version
-npx -y record_safer_pro_mcp --doctor
+node -v
+npx -v
 ```
 
-如果这两个命令能正常输出，说明 npm 包安装和启动链路是正常的。
+**Q: 我在终端运行 `npx -y record_safer_pro_mcp@latest` 后没有任何输出，是不是安装失败了？**
+
+不是。默认行为就是等待客户端接管的 `stdio` Server。请使用 `--version` 和 `--doctor` 验证，而不是直接通过“是否卡住”来判断。
 
-**Q: 端口不是 8080 怎么办？**
+**Q: 正常情况下需要手动配置端口吗？**
 
-正常情况下不需要手动处理，应用会自动写入端口文件并自动发现。如果你确实要覆盖目标后端，再设置 `RECORD_SAFER_URL`。
+不需要。默认会自动发现本机端口和 token。只有在你明确覆盖目标后端时，才需要设置 `RECORD_SAFER_URL`。
 
-**Q: 版本不兼容时会怎样？**
+**Q: 为什么 README 反复强调把 `INSTALL_AI.md` 直接发给 AI？**
 
-当前代码会先做 MCP compatibility handshake。如果桌面端过旧、协议版本不匹配、缺少必需 capability，MCP 会直接报出升级或兼容性错误，而不是静默失败。
+因为这是目前最贴近真实用户路径的安装方式。相比人工阅读后再逐步配置，它更标准化、更可复制，也更适合产品交付和团队支持。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "record_safer_pro_mcp",
-  "version": "1.0.31",
+  "version": "1.0.32",
   "description": "Record Safer Pro MCP Server — 专业多通道录音工作流 AI 控制接口 / AI control interface for professional multichannel recording workflows",
   "type": "module",
   "main": "dist/index.js",