Record Safer Pro MCP

Language: 中文 | English

中文

Record Safer Pro 的官方 MCP Server。它让具备本机执行能力的 AI 客户端，可以直接接入专业多通道录音工作流，完成设备发现、录音准备、开始/停止录音、通道调整、标记管理等核心操作。

由 DADAO 大道声学（北京大道创响科技有限公司） 开发。
官网：www.dadaoaudio.com

推荐安装方式：AI Direct Install

把 INSTALL_AI.md 的全文直接发送给你的 AI Agent，并补充一句：

请按这份说明为我安装 Record Safer Pro MCP，只配置我当前正在使用的客户端，完成后执行 doctor 验证并告诉我结果。

对大多数用户，这就是最快、最稳妥、最接近“零配置”的安装方式。

为什么优先用 INSTALL_AI.md

INSTALL_AI.md 不是一份给人手动照着点的普通说明书，而是一份为 AI Agent 编写的可执行安装指令。它的设计目标很明确：让 AI 在尽量少打扰用户的前提下，完成一次可靠、选择性、可验证的 MCP 接入。

它会指导 AI：

• 先识别你当前正在使用的客户端，而不是对所有平台一股脑写配置
• 统一使用 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，将全文粘贴给你的 AI Agent。

2. 追加一句明确指令

可以直接使用下面这段话：

请按这份 INSTALL_AI.md 为我安装 Record Safer Pro MCP。
要求：
1. 只配置我当前正在使用或已经安装的 AI 客户端。
2. 不要修改我未使用的平台配置。
3. 统一使用 npx -y record_safer_pro_mcp@latest。
4. 修改 JSON 时保持原文件合法。
5. 安装完成后执行 --doctor，并告诉我结果。

这套方式的核心价值不是“让用户少看文档”，而是把安装本身变成一项可以交付给 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 无法直接改本机文件，或者你明确希望人工接入时，才建议使用手动方式。

当前实际 npm 包名和 CLI 命令名都是：

record_safer_pro_mcp

推荐统一命令：

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 配置形态如下：

{
  "mcpServers": {
    "record-safer-pro": {
      "command": "npx",
      "args": ["-y", "record_safer_pro_mcp@latest"]
    }
  }
}

OpenCode 使用的结构略有不同：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "record-safer-pro": {
      "type": "local",
      "command": ["npx", "-y", "record_safer_pro_mcp@latest"],
      "enabled": true
    }
  }
}

更完整的平台级安装细节，直接参考 INSTALL_AI.md。

安装验证

不要把终端里运行 npx -y record_safer_pro_mcp@latest 后“没有输出”误判为失败。

默认模式会启动 stdio MCP Server 并持续等待客户端接管，因此终端看起来像“卡住”是正常行为。正确的验证方式是：

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 这样操作：

• “用 RME Babyface，通道 1-4，WAV，默认 48k/24bit 和桌面路径，帮我打开录音界面并准备录音”
• “先列出当前可用声卡，我来选一个，然后按默认参数准备录音”
• “5 分钟后开始录音，并在开始后 30 分钟自动停止”
• “帮我看一下当前录音健康状态”
• “我已经在录音界面，把 3 号通道静音”
• “在当前位置添加一个标记，命名为‘第二段’”
• “停止录音”

本地开发与离线模式

如果你在本地开发 record_safer_mcp，或者所处环境无法使用 npm 在线拉取包，可以直接指向本地 dist/index.js：

node /absolute/path/to/record_safer_mcp/dist/index.js

例如 Claude Desktop：

{
  "mcpServers": {
    "record-safer-pro": {
      "command": "node",
      "args": ["/absolute/path/to/record_safer_mcp/dist/index.js"]
    }
  }
}

如果你明确要覆盖目标后端地址，再额外设置环境变量，例如：

{
  "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:你的端口号"
      }
    }
  }
}

Streamable HTTP 远程模式

当前代码也支持可选的 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

示例：

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 自动发送到远端

常见问题

Q: AI 提示无法连接 Record Safer Pro？

先确认 Record Safer Pro 桌面应用已经启动并完成初始化。MCP 依赖本机录音服务和授权 token。若仍失败，重启 AI 客户端后再重试。

Q: 提示找不到 npx 命令？

需要先安装 Node.js >= 18。安装完成后确认：

node -v
npx -v

Q: 我在终端运行 npx -y record_safer_pro_mcp@latest 后没有任何输出，是不是安装失败了？

不是。默认行为就是等待客户端接管的 stdio Server。请使用 --version 和 --doctor 验证，而不是直接通过“是否卡住”来判断。

Q: 正常情况下需要手动配置端口吗？

不需要。默认会自动发现本机端口和 token。只有在你明确覆盖目标后端时，才需要设置 RECORD_SAFER_URL。

Q: 为什么 README 反复强调把 INSTALL_AI.md 直接发给 AI？

因为这是目前最贴近真实用户路径的安装方式。相比人工阅读后再逐步配置，它更标准化、更可复制，也更适合产品交付和团队支持。

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

Recommended installation path: AI Direct Install

Send the full contents of 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 and paste the full file into your AI agent.

2. Add an explicit execution instruction

You can use this exact prompt:

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:

record_safer_pro_mcp

Recommended standard command:

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:

{
  "mcpServers": {
    "record-safer-pro": {
      "command": "npx",
      "args": ["-y", "record_safer_pro_mcp@latest"]
    }
  }
}

OpenCode uses a slightly different structure:

{
  "$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.

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:

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:

node /absolute/path/to/record_safer_mcp/dist/index.js

Claude Desktop example:

{
  "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:

{
  "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:

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:

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.)