record_safer_pro_mcp 1.0.30 → 1.0.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +213 -161
  2. package/dist/cli.d.ts.map +1 -1
  3. package/dist/cli.js +3 -1
  4. package/dist/cli.js.map +1 -1
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,177 +1,264 @@
1
- # Record Safer Pro MCP Server
1
+ # Record Safer Pro MCP
2
2
 
3
- [Record Safer Pro](https://www.dadaoaudio.com) 的 AI 接口服务，基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 标准。让 Claude、Kiro、Cursor 等 AI 助手直接控制你的专业多通道录音软件。
3
+ Record Safer Pro 的官方 MCP Server。它让具备本机执行能力的 AI 客户端，可以直接接入专业多通道录音工作流，完成设备发现、录音准备、开始/停止录音、通道调整、标记管理等核心操作。
4
4
 
5
- 由 **DADAO 大道声学（北京大道创响科技有限公司）** 开发。
5
+ 由 **DADAO 大道声学（北京大道创响科技有限公司）** 开发。
6
+ 官网：[www.dadaoaudio.com](https://www.dadaoaudio.com)
6
7
 
7
- ---
8
+ > **推荐安装方式：AI Direct Install**
9
+ >
10
+ > 把 [`INSTALL_AI.md`](./INSTALL_AI.md) 的全文直接发送给你的 AI Agent，并补充一句：
11
+ >
12
+ > `请按这份说明为我安装 Record Safer Pro MCP，只配置我当前正在使用的客户端，完成后执行 doctor 验证并告诉我结果。`
13
+ >
14
+ > 对大多数用户，这就是最快、最稳妥、最接近“零配置”的安装方式。
8
15
 
9
- ## 安装步骤
16
+ ## 为什么优先用 `INSTALL_AI.md`
10
17
 
11
- ### 1. 安装 Node.js
18
+ `INSTALL_AI.md` 不是一份给人手动照着点的普通说明书，而是一份为 AI Agent 编写的可执行安装指令。它的设计目标很明确：让 AI 在尽量少打扰用户的前提下，完成一次可靠、选择性、可验证的 MCP 接入。
12
19
 
13
- 如果你的电脑还没有 Node.js，先去 [nodejs.org](https://nodejs.org) 下载安装（选 LTS 版本即可，需要 >= 18）。
20
+ 它会指导 AI：
14
21
 
15
- 安装完成后打开终端验证：
22
+ - 先识别你当前正在使用的客户端，而不是对所有平台一股脑写配置。
23
+ - 统一使用 `npx -y record_safer_pro_mcp@latest`，避免全局安装、PATH、缓存版本不一致等常见问题。
24
+ - 对 JSON 配置做结构化合并，尽量不破坏现有配置。
25
+ - 在安装完成后执行 `--doctor` 做有效性验证，而不是只停留在“看起来写进去了”。
16
26
 
17
- ```bash
18
- node -v
19
- npx -v
27
+ 如果你的 AI 具备本机命令执行和文件写入能力，这种方式通常比人工逐项配置更快，也更不容易出错。
28
+
29
+ ## 适用对象
30
+
31
+ 这种 AI 直装方式适用于：
32
+
33
+ - Claude Desktop
34
+ - Cursor
35
+ - Gemini CLI
36
+ - OpenCode
37
+ - Kiro
38
+ - Windsurf
39
+
40
+ 前提条件：
41
+
42
+ - 已安装 Node.js `>= 18`
43
+ - 已安装并可启动 Record Safer Pro 桌面应用
44
+ - 你使用的 AI Agent 具备本机终端执行和本地配置文件修改能力
45
+
46
+ ## 标准使用方式
47
+
48
+ 最推荐的做法只有两步：
49
+
50
+ ### 1. 把安装说明直接喂给 AI
51
+
52
+ 打开 [`INSTALL_AI.md`](./INSTALL_AI.md)，将全文粘贴给你的 AI Agent。
53
+
54
+ ### 2. 追加一句明确指令
55
+
56
+ 可以直接使用下面这段话：
57
+
58
+ ```text
59
+ 请按这份 INSTALL_AI.md 为我安装 Record Safer Pro MCP。
60
+ 要求：
61
+ 1. 只配置我当前正在使用或已经安装的 AI 客户端。
62
+ 2. 不要修改我未使用的平台配置。
63
+ 3. 统一使用 npx -y record_safer_pro_mcp@latest。
64
+ 4. 修改 JSON 时保持原文件合法。
65
+ 5. 安装完成后执行 --doctor，并告诉我结果。
20
66
  ```
21
67
 
22
- 两个命令都能输出版本号就说明安装成功。
68
+ 这套方式的核心价值不是“让用户少看文档”，而是把安装本身变成一项可以交付给 AI 的标准化动作。
23
69
 
24
- ### 2. 在 AI 客户端中添加配置
70
+ ## AI 安装完成后应有的结果
25
71
 
26
- 根据你使用的 AI 客户端，将以下配置添加到对应的配置文件中：
72
+ 一个合格的安装结果，通常会同时满足以下几点：
27
73
 
28
- 以下配置默认使用 `stdio` 本地传输，也是 Claude Desktop / Cursor / Kiro 最常见的 MCP 接入方式。
74
+ - AI 只修改了与你当前环境相关的 MCP 配置文件。
75
+ - MCP 启动命令统一为 `npx -y record_safer_pro_mcp@latest`。
76
+ - 需要重启或 reload 的客户端，AI 已明确提示你执行。
77
+ - `npx -y record_safer_pro_mcp@latest --doctor` 返回成功结果。
78
+ - Record Safer Pro 桌面应用可以被正常发现，且无需手动填写本地端口。
29
79
 
30
- #### Claude Desktop
80
+ ## 手动配置
31
81
 
32
- 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
82
+ 只有在你的 AI 无法直接改本机文件，或者你明确希望人工接入时，才建议使用手动方式。
33
83
 
34
- ```json
35
- {
36
- "mcpServers": {
37
- "record-safer-pro": {
38
- "command": "npx",
39
- "args": ["-y", "record_safer_pro_mcp"]
40
- }
41
- }
42
- }
84
+ 当前实际 npm 包名和 CLI 命令名都是：
85
+
86
+ ```bash
87
+ record_safer_pro_mcp
88
+ ```
89
+
90
+ 推荐统一命令：
91
+
92
+ ```bash
93
+ npx -y record_safer_pro_mcp@latest
43
94
  ```
44
95
 
45
- #### Kiro
96
+ 各客户端的常见接入位置如下：
46
97
 
47
- 编辑项目目录下的 `.kiro/settings/mcp.json`：
98
+ | 客户端 | 常见配置位置 | 配置方式 |
99
+ | --- | --- | --- |
100
+ | Gemini CLI | 命令行 | `gemini mcp add record-safer-pro --scope user npx -y record_safer_pro_mcp@latest` |
101
+ | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | 在 `mcpServers` 中加入 `record-safer-pro` |
102
+ | Cursor | `~/.cursor/mcp.json` 或项目内 `.cursor/mcp.json` | 在 `mcpServers` 中加入 `record-safer-pro` |
103
+ | Windsurf | `~/.codeium/windsurf/mcp_config.json` | 在 `mcpServers` 中加入 `record-safer-pro` |
104
+ | Kiro | `~/.kiro/settings/mcp.json` 或项目内 `.kiro/settings/mcp.json` | 在 `mcpServers` 中加入 `record-safer-pro` |
105
+ | OpenCode | `~/.config/opencode/opencode.json(.jsonc)`、项目内 `opencode.json` 或 `.mcp.json` | 在 `mcp` 中加入 `record-safer-pro` |
106
+
107
+ 通用 `stdio` 配置形态如下：
48
108
 
49
109
  ```json
50
110
  {
51
111
  "mcpServers": {
52
112
  "record-safer-pro": {
53
113
  "command": "npx",
54
- "args": ["-y", "record_safer_pro_mcp"]
114
+ "args": ["-y", "record_safer_pro_mcp@latest"]
55
115
  }
56
116
  }
57
117
  }
58
118
  ```
59
119
 
60
- #### Cursor
61
-
62
- 在 Settings → MCP 中添加，或编辑 `.cursor/mcp.json`：
120
+ OpenCode 使用的结构略有不同：
63
121
 
64
122
  ```json
65
123
  {
66
- "mcpServers": {
124
+ "$schema": "https://opencode.ai/config.json",
125
+ "mcp": {
67
126
  "record-safer-pro": {
68
- "command": "npx",
69
- "args": ["-y", "record_safer_pro_mcp"]
127
+ "type": "local",
128
+ "command": ["npx", "-y", "record_safer_pro_mcp@latest"],
129
+ "enabled": true
70
130
  }
71
131
  }
72
132
  }
73
133
  ```
74
134
 
75
- ### 3. 启动 Record Safer Pro
76
-
77
- 确保 Record Safer Pro 桌面应用正在运行，然后重启你的 AI 客户端即可。
78
-
79
- MCP Server 会自动发现本地服务地址，无需手动配置端口。每次启动时会自动获取最新版本，无需手动更新。
135
+ 更完整的平台级安装细节，直接参考 [`INSTALL_AI.md`](./INSTALL_AI.md)。
80
136
 
81
- ### 4. 验证安装是否成功
137
+ ## 安装验证
82
138
 
83
- 如果你想单独验证 npm 包是否安装可用，不要只看 `npx -y record_safer_pro_mcp` 是否“卡住”。
139
+ 不要把终端里运行 `npx -y record_safer_pro_mcp@latest` 后“没有输出”误判为失败。
84
140
 
85
- 这个命令默认会启动 `stdio` MCP Server 并持续等待客户端连接，所以终端看起来像“没有输出”或“正在等待”，这是正常行为，不代表安装失败。
86
-
87
- 建议用下面两个命令做一次性验证：
141
+ 默认模式会启动 `stdio` MCP Server 并持续等待客户端接管，因此终端看起来像“卡住”是正常行为。正确的验证方式是：
88
142
 
89
143
  ```bash
90
- npx -y record_safer_pro_mcp --version
91
- npx -y record_safer_pro_mcp --doctor
144
+ npx -y record_safer_pro_mcp@latest --version
145
+ npx -y record_safer_pro_mcp@latest --doctor
92
146
  ```
93
147
 
94
148
  预期结果：
95
149
 
96
- - `--version` 会输出当前已发布版本
97
- - `--doctor` 会输出 JSON，自检当前 Node 版本与传输模式
150
+ - `--version` 输出当前安装版本
151
+ - `--doctor` 输出诊断结果 JSON
98
152
 
99
- ---
153
+ 如果这两个命令正常，说明安装链路和启动链路基本可用。
154
+
155
+ ## 运行机制
156
+
157
+ 当前默认接入方式是本地 `stdio`。
158
+
159
+ 服务端会自动发现本机 Record Safer Pro 后端地址和授权 token，默认无需手动填写端口。对多数本地用户而言，安装完成后只需要：
160
+
161
+ - 启动 Record Safer Pro 桌面应用
162
+ - 重启或 reload 你的 AI 客户端
163
+ - 直接开始使用自然语言调用录音能力
100
164
 
101
- ## 功能一览
165
+ 当前实际行为：
102
166
 
103
- 安装后，AI 助手可以帮你完成以下操作：
167
+ - 本地默认自动发现 `~/.record_safer` 下的端口和授权 token
168
+ - macOS 下，部分非只读控制操作在后端暂时不可达时，会尝试自动拉起桌面应用
169
+ - 只读查询工具更适合在桌面应用已打开的前提下使用
170
+
171
+ ## 能力范围
172
+
173
+ 当前 MCP Server 聚焦高频核心录音能力，适合在实际录音现场由 AI 协助完成以下工作：
104
174
 
105
175
  | 类别 | 能力 |
106
- |------|------|
107
- | 🧰 录音前准备 | 预览设置、确认设置、打开录音界面 |
108
- | 🎙️ 设备发现 | 列出当前可用音频输入设备 |
109
- | ▶️ 录音控制 | 在已准备好的录音界面中显式开始/停止录音，或定时开始/定时停止/取消定时 |
110
- | 📋 录音状态 | 获取通道、混音、健康状态、最小录音状态 |
111
- | 🎛️ 通道调整 | 重命名通道、调整颜色、调音量、调声像、solo、mute、切换反相 |
112
- | 🏷️ 录音中操作 | 添加标记、查看轨道、查看标记、重命名标记 |
176
+ | --- | --- |
177
+ | 录音前准备 | 预览设置、确认设置、打开录音界面 |
178
+ | 设备发现 | 列出当前可用音频输入设备 |
179
+ | 录音控制 | 开始录音、停止录音、定时开始、定时停止、取消定时 |
180
+ | 录音状态 | 获取通道、混音、健康状态、最小录音状态 |
181
+ | 通道操作 | 重命名通道、调颜色、音量、声像、solo、mute、反相 |
182
+ | 录音中管理 | 添加标记、列出轨道、列出标记、重命名标记 |
183
+
184
+ 当前仅暴露 24 个高频核心工具，不通过 MCP 暴露以下能力：
113
185
 
114
- 当前 MCP Server 已做瘦身，只保留高频核心工具，共 24 个：
186
+ - 系统设置
187
+ - 更新
188
+ - 激活
189
+ - 存储管理
190
+ - 文件分割等扩展功能
115
191
 
116
- - `list_audio_devices`
117
- - `preview_record_mcp_setup`
118
- - `confirm_record_mcp_setup`
119
- - `start_record_mcp`
120
- - `start_recording`
121
- - `schedule_start_recording`
122
- - `schedule_stop_recording`
123
- - `cancel_scheduled_recording`
124
- - `get_channels`
125
- - `get_mix`
126
- - `get_health`
127
- - `get_status`
128
- - `stop_recording`
129
- - `list_tracks`
130
- - `list_markers`
131
- - `add_marker`
132
- - `rename_marker`
133
- - `rename_channel`
134
- - `set_channel_color`
135
- - `set_channel_volume`
136
- - `set_channel_pan`
137
- - `set_channel_solo`
138
- - `set_channel_mute`
139
- - `set_channel_phase_invert`
192
+ ## 关键行为边界
140
193
 
141
- 以下能力目前不再通过 MCP 暴露，必须在 GUI 中手动完成：
194
+ 为了让 AI 在录音流程中表现稳定，以下语义边界很重要：
142
195
 
143
- - 系统设置、更新、激活、存储管理、文件分割等扩展功能
196
+ - `start_record_mcp` 的职责是打开录音界面并准备本次会话，不等于真正开始录音。
197
+ - 真正开始录音需要后续显式调用 `start_recording`。
198
+ - 如果 `get_status` 已返回 `ready=true`，应优先沿用当前已准备好的会话，而不是重复初始化。
199
+ - 如果你没有指定声卡，AI 应先调用 `list_audio_devices`，再让你选择。
200
+ - 如果你没有指定通道，默认使用所选声卡的全部输入通道。
144
201
 
145
- `start_record_mcp` 的职责是“在你确认完整配置后，打开录音界面并准备本次会话”，不是“开始录音”。
146
- 这里确认过的 `recordingMode` 也必须随初始化一起传入后端：`safe` 对应 `safeMode: true`，`studio` 对应 `safeMode: false`。如果用户随后直接确认开始录音而没有改模式，AI 应沿用这次已批准的模式，而不是重新默认成别的模式。
147
- 调用前 AI 必须先把所有录音相关配置一次性完整展示给你确认，不能只展示部分参数：
202
+ 默认录音设置为：
148
203
 
149
- - 必填：`deviceId`、`audioFormat`、`channels`
150
- - 可选：`sampleRate`、`bitDepth`、`outputPath`、`sessionName`、`bufferSize`
151
- - 确认清单必须覆盖：`声卡/音频接口`、`实际录音通道数`、`通道`、`sampleRate`、`bitDepth`、`audioFormat`、`recordingMode`、`outputPath`、`sessionName`、`bufferSize`
152
- - 默认值：`所选声卡全部输入通道`、`所选声卡当前/默认采样率`、`24-bit`、`wav`、`安全模式`、`~/Desktop`
204
+ - 所选声卡当前或默认采样率
205
+ - `24-bit`
206
+ - `wav`
207
+ - 安全模式
208
+ - `~/Desktop`
153
209
 
154
- 如果你没有指定声卡，AI 应先调用 `list_audio_devices`，把可用声卡列出来让你选，而不是先问“有没有麦克风”。
210
+ ## 使用示例
211
+
212
+ 安装完成后，可以直接让 AI 这样操作：
155
213
 
156
- 如果 `list_audio_devices` 返回了多个设备，AI 必须把返回的所有设备都展示出来让你选择，不能只显示内置麦克风这一项。
214
+ - “用 RME Babyface，通道 1-4，WAV，默认 48k/24bit 和桌面路径，帮我打开录音界面并准备录音”
215
+ - “先列出当前可用声卡，我来选一个，然后按默认参数准备录音”
216
+ - “5 分钟后开始录音，并在开始后 30 分钟自动停止”
217
+ - “帮我看一下当前录音健康状态”
218
+ - “我已经在录音界面，把 3 号通道静音”
219
+ - “在当前位置添加一个标记，命名为‘第二段’”
220
+ - “停止录音”
157
221
 
158
- `list_audio_devices` 返回的是当前所有可录音输入设备，包括麦克风、虚拟音频桥接设备、以及硬件音频接口。AI 在让你选设备时，展示出来的可选项数量必须和当前这次工具返回的 `deviceCount` 一致，不能把多项结果压缩成一项“麦克风”。
222
+ ## 本地开发与离线模式
159
223
 
160
- 如果客户端支持 MCP form elicitation，AI 应优先调用 `list_audio_devices` 的点选式设备选择，而不是让你手动输入设备名或输入“第几号”。如果退回到编号列表，用户回复的 `7` 这类裸数字必须按当前这次返回里的 `selectionOptions.displayIndex` 映射，绝不能直接拿去当后端 `deviceId`。
224
+ 如果你在本地开发 `record_safer_mcp`，或者所处环境无法使用 npm 在线拉取包，可以直接指向本地 `dist/index.js`：
161
225
 
162
- 如果你没有指定通道，AI 默认应使用所选声卡的全部输入通道；但在确认清单里展示的“通道数”必须是实际会录进去的通道数，不能直接拿声卡最大通道容量顶替。
226
+ ```bash
227
+ node /absolute/path/to/record_safer_mcp/dist/index.js
228
+ ```
163
229
 
164
- 如果你没有提供可选参数，AI 必须先在确认清单里明确告知默认值和保持应用默认的项，再要求你按回车或回复“确认”后，才会真正调用 `start_record_mcp`。确认时不要出现“使用默认设置”这种选项，用户只能确认当前展示的配置，或者一次性发回修改项。
230
+ 例如 Claude Desktop：
165
231
 
166
- 这一步也不能写成“确认并开始录音”。正确语义是“确认当前设置”或“确认并进入录音界面”，因为真正开始录音仍然是后续动作。
232
+ ```json
233
+ {
234
+ "mcpServers": {
235
+ "record-safer-pro": {
236
+ "command": "node",
237
+ "args": ["/absolute/path/to/record_safer_mcp/dist/index.js"]
238
+ }
239
+ }
240
+ }
241
+ ```
167
242
 
168
- 当录音界面已经准备好，并且状态页明确满足开始条件后，AI 才可以调用 `start_recording`。这一步仍然需要单独的显式确认，不能把“打开录音界面”和“真正开始录音”合并成一次动作。
243
+ 如果你明确要覆盖目标后端地址，再额外设置环境变量，例如：
169
244
 
170
- 如果用户已经手动进入录音控制台，并且 `get_status` / 后端状态已经显示 `ready=true`，AI 必须直接从当前会话继续协助，而不是强制重新走 `preview_record_mcp_setup` → `confirm_record_mcp_setup` → `start_record_mcp`。只有在当前会话并未准备好，或者用户明确要求重配录音设置时，才应该重新从头准备。
245
+ ```json
246
+ {
247
+ "mcpServers": {
248
+ "record-safer-pro": {
249
+ "command": "node",
250
+ "args": ["/absolute/path/to/record_safer_mcp/dist/index.js"],
251
+ "env": {
252
+ "RECORD_SAFER_URL": "http://127.0.0.1:你的端口号"
253
+ }
254
+ }
255
+ }
256
+ }
257
+ ```
171
258
 
172
259
  ## Streamable HTTP 远程模式
173
260
 
174
- 为了兼容 OpenAI Developer Mode / remote MCP 场景，服务端现在也支持可选的 `Streamable HTTP` 传输。
261
+ 当前代码也支持可选的 `streamable-http` 传输，适用于 OpenAI Developer Mode 或需要远程暴露 MCP 的场景。
175
262
 
176
263
  默认环境变量：
177
264
 
@@ -180,88 +267,53 @@ npx -y record_safer_pro_mcp --doctor
180
267
  - `RECORD_SAFER_MCP_HTTP_PORT=3010`
181
268
  - `RECORD_SAFER_MCP_HTTP_PATH=/mcp`
182
269
 
183
- 如果你要切到远程模式：
270
+ 示例：
184
271
 
185
272
  ```bash
186
273
  RECORD_SAFER_MCP_TRANSPORT=streamable-http \
187
274
  RECORD_SAFER_MCP_HTTP_HOST=127.0.0.1 \
188
275
  RECORD_SAFER_MCP_HTTP_PORT=3010 \
189
- npx record_safer_pro_mcp
276
+ npx -y record_safer_pro_mcp@latest
190
277
  ```
191
278
 
192
- 启动后默认端点是：
279
+ 启动后默认端点：
193
280
 
194
281
  - MCP: `http://127.0.0.1:3010/mcp`
195
282
  - Health: `http://127.0.0.1:3010/healthz`
196
283
 
197
284
  安全约束：
198
285
 
199
- - 当 `RECORD_SAFER_MCP_HTTP_HOST` 是非回环地址（例如 `0.0.0.0`）时，必须同时设置 `RECORD_SAFER_MCP_HTTP_BEARER_TOKEN`
200
- - 可选设置 `RECORD_SAFER_MCP_HTTP_ALLOWED_HOSTS=your-domain.com,localhost` 来限制允许的 Host 头
201
- - 本地调试可以直接使用 `http://127.0.0.1:3010/mcp`
202
- - 如果要给公网客户端或 OpenAI Developer Mode 远程接入使用，必须通过 HTTPS 对外暴露；建议放在 HTTPS 反向代理之后，不要直接裸露 HTTP 端口
203
-
204
- 带鉴权的示例：
205
-
206
- ```bash
207
- RECORD_SAFER_MCP_TRANSPORT=streamable-http \
208
- RECORD_SAFER_MCP_HTTP_HOST=0.0.0.0 \
209
- RECORD_SAFER_MCP_HTTP_PORT=3010 \
210
- RECORD_SAFER_MCP_HTTP_BEARER_TOKEN=replace-with-a-long-random-token \
211
- RECORD_SAFER_MCP_HTTP_ALLOWED_HOSTS=your-domain.com \
212
- npx record_safer_pro_mcp
213
- ```
214
-
215
- ## 使用示例
216
-
217
- 配置完成后，你可以直接用自然语言让 AI 操作 Record Safer Pro：
218
-
219
- - "用 RME Babyface，通道 1-4，WAV，默认 48k/24bit 和桌面路径，帮我打开录音界面并准备录音"
220
- - "帮我开始一个录音，先列出当前可用声卡让我选择；如果我没特别说明，就按 wav、24-bit、安全模式和桌面路径准备"
221
- - "5 分钟后开始录音，并在开始后 30 分钟自动停止"
222
- - "帮我列出当前所有音频输入设备"
223
- - "现在有哪些通道？"
224
- - "帮我看一下当前录音健康状态"
225
- - "我已经在录音控制台了，直接帮我开始录音"
226
- - "我已经进了录音界面，把 3 号通道静音"
227
- - "在当前位置添加一个标记，命名为'第二段'"
228
- - "把 3 号通道改名为 Vocal"
229
- - "列出当前所有标记"
230
- - "停止录音"
286
+ - 当 `RECORD_SAFER_MCP_HTTP_HOST` 为非回环地址，例如 `0.0.0.0`，必须同时设置 `RECORD_SAFER_MCP_HTTP_BEARER_TOKEN`
287
+ - 可选使用 `RECORD_SAFER_MCP_HTTP_ALLOWED_HOSTS` 限制允许的 Host
288
+ - 对公网客户端暴露时，必须通过 HTTPS 反向代理对外提供服务
289
+ - 如果 `RECORD_SAFER_URL` 指向非回环地址，默认不会把本机 `~/.record_safer/auth_token` 自动发送到远端
231
290
 
232
291
  ## 常见问题
233
292
 
234
293
  **Q: AI 提示无法连接 Record Safer Pro？**
235
- 确保 Record Safer Pro 桌面应用已启动并完成初始化。MCP Server 需要本地录音服务处于可用状态后才能工作。
236
294
 
237
- **Q: 提示找不到 npx 命令？**
238
- 需要安装 Node.js >= 18。访问 https://nodejs.org 下载安装。
295
+ 先确认 Record Safer Pro 桌面应用已经启动并完成初始化。MCP 依赖本机录音服务和授权 token。若仍失败，重启 AI 客户端后再重试。
296
+
297
+ **Q: 提示找不到 `npx` 命令？**
239
298
 
240
- **Q: 我在终端里运行 `npx -y record_safer_pro_mcp` 后没有任何输出，是不是安装失败了？**
241
- 不是。默认模式是 `stdio` MCP Server，会一直等待 Claude / Cursor / Kiro 之类的客户端接管。请改用：
299
+ 需要先安装 Node.js `>= 18`。安装完成后确认：
242
300
 
243
301
  ```bash
244
- npx -y record_safer_pro_mcp --version
245
- npx -y record_safer_pro_mcp --doctor
302
+ node -v
303
+ npx -v
246
304
  ```
247
305
 
248
- 如果这两个命令能正常输出，说明 npm 包安装和启动链路是正常的。
306
+ **Q: 我在终端运行 `npx -y record_safer_pro_mcp@latest` 后没有任何输出，是不是安装失败了？**
249
307
 
250
- **Q: 端口不是 8080 怎么办？**
251
- 正常情况下不需要手动处理，应用会自动写入端口文件。如果确实需要手动指定，设置环境变量：
252
- ```json
253
- {
254
- "mcpServers": {
255
- "record-safer-pro": {
256
- "command": "npx",
257
- "args": ["-y", "record_safer_pro_mcp"],
258
- "env": {
259
- "RECORD_SAFER_URL": "http://127.0.0.1:你的端口号"
260
- }
261
- }
262
- }
263
- }
264
- ```
308
+ 不是。默认行为就是等待客户端接管的 `stdio` Server。请使用 `--version` 和 `--doctor` 验证，而不是直接通过“是否卡住”来判断。
309
+
310
+ **Q: 正常情况下需要手动配置端口吗？**
311
+
312
+ 不需要。默认会自动发现本机端口和 token。只有在你明确覆盖目标后端时，才需要设置 `RECORD_SAFER_URL`。
313
+
314
+ **Q: 为什么 README 反复强调把 `INSTALL_AI.md` 直接发给 AI？**
315
+
316
+ 因为这是目前最贴近真实用户路径的安装方式。相比人工阅读后再逐步配置，它更标准化、更可复制，也更适合产品交付和团队支持。
265
317
 
266
318
  ---
267
319
 
package/dist/cli.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AA6BvD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,UAAU,GAAG,SAAS,CAoC/E;AAkBD,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,GAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAkB,EAC1D,MAAM,GAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAkB,GACzD,OAAO,CAAC,OAAO,CAAC,CAelB"}
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AA+BvD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,UAAU,GAAG,SAAS,CAoC/E;AAkBD,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,GAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAkB,EAC1D,MAAM,GAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAkB,GACzD,OAAO,CAAC,OAAO,CAAC,CAelB"}
package/dist/cli.js CHANGED
@@ -11,7 +11,9 @@ Usage:
11
11
  Notes:
12
12
  - Running without arguments starts a stdio MCP server and waits for the client.
13
13
  - In a normal terminal this often appears idle with no output while it waits for a client, which is expected.
14
- - Typical client config uses: npx -y record_safer_pro_mcp`;
14
+ - Official npm package and CLI command name: record_safer_pro_mcp
15
+ - Standard local MCP client config uses: command "npx", args ["-y", "record_safer_pro_mcp"]
16
+ - OpenCode config uses: ["npx", "-y", "record_safer_pro_mcp"]`;
15
17
  function buildDoctorReport(context) {
16
18
  return JSON.stringify({
17
19
  ok: true,
package/dist/cli.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAcpD,MAAM,SAAS,GAAG;;;;;;;;;;;;;gEAa8C,CAAC;AAEjE,SAAS,iBAAiB,CAAC,OAAmB;IAC5C,OAAO,IAAI,CAAC,SAAS,CACnB;QACE,EAAE,EAAE,IAAI;QACR,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,EACD,IAAI,EACJ,CAAC,CACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAc,EAAE,OAAmB;IAClE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAExB,IAAI,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC/C,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,GAAG,SAAS,IAAI;YACtB,QAAQ,EAAE,CAAC;SACZ,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAClD,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,OAAO,IAAI;YACnD,QAAQ,EAAE,CAAC;SACZ,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,KAAK,UAAU,EAAE,CAAC;QAC5B,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,GAAG,iBAAiB,CAAC,OAAO,CAAC,IAAI;YACvC,QAAQ,EAAE,CAAC;SACZ,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,IAAI,EAAE,qBAAqB,QAAQ,OAAO,SAAS,IAAI;QACvD,QAAQ,EAAE,CAAC;KACZ,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,kBAAkB;IAC/B,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnE,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,CAGpE,CAAC;IACF,MAAM,aAAa,GAAG,oBAAoB,EAAE,CAAC;IAE7C,OAAO;QACL,WAAW,EAAE,WAAW,CAAC,IAAI,IAAI,sBAAsB;QACvD,OAAO,EAAE,WAAW,CAAC,OAAO,IAAI,OAAO;QACvC,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;QAClC,SAAS,EAAE,aAAa,CAAC,SAAS;KACnC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAc,EACd,SAA4C,OAAO,CAAC,MAAM,EAC1D,SAA4C,OAAO,CAAC,MAAM;IAE1D,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,EAAE,MAAM,kBAAkB,EAAE,CAAC,CAAC;IAElE,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "record_safer_pro_mcp",
3
- "version": "1.0.30",
3
+ "version": "1.0.32",
4
4
  "description": "Record Safer Pro MCP Server — 专业多通道录音工作流 AI 控制接口 / AI control interface for professional multichannel recording workflows",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",