record_safer_pro_mcp 1.0.31 → 1.0.33

package/README.md

@@ -1,136 +1,448 @@
-# 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 等客户端能够直接协助你的专业多通道录音工作流。
+Language: [中文](#zh-cn) | [English](#english)
 
-由 **DADAO 大道声学（北京大道创响科技有限公司）** 开发。
+<a id="zh-cn"></a>
+## 中文
 
-## 快速结论
+Record Safer Pro 的官方 MCP Server。它让具备本机执行能力的 AI 客户端，可以直接接入专业多通道录音工作流，完成设备发现、录音准备、开始/停止录音、通道调整、标记管理等核心操作。
 
-- 当前真实 npm 包名和 CLI 命令名都是 `record_safer_pro_mcp`。
-- 标准本地接入方式是 `stdio`，推荐命令统一为 `npx -y record_safer_pro_mcp`。
-- 本地默认会自动发现 `~/.record_safer` 下的端口和授权 token，不需要手动填写端口。
-- 本地开发、解压包调试或未发布场景，再使用 `node /absolute/path/to/dist/index.js`。
+由 **DADAO 大道声学（北京大道创响科技有限公司）** 开发。  
+官网：[www.dadaoaudio.com](https://www.dadaoaudio.com)
 
-## 安装与接入
+> **推荐安装方式：AI Direct Install**
+>
+> 把 [`INSTALL_AI.md`](./INSTALL_AI.md) 的全文直接发送给你的 AI Agent，并补充一句：
+>
+> `请按这份说明为我安装 Record Safer Pro MCP，只配置我当前正在使用的客户端，完成后执行 doctor 验证并告诉我结果。`
+>
+> 对大多数用户，这就是最快、最稳妥、最接近“零配置”的安装方式。
 
-### 1. 安装 Node.js
+### 为什么优先用 `INSTALL_AI.md`
 
-需要 Node.js `>= 18`。
+`INSTALL_AI.md` 不是一份给人手动照着点的普通说明书，而是一份为 AI Agent 编写的可执行安装指令。它的设计目标很明确：让 AI 在尽量少打扰用户的前提下，完成一次可靠、选择性、可验证的 MCP 接入。
 
-安装完成后在终端验证：
+它会指导 AI：
 
-```bash
-node -v
-npx -v
+- 先识别你当前正在使用的客户端，而不是对所有平台一股脑写配置
+- 统一使用 `npx -y record_safer_pro_mcp@latest`，避免全局安装、PATH、缓存版本不一致等常见问题
+- 对 JSON 配置做结构化合并，尽量不破坏现有配置
+- 在安装完成后执行 `--doctor` 做有效性验证，而不是只停留在“看起来写进去了”
+
+如果你的 AI 具备本机命令执行和文件写入能力，这种方式通常比人工逐项配置更快，也更不容易出错。
+
+### 适用对象
+
+这种 AI 直装方式适用于：
+
+- Claude Desktop
+- Cursor
+- Gemini CLI
+- OpenCode
+- Kiro
+- Windsurf
+
+前提条件：
+
+- 已安装 Node.js `>= 18`
+- 已安装并可启动 Record Safer Pro 桌面应用
+- 你使用的 AI Agent 具备本机终端执行和本地配置文件修改能力
+
+### 标准使用方式
+
+最推荐的做法只有两步：
+
+#### 1. 把安装说明直接喂给 AI
+
+打开 [`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，并告诉我结果。
 ```
 
-### 2. 启动 Record Safer Pro
+这套方式的核心价值不是“让用户少看文档”，而是把安装本身变成一项可以交付给 AI 的标准化动作。
 
-先启动 Record Safer Pro 桌面应用，再重启你的 AI 客户端。
+### AI 安装完成后应有的结果
 
-本地默认会自动发现后端地址与授权 token，无需手动配置端口。对于多数非只读控制操作，如果后端暂时不可达，macOS 上 MCP 也会尝试自动拉起桌面应用；只读查询工具仍建议你先手动打开应用。
+一个合格的安装结果，通常会同时满足以下几点：
 
-### 3. 添加客户端配置
+- AI 只修改了与你当前环境相关的 MCP 配置文件
+- MCP 启动命令统一为 `npx -y record_safer_pro_mcp@latest`
+- 需要重启或 reload 的客户端，AI 已明确提示你执行
+- `npx -y record_safer_pro_mcp@latest --doctor` 返回成功结果
+- Record Safer Pro 桌面应用可以被正常发现，且无需手动填写本地端口
 
-以下示例都基于当前实际代码，统一使用 `record_safer_pro_mcp`。
+### 手动配置
 
-#### Claude Desktop
+只有在你的 AI 无法直接改本机文件，或者你明确希望人工接入时，才建议使用手动方式。
 
-编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：
+当前实际 npm 包名和 CLI 命令名都是：
+
+```bash
+record_safer_pro_mcp
+```
+
+推荐统一命令：
+
+```bash
+npx -y record_safer_pro_mcp@latest
+```
+
+各客户端的常见接入位置如下：
+
+| 客户端 | 常见配置位置 | 配置方式 |
+| --- | --- | --- |
+| 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"]
     }
   }
 }
 ```
 
-#### Kiro
-
-编辑项目目录下的 `.kiro/settings/mcp.json`：
+OpenCode 使用的结构略有不同：
 
 ```json
 {
-  "mcpServers": {
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
     "record-safer-pro": {
-      "command": "npx",
-      "args": ["-y", "record_safer_pro_mcp"]
+      "type": "local",
+      "command": ["npx", "-y", "record_safer_pro_mcp@latest"],
+      "enabled": true
     }
   }
 }
 ```
 
-#### Cursor
+更完整的平台级安装细节，直接参考 [`INSTALL_AI.md`](./INSTALL_AI.md)。
+
+### 安装验证
+
+不要把终端里运行 `npx -y record_safer_pro_mcp@latest` 后“没有输出”误判为失败。
+
+默认模式会启动 `stdio` MCP Server 并持续等待客户端接管，因此终端看起来像“卡住”是正常行为。正确的验证方式是：
+
+```bash
+npx -y record_safer_pro_mcp@latest --version
+npx -y record_safer_pro_mcp@latest --doctor
+```
+
+预期结果：
+
+- `--version` 输出当前安装版本
+- `--doctor` 输出诊断结果 JSON
+
+如果这两个命令正常，说明安装链路和启动链路基本可用。
+
+### 运行机制
+
+当前默认接入方式是本地 `stdio`。
+
+服务端会自动发现本机 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 这样操作：
 
-在 Settings -> MCP 中添加，或编辑 `.cursor/mcp.json`：
+- “用 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
+```
+
+例如 Claude Desktop：
 
 ```json
 {
   "mcpServers": {
     "record-safer-pro": {
-      "command": "npx",
-      "args": ["-y", "record_safer_pro_mcp"]
+      "command": "node",
+      "args": ["/absolute/path/to/record_safer_mcp/dist/index.js"]
     }
   }
 }
 ```
 
-#### OpenCode
-
-编辑 `opencode.json`：
+如果你明确要覆盖目标后端地址，再额外设置环境变量，例如：
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
+  "mcpServers": {
     "record-safer-pro": {
-      "type": "local",
-      "command": ["npx", "-y", "record_safer_pro_mcp"],
-      "enabled": true,
-      "timeout": 30000
+      "command": "node",
+      "args": ["/absolute/path/to/record_safer_mcp/dist/index.js"],
+      "env": {
+        "RECORD_SAFER_URL": "http://127.0.0.1:你的端口号"
+      }
     }
   }
 }
 ```
 
-## 验证安装是否成功
+### Streamable HTTP 远程模式
 
-不要只看 `npx -y record_safer_pro_mcp` 是否“卡住”。默认模式会启动 `stdio` MCP Server 并持续等待客户端接管，所以终端看起来像“没有输出”是正常现象。
+当前代码也支持可选的 `streamable-http` 传输，适用于 OpenAI Developer Mode 或需要远程暴露 MCP 的场景。
 
-请用下面两个命令做一次性验证：
+默认环境变量：
+
+- `RECORD_SAFER_MCP_TRANSPORT=stdio`
+- `RECORD_SAFER_MCP_HTTP_HOST=127.0.0.1`
+- `RECORD_SAFER_MCP_HTTP_PORT=3010`
+- `RECORD_SAFER_MCP_HTTP_PATH=/mcp`
+
+示例：
 
 ```bash
-npx -y record_safer_pro_mcp --version
-npx -y record_safer_pro_mcp --doctor
+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@latest
 ```
 
-预期结果：
+启动后默认端点：
+
+- MCP: `http://127.0.0.1:3010/mcp`
+- Health: `http://127.0.0.1:3010/healthz`
+
+安全约束：
+
+- 当 `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` 自动发送到远端
+
+### 常见问题
 
-- `--version` 会输出当前已发布版本。
-- `--doctor` 会输出 JSON，并包含当前实际代码返回的这些字段：`ok`、`packageName`、`version`、`nodeVersion`、`transport`。
+**Q: AI 提示无法连接 Record Safer Pro？**
+
+先确认 Record Safer Pro 桌面应用已经启动并完成初始化。MCP 依赖本机录音服务和授权 token。若仍失败，重启 AI 客户端后再重试。
+
+**Q: 提示找不到 `npx` 命令？**
+
+需要先安装 Node.js `>= 18`。安装完成后确认：
 
-## 本地 dist / 解压包配置
+```bash
+node -v
+npx -v
+```
 
-如果你在本地开发 `record_safer_mcp`，或者正在使用解压后的 `dist/index.js`，改用下面这种配置。
+**Q: 我在终端运行 `npx -y record_safer_pro_mcp@latest` 后没有任何输出，是不是安装失败了？**
+
+不是。默认行为就是等待客户端接管的 `stdio` Server。请使用 `--version` 和 `--doctor` 验证，而不是直接通过“是否卡住”来判断。
+
+**Q: 正常情况下需要手动配置端口吗？**
+
+不需要。默认会自动发现本机端口和 token。只有在你明确覆盖目标后端时，才需要设置 `RECORD_SAFER_URL`。
+
+**Q: 为什么 README 反复强调把 `INSTALL_AI.md` 直接发给 AI？**
+
+因为这是目前最贴近真实用户路径的安装方式。相比人工阅读后再逐步配置，它更标准化、更可复制，也更适合产品交付和团队支持。
+
+---
 
-Claude Desktop 示例：
+<a id="english"></a>
+## English
+
+The official MCP server for Record Safer Pro. It allows AI clients with local execution capability to connect directly to a professional multichannel recording workflow and handle core tasks such as device discovery, recording preparation, start/stop recording, channel control, and marker management.
+
+Built by **DADAO Audio (Beijing Dadao Chuangxiang Technology Co., Ltd.)**.  
+Website: [www.dadaoaudio.com](https://www.dadaoaudio.com)
+
+> **Recommended installation path: AI Direct Install**
+>
+> Send the full contents of [`INSTALL_AI.md`](./INSTALL_AI.md) directly to your AI agent, then add this instruction:
+>
+> `Please install Record Safer Pro MCP based on this guide, configure only the client I currently use, run doctor after setup, and tell me the result.`
+>
+> For most users, this is the fastest, safest, and closest-to-zero-config installation path.
+
+### Why `INSTALL_AI.md` Comes First
+
+`INSTALL_AI.md` is not a conventional step-by-step document written for manual setup. It is an executable installation brief written for AI agents. Its purpose is clear: let AI complete a reliable, selective, and verifiable MCP setup with minimal user interruption.
+
+It tells the AI to:
+
+- detect the client you actually use instead of writing configuration for every platform
+- standardize on `npx -y record_safer_pro_mcp@latest` to avoid global install issues, PATH problems, and stale cached versions
+- merge JSON configuration safely instead of overwriting or breaking existing files
+- run `--doctor` after setup so installation is verified, not just "apparently written"
+
+If your AI can run local commands and edit local files, this approach is usually faster and more reliable than manual configuration.
+
+### Who This Is For
+
+This AI-driven installation flow is designed for:
+
+- Claude Code
+- Cursor
+- Gemini CLI
+- OpenCode
+- Kiro
+- Windsurf
+
+Prerequisites:
+
+- Node.js `>= 18` is installed
+- The Record Safer Pro desktop application is installed and can be launched
+- Your AI agent has permission to run local terminal commands and edit local configuration files
+
+### Recommended Workflow
+
+The recommended setup has only two steps.
+
+#### 1. Feed the installation guide directly to AI
+
+Open [`INSTALL_AI.md`](./INSTALL_AI.md) and paste the full file into your AI agent.
+
+#### 2. Add an explicit execution instruction
+
+You can use this exact prompt:
+
+```text
+Please install Record Safer Pro MCP based on this INSTALL_AI.md.
+Requirements:
+1. Configure only the AI client I currently use or already have installed.
+2. Do not modify configuration for platforms I do not use.
+3. Use npx -y record_safer_pro_mcp@latest consistently.
+4. Keep all edited JSON files valid.
+5. Run --doctor after installation and tell me the result.
+```
+
+The value of this workflow is not merely that the user reads less documentation. The real value is that installation becomes a standardized task that can be delegated to AI and executed consistently.
+
+### What a Successful AI Installation Looks Like
+
+A good installation outcome should usually meet all of the following:
+
+- the AI edits only MCP configuration files relevant to your actual environment
+- the launch command is standardized as `npx -y record_safer_pro_mcp@latest`
+- any required restart or reload step is clearly communicated
+- `npx -y record_safer_pro_mcp@latest --doctor` completes successfully
+- the Record Safer Pro desktop app is discovered automatically without manual port configuration
+
+### Manual Setup
+
+Manual setup is recommended only when your AI cannot modify local files directly or when you explicitly want to wire it by hand.
+
+The current npm package name and CLI command are:
+
+```bash
+record_safer_pro_mcp
+```
+
+Recommended standard command:
+
+```bash
+npx -y record_safer_pro_mcp@latest
+```
+
+Common integration points:
+
+| Client | Common config location | Integration method |
+| --- | --- | --- |
+| Gemini CLI | command line | `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` | add `record-safer-pro` under `mcpServers` |
+| Cursor | `~/.cursor/mcp.json` or project `.cursor/mcp.json` | add `record-safer-pro` under `mcpServers` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | add `record-safer-pro` under `mcpServers` |
+| Kiro | `~/.kiro/settings/mcp.json` or project `.kiro/settings/mcp.json` | add `record-safer-pro` under `mcpServers` |
+| OpenCode | `~/.config/opencode/opencode.json(.jsonc)`, project `opencode.json`, or `.mcp.json` | add `record-safer-pro` under `mcp` |
+
+Standard `stdio` shape:
 
 ```json
 {
   "mcpServers": {
     "record-safer-pro": {
-      "command": "node",
-      "args": ["/absolute/path/to/record_safer_mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "record_safer_pro_mcp@latest"]
     }
   }
 }
 ```
 
-OpenCode 示例：
+OpenCode uses a slightly different structure:
 
 ```json
 {
@@ -138,15 +450,122 @@ OpenCode 示例：
   "mcp": {
     "record-safer-pro": {
       "type": "local",
-      "command": ["node", "/absolute/path/to/record_safer_mcp/dist/index.js"],
-      "enabled": true,
-      "timeout": 30000
+      "command": ["npx", "-y", "record_safer_pro_mcp@latest"],
+      "enabled": true
     }
   }
 }
 ```
 
-本地默认同样会自动发现端口和 token。只有在你明确覆盖目标后端时，才需要额外设置环境变量，例如：
+For full platform-specific installation details, refer to [`INSTALL_AI.md`](./INSTALL_AI.md).
+
+### Installation Verification
+
+Do not treat "no output" from `npx -y record_safer_pro_mcp@latest` as an installation failure.
+
+By default, the server starts in `stdio` mode and waits for the client to attach, so the terminal may appear to hang. The correct way to validate installation is:
+
+```bash
+npx -y record_safer_pro_mcp@latest --version
+npx -y record_safer_pro_mcp@latest --doctor
+```
+
+Expected behavior:
+
+- `--version` prints the installed version
+- `--doctor` prints diagnostic JSON
+
+If both commands succeed, the install and startup path is generally working.
+
+### How It Works
+
+The default integration mode is local `stdio`.
+
+The server automatically discovers the local Record Safer Pro backend address and auth token, so manual port input is not required in the normal local workflow. For most users, installation is followed by only three actions:
+
+- launch the Record Safer Pro desktop app
+- restart or reload your AI client
+- start using natural-language recording commands
+
+Current runtime behavior:
+
+- local port and auth token are discovered automatically from `~/.record_safer`
+- on macOS, some non-read-only control actions may attempt to auto-launch the desktop app if the backend is temporarily unavailable
+- read-only inspection tools work best when the desktop app is already running
+
+### Capability Scope
+
+The current MCP server is intentionally focused on high-frequency recording tasks that are practical during real sessions:
+
+| Category | Capability |
+| --- | --- |
+| Pre-record setup | preview setup, confirm setup, open recording screen |
+| Device discovery | list currently available audio input devices |
+| Recording control | start recording, stop recording, scheduled start, scheduled stop, cancel schedule |
+| Recording status | retrieve channels, mix, health, and minimal status |
+| Channel operations | rename channel, set color, volume, pan, solo, mute, phase invert |
+| In-session management | add markers, list tracks, list markers, rename markers |
+
+Only 24 high-frequency core tools are exposed at this time. The following capabilities are intentionally not exposed through MCP:
+
+- system settings
+- updates
+- activation
+- storage management
+- extended features such as file splitting
+
+### Important Behavioral Boundaries
+
+To keep AI behavior stable in real recording workflows, these semantics matter:
+
+- `start_record_mcp` prepares the recording session and opens the recording screen; it does not actually start recording
+- actual recording still requires an explicit `start_recording` step
+- if `get_status` already returns `ready=true`, the existing prepared session should be reused rather than reinitialized
+- if no audio device is specified, the AI should call `list_audio_devices` first and let the user choose
+- if no channels are specified, the default is all input channels of the selected device
+
+Default recording settings:
+
+- the selected interface's current or default sample rate
+- `24-bit`
+- `wav`
+- safe mode
+- `~/Desktop`
+
+### Example Prompts
+
+After setup, you can instruct AI with prompts like:
+
+- "Use RME Babyface on channels 1-4, WAV, default 48k/24-bit, Desktop path, and prepare the recording screen for me."
+- "List the currently available audio devices first. I'll choose one, then prepare recording with the default settings."
+- "Start recording in 5 minutes and stop automatically 30 minutes later."
+- "Check the current recording health status."
+- "I'm already on the recording screen. Mute channel 3."
+- "Add a marker here and name it Second Segment."
+- "Stop recording."
+
+### Local Development and Offline Mode
+
+If you are developing `record_safer_mcp` locally, or if your environment cannot fetch the npm package online, point the client directly to the local `dist/index.js`:
+
+```bash
+node /absolute/path/to/record_safer_mcp/dist/index.js
+```
+
+Claude Desktop example:
+
+```json
+{
+  "mcpServers": {
+    "record-safer-pro": {
+      "command": "node",
+      "args": ["/absolute/path/to/record_safer_mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+If you explicitly want to override the backend target, add environment variables such as:
 
 ```json
 {
@@ -155,159 +574,72 @@ OpenCode 示例：
       "command": "node",
       "args": ["/absolute/path/to/record_safer_mcp/dist/index.js"],
       "env": {
-        "RECORD_SAFER_URL": "http://127.0.0.1:你的端口号"
+        "RECORD_SAFER_URL": "http://127.0.0.1:your-port"
       }
     }
   }
 }
 ```
 
-## 功能一览
-
-安装后，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 中手动完成：
-
-- 系统设置
-- 更新
-- 激活
-- 存储管理
-- 文件分割等扩展功能
-
-## 当前实际行为约束
+### Streamable HTTP Remote Mode
 
-- `start_record_mcp` 的职责是“在你确认完整配置后，打开录音界面并准备本次会话”，不是“开始录音”。
-- `start_recording` 仍然是后续单独动作，必须在录音界面已经准备好后再显式确认。
-- 如果 `get_status` 已经返回 `ready=true`，MCP 应直接沿用当前准备好的录音会话，而不是强制重新走一遍初始化。
-- 如果你没有指定声卡，AI 应先调用 `list_audio_devices`，把这次返回的所有输入设备完整展示给你选择。
-- 如果你没有指定通道，默认会使用所选声卡的全部输入通道；确认清单里显示的通道数必须是实际会录进去的通道数。
-- 默认录音设置是：所选声卡当前或默认采样率、`24-bit`、`wav`、安全模式、`~/Desktop`。
+The current codebase also supports optional `streamable-http` transport for OpenAI Developer Mode and other remote MCP deployment scenarios.
 
-## Streamable HTTP 远程模式
-
-为了兼容 OpenAI Developer Mode / remote MCP 场景，当前实际代码也支持可选的 `Streamable HTTP` 传输。
-
-默认环境变量：
+Default environment variables:
 
 - `RECORD_SAFER_MCP_TRANSPORT=stdio`
 - `RECORD_SAFER_MCP_HTTP_HOST=127.0.0.1`
 - `RECORD_SAFER_MCP_HTTP_PORT=3010`
 - `RECORD_SAFER_MCP_HTTP_PATH=/mcp`
 
-切到远程模式：
+Example:
 
 ```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
 ```
 
-启动后默认端点：
+Default endpoints after launch:
 
 - MCP: `http://127.0.0.1:3010/mcp`
 - Health: `http://127.0.0.1:3010/healthz`
 
-安全约束：
-
-- 当 `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
-```
+Security constraints:
 
-## 使用示例
+- if `RECORD_SAFER_MCP_HTTP_HOST` is set to a non-loopback address such as `0.0.0.0`, you must also set `RECORD_SAFER_MCP_HTTP_BEARER_TOKEN`
+- you may optionally restrict allowed hosts with `RECORD_SAFER_MCP_HTTP_ALLOWED_HOSTS`
+- if exposed publicly, the service should be placed behind HTTPS reverse proxying
+- if `RECORD_SAFER_URL` points to a non-loopback target, the local `~/.record_safer/auth_token` is not forwarded automatically by default
 
-配置完成后，你可以直接用自然语言让 AI 操作 Record Safer Pro：
+### FAQ
 
-- "用 RME Babyface，通道 1-4，WAV，默认 48k/24bit 和桌面路径，帮我打开录音界面并准备录音"
-- "帮我开始一个录音，先列出当前可用声卡让我选择；如果我没特别说明，就按 wav、24-bit、安全模式和桌面路径准备"
-- "5 分钟后开始录音，并在开始后 30 分钟自动停止"
-- "帮我列出当前所有音频输入设备"
-- "现在有哪些通道？"
-- "帮我看一下当前录音健康状态"
-- "我已经在录音控制台了，直接帮我开始录音"
-- "我已经进了录音界面，把 3 号通道静音"
-- "在当前位置添加一个标记，命名为'第二段'"
-- "把 3 号通道改名为 Vocal"
-- "列出当前所有标记"
-- "停止录音"
+**Q: The AI says it cannot connect to Record Safer Pro. What should I check?**
 
-## 常见问题
+First make sure the Record Safer Pro desktop app is already running and fully initialized. MCP depends on the local recording service and auth token. If the issue persists, restart the AI client and try again.
 
-**Q: AI 提示无法连接 Record Safer Pro？**
+**Q: `npx` is not found. What does that mean?**
 
-先确认 Record Safer Pro 桌面应用已经启动并完成初始化。MCP 依赖本机录音服务和授权 token。若仍失败，再重启 AI 客户端后重试。
-
-**Q: 提示找不到 npx 命令？**
-
-需要安装 Node.js `>= 18`。访问 [nodejs.org](https://nodejs.org) 下载安装。
-
-**Q: 我在终端里运行 `npx -y record_safer_pro_mcp` 后没有任何输出，是不是安装失败了？**
-
-不是。默认模式就是等待客户端接管的 `stdio` Server。请改用：
+You need Node.js `>= 18`. After installation, confirm:
 
 ```bash
-npx -y record_safer_pro_mcp --version
-npx -y record_safer_pro_mcp --doctor
+node -v
+npx -v
 ```
 
-如果这两个命令能正常输出，说明 npm 包安装和启动链路是正常的。
+**Q: I ran `npx -y record_safer_pro_mcp@latest` in a terminal and it produced no output. Did installation fail?**
+
+No. The default behavior is to start a waiting `stdio` server for the MCP client. Use `--version` and `--doctor` for validation instead of assuming a hang means failure.
 
-**Q: 端口不是 8080 怎么办？**
+**Q: Do I normally need to configure ports manually?**
 
-正常情况下不需要手动处理，应用会自动写入端口文件并自动发现。如果你确实要覆盖目标后端，再设置 `RECORD_SAFER_URL`。
+No. Local ports and tokens are discovered automatically in the normal setup. You only need `RECORD_SAFER_URL` if you intentionally override the backend target.
 
-**Q: 版本不兼容时会怎样？**
+**Q: Why does this README keep emphasizing sending `INSTALL_AI.md` directly to AI?**
 
-当前代码会先做 MCP compatibility handshake。如果桌面端过旧、协议版本不匹配、缺少必需 capability，MCP 会直接报出升级或兼容性错误，而不是静默失败。
+Because that is the most realistic user path for this product. Compared with manual configuration, it is more standardized, more repeatable, and better suited to product delivery and support.
 
 ---
 
-Copyright © DADAO 大道声学（北京大道创响科技有限公司）
+Copyright © DADAO Audio (Beijing Dadao Chuangxiang Technology Co., Ltd.)

package/package.json

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