record_safer_pro_mcp 1.0.32 → 1.0.33

package/README.md

@@ -1,5 +1,10 @@
 # Record Safer Pro MCP
 
+Language: [中文](#zh-cn) | [English](#english)
+
+<a id="zh-cn"></a>
+## 中文
+
 Record Safer Pro 的官方 MCP Server。它让具备本机执行能力的 AI 客户端，可以直接接入专业多通道录音工作流，完成设备发现、录音准备、开始/停止录音、通道调整、标记管理等核心操作。
 
 由 **DADAO 大道声学（北京大道创响科技有限公司）** 开发。  
@@ -13,20 +18,20 @@ Record Safer Pro 的官方 MCP Server。它让具备本机执行能力的 AI 客
 >
 > 对大多数用户，这就是最快、最稳妥、最接近“零配置”的安装方式。
 
-## 为什么优先用 `INSTALL_AI.md`
+### 为什么优先用 `INSTALL_AI.md`
 
 `INSTALL_AI.md` 不是一份给人手动照着点的普通说明书，而是一份为 AI Agent 编写的可执行安装指令。它的设计目标很明确：让 AI 在尽量少打扰用户的前提下，完成一次可靠、选择性、可验证的 MCP 接入。
 
 它会指导 AI：
 
-- 先识别你当前正在使用的客户端，而不是对所有平台一股脑写配置。
-- 统一使用 `npx -y record_safer_pro_mcp@latest`，避免全局安装、PATH、缓存版本不一致等常见问题。
-- 对 JSON 配置做结构化合并，尽量不破坏现有配置。
-- 在安装完成后执行 `--doctor` 做有效性验证，而不是只停留在“看起来写进去了”。
+- 先识别你当前正在使用的客户端，而不是对所有平台一股脑写配置
+- 统一使用 `npx -y record_safer_pro_mcp@latest`，避免全局安装、PATH、缓存版本不一致等常见问题
+- 对 JSON 配置做结构化合并，尽量不破坏现有配置
+- 在安装完成后执行 `--doctor` 做有效性验证，而不是只停留在“看起来写进去了”
 
 如果你的 AI 具备本机命令执行和文件写入能力，这种方式通常比人工逐项配置更快，也更不容易出错。
 
-## 适用对象
+### 适用对象
 
 这种 AI 直装方式适用于：
 
@@ -43,15 +48,15 @@ Record Safer Pro 的官方 MCP Server。它让具备本机执行能力的 AI 客
 - 已安装并可启动 Record Safer Pro 桌面应用
 - 你使用的 AI Agent 具备本机终端执行和本地配置文件修改能力
 
-## 标准使用方式
+### 标准使用方式
 
 最推荐的做法只有两步：
 
-### 1. 把安装说明直接喂给 AI
+#### 1. 把安装说明直接喂给 AI
 
 打开 [`INSTALL_AI.md`](./INSTALL_AI.md)，将全文粘贴给你的 AI Agent。
 
-### 2. 追加一句明确指令
+#### 2. 追加一句明确指令
 
 可以直接使用下面这段话：
 
@@ -67,17 +72,17 @@ Record Safer Pro 的官方 MCP Server。它让具备本机执行能力的 AI 客
 
 这套方式的核心价值不是“让用户少看文档”，而是把安装本身变成一项可以交付给 AI 的标准化动作。
 
-## AI 安装完成后应有的结果
+### AI 安装完成后应有的结果
 
 一个合格的安装结果，通常会同时满足以下几点：
 
-- AI 只修改了与你当前环境相关的 MCP 配置文件。
-- MCP 启动命令统一为 `npx -y record_safer_pro_mcp@latest`。
-- 需要重启或 reload 的客户端，AI 已明确提示你执行。
-- `npx -y record_safer_pro_mcp@latest --doctor` 返回成功结果。
-- Record Safer Pro 桌面应用可以被正常发现，且无需手动填写本地端口。
+- AI 只修改了与你当前环境相关的 MCP 配置文件
+- MCP 启动命令统一为 `npx -y record_safer_pro_mcp@latest`
+- 需要重启或 reload 的客户端，AI 已明确提示你执行
+- `npx -y record_safer_pro_mcp@latest --doctor` 返回成功结果
+- Record Safer Pro 桌面应用可以被正常发现，且无需手动填写本地端口
 
-## 手动配置
+### 手动配置
 
 只有在你的 AI 无法直接改本机文件，或者你明确希望人工接入时，才建议使用手动方式。
 
@@ -134,7 +139,7 @@ OpenCode 使用的结构略有不同：
 
 更完整的平台级安装细节，直接参考 [`INSTALL_AI.md`](./INSTALL_AI.md)。
 
-## 安装验证
+### 安装验证
 
 不要把终端里运行 `npx -y record_safer_pro_mcp@latest` 后“没有输出”误判为失败。
 
@@ -152,7 +157,7 @@ npx -y record_safer_pro_mcp@latest --doctor
 
 如果这两个命令正常，说明安装链路和启动链路基本可用。
 
-## 运行机制
+### 运行机制
 
 当前默认接入方式是本地 `stdio`。
 
@@ -168,7 +173,7 @@ npx -y record_safer_pro_mcp@latest --doctor
 - macOS 下，部分非只读控制操作在后端暂时不可达时，会尝试自动拉起桌面应用
 - 只读查询工具更适合在桌面应用已打开的前提下使用
 
-## 能力范围
+### 能力范围
 
 当前 MCP Server 聚焦高频核心录音能力，适合在实际录音现场由 AI 协助完成以下工作：
 
@@ -189,15 +194,15 @@ npx -y record_safer_pro_mcp@latest --doctor
 - 存储管理
 - 文件分割等扩展功能
 
-## 关键行为边界
+### 关键行为边界
 
 为了让 AI 在录音流程中表现稳定，以下语义边界很重要：
 
-- `start_record_mcp` 的职责是打开录音界面并准备本次会话，不等于真正开始录音。
-- 真正开始录音需要后续显式调用 `start_recording`。
-- 如果 `get_status` 已返回 `ready=true`，应优先沿用当前已准备好的会话，而不是重复初始化。
-- 如果你没有指定声卡，AI 应先调用 `list_audio_devices`，再让你选择。
-- 如果你没有指定通道，默认使用所选声卡的全部输入通道。
+- `start_record_mcp` 的职责是打开录音界面并准备本次会话，不等于真正开始录音
+- 真正开始录音需要后续显式调用 `start_recording`
+- 如果 `get_status` 已返回 `ready=true`，应优先沿用当前已准备好的会话，而不是重复初始化
+- 如果你没有指定声卡，AI 应先调用 `list_audio_devices`，再让你选择
+- 如果你没有指定通道，默认使用所选声卡的全部输入通道
 
 默认录音设置为：
 
@@ -207,7 +212,7 @@ npx -y record_safer_pro_mcp@latest --doctor
 - 安全模式
 - `~/Desktop`
 
-## 使用示例
+### 使用示例
 
 安装完成后，可以直接让 AI 这样操作：
 
@@ -219,7 +224,7 @@ npx -y record_safer_pro_mcp@latest --doctor
 - “在当前位置添加一个标记，命名为‘第二段’”
 - “停止录音”
 
-## 本地开发与离线模式
+### 本地开发与离线模式
 
 如果你在本地开发 `record_safer_mcp`，或者所处环境无法使用 npm 在线拉取包，可以直接指向本地 `dist/index.js`：
 
@@ -256,7 +261,7 @@ node /absolute/path/to/record_safer_mcp/dist/index.js
 }
 ```
 
-## Streamable HTTP 远程模式
+### Streamable HTTP 远程模式
 
 当前代码也支持可选的 `streamable-http` 传输，适用于 OpenAI Developer Mode 或需要远程暴露 MCP 的场景。
 
@@ -288,7 +293,7 @@ npx -y record_safer_pro_mcp@latest
 - 对公网客户端暴露时，必须通过 HTTPS 反向代理对外提供服务
 - 如果 `RECORD_SAFER_URL` 指向非回环地址，默认不会把本机 `~/.record_safer/auth_token` 自动发送到远端
 
-## 常见问题
+### 常见问题
 
 **Q: AI 提示无法连接 Record Safer Pro？**
 
@@ -317,4 +322,324 @@ npx -v
 
 ---
 
-Copyright © DADAO 大道声学（北京大道创响科技有限公司）
+<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": "npx",
+      "args": ["-y", "record_safer_pro_mcp@latest"]
+    }
+  }
+}
+```
+
+OpenCode uses a slightly different structure:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "record-safer-pro": {
+      "type": "local",
+      "command": ["npx", "-y", "record_safer_pro_mcp@latest"],
+      "enabled": true
+    }
+  }
+}
+```
+
+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
+{
+  "mcpServers": {
+    "record-safer-pro": {
+      "command": "node",
+      "args": ["/absolute/path/to/record_safer_mcp/dist/index.js"],
+      "env": {
+        "RECORD_SAFER_URL": "http://127.0.0.1:your-port"
+      }
+    }
+  }
+}
+```
+
+### Streamable HTTP Remote Mode
+
+The current codebase also supports optional `streamable-http` transport for OpenAI Developer Mode and other remote MCP deployment scenarios.
+
+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@latest
+```
+
+Default endpoints after launch:
+
+- MCP: `http://127.0.0.1:3010/mcp`
+- Health: `http://127.0.0.1:3010/healthz`
+
+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
+
+### FAQ
+
+**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: `npx` is not found. What does that mean?**
+
+You need Node.js `>= 18`. After installation, confirm:
+
+```bash
+node -v
+npx -v
+```
+
+**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: Do I normally need to configure ports manually?**
+
+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: Why does this README keep emphasizing sending `INSTALL_AI.md` directly to AI?**
+
+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 Audio (Beijing Dadao Chuangxiang Technology Co., Ltd.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "record_safer_pro_mcp",
-  "version": "1.0.32",
+  "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",