MCP 配置与文档

• ✓ 安装 Unfour 并至少打开一次桌面应用，让本地数据库完成创建。
• ✓ 创建或选择 MCP 客户端应使用其资源的工作区。
• ✓ 安装支持手动配置本地 stdio Server 的 MCP 客户端。
• ✓ 确保 Settings → MCP 显示的命令可用。Standard 安装使用已安装 sidecar 的路径，Microsoft Store/MSIX 使用稳定的 unfour-mcp.exe execution alias。

1. 1 在 Unfour 中打开 Settings → MCP。
2. 2 在 Codex 区域选择 Configure Codex（推荐）。Unfour 会将 unfour 条目合并到用户主目录下的 ~/.codex/config.toml，并显示状态。
3. 3 配置改变后重启 Codex。

自动配置仅写入该用户级文件，不更新项目配置或自定义 CODEX_HOME。它会保留无关配置、备份已有文件，并拒绝无效 TOML；不会更改工作区权限或发起工具调用。

如需手动配置，请从 Settings → MCP 复制可执行文件路径或别名。以下路径仅为示例，须替换为复制的值。Codex 直接启动可执行文件，Windows 路径含空格时也保持 args 为空。TOML 单引号字面量字符串中的反斜杠无需转义。

[mcp_servers.unfour]
command = 'D:\Program Files\Unfour\unfour-mcp.exe'
args = []

也可使用 TOML 双引号基本字符串，但每个 Windows 反斜杠都必须转义为 \\。两个示例解析为相同路径，只保留一个 unfour 条目。

[mcp_servers.unfour]
command = "D:\\Program Files\\Unfour\\unfour-mcp.exe"
args = []

Microsoft Store/MSIX 安装使用下方稳定执行别名。macOS 或 Linux 请将 Settings → MCP 复制的准确路径写入 command，并保持 args 为空。

[mcp_servers.unfour]
command = "unfour-mcp.exe"
args = []

1. 1 在 Unfour 中打开 Settings → MCP。
2. 2 在 Cursor 区域选择 Configure Cursor（推荐）。Unfour 会将 unfour 条目合并到用户主目录下的 ~/.cursor/mcp.json，并显示状态。
3. 3 配置改变后重启 Cursor。

自动配置仅写入用户级文件，不写入项目的 .cursor/mcp.json。它会保留无关配置、备份已有文件，并拒绝无效 JSON。项目级配置需手动合并：将 unfour 服务条目加入项目文件，不要覆盖其他服务。

手动配置时，在 Settings → MCP 使用 Copy command。Windows 可执行文件路径包含空白字符时，command 使用 cmd.exe，args 使用两个元素：/c 和完整路径字符串。JSON 中每个反斜杠都必须转义为 \\。请将下方示例路径替换为复制的路径，不要按空格拆分，也不要额外嵌入引号字符。

{
  "mcpServers": {
    "unfour": {
      "command": "cmd.exe",
      "args": ["/c", "D:\\Program Files\\Unfour\\unfour-mcp.exe"]
    }
  }
}

这里 /c 和路径是 cmd.exe 的参数；unfour-mcp 本身不接收 CLI 参数。Microsoft Store/MSIX 直接使用下方稳定别名，args 为空。Windows 路径不含空白字符时，以及 macOS/Linux 上，请将复制的可执行文件路径直接写入 command，保持 args 为空，并遵守 JSON 转义规则。

{
  "mcpServers": {
    "unfour": {
      "command": "unfour-mcp.exe",
      "args": []
    }
  }
}

其他支持手动配置本地 stdio Server 的 MCP 兼容客户端也可以连接。

更新后重启 MCP 客户端或其 Unfour 服务，使其加载更新后的程序。选择目标工作区、检查策略，并在修改前列出资源。资源管理属于免费核心能力。

• ✓ 使用 unfour.workspace.create 创建工作区，或用 unfour.workspace.rename 重命名，并传入 workspace.list 返回的 expectedName。创建不会激活新工作区或复制资源；它继承授权工作区的环境类型与 MCP 策略，不接受策略覆盖。
• ✓ 创建、重命名、移动、排序或删除文件夹前，先用 unfour.api.list_folders 查看资源。文件夹只能在同一集合内移动，请求只能在同一工作区内移动；重命名使用 expectedUpdatedAt。递归删除会同时删除子文件夹及请求，应复核范围并完成所需确认。
• ✓ 用 unfour.api.move_request 或 unfour.api.duplicate_request 整理原始已保存请求，无需从脱敏预览重建；这些操作不会发送 HTTP 请求。
• ✓ 用 unfour.db.list_saved_sql 和 get_saved_sql 检查记录，再通过 save_saved_sql 或 delete_saved_sql 管理。更新/删除要求 expectedRevision；更新时省略的字段保留原值。这些工具不会执行 SQL。使用 unfour.db.list_catalogs 和已保存连接发现可用数据库目录。

unfour.ssh.write_file 与 unfour.ssh.patch_file 使用已保存 SSH 连接，并接受工作区策略检查。仅支持普通文件，拒绝已识别的符号链接和目录。复核准确目标与内容，并完成所需确认。

• ✓ write_file 使用 SFTP，不需要终端会话或远端 Python。替换已有文件要求 [email protected] version 1；不支持的服务器会在替换前失败。
• ✓ patch_file 要求通过兼容 POSIX 的 SSH Shell 调用远端 python3，不覆盖默认使用 Windows cmd/PowerShell 的 SSH Shell。
• ✓ 写入内容或补丁查找/替换文本合计不能超过 4 MiB UTF-8 字节；补丁目标与结果文件上限为 16 MiB。
• ✓ 新文件使用 0600 权限。替换保留基本所有者、组和权限，不保留扩展 ACL、属性或硬链接身份。

每次工具调用都要经过目标工作区 MCP 策略检查。默认 auto 策略将 dev 映射为普通读写访问、test 映射为受保护访问、prod 映射为只读并允许安全 SSH 诊断。

• ✓ 只读、破坏性、幂等和开放世界提示描述工具行为，但服务端策略才是最终控制。
• ✓ 策略或后端安全检查要求确认时会返回 CONFIRMATION_REQUIRED。完全访问不保证每个高风险操作都弹出确认；显式工作区策略会覆盖 auto。
• ✓ 复核准确目标和载荷后，客户端使用 confirm=true 与返回的 confirmation_text 重试同一调用。
• ✓ 确认文本与载荷指纹绑定；修改 SQL、URL、命令、路径或补丁内容后需要重新确认。
• ✓ 必要时结果和活动会脱敏。生产环境默认值不会授予自主写入权限。

Flow 工具共用桌面定义、已保存工作区资源和运行历史。明确选择工作区与环境，复核定义和输入后确认运行。即使在 full_access 下，执行 Flow 也需要确认；read_only 会阻止执行，包括只有只读检查的 runbook。取消不会回滚已完成操作，运行期间应保持 MCP 连接。

MCP 与桌面应用使用相同的本地数据库和 command bus。SSH 与数据库凭据在需要时通过 OS secret store 解析。保存的 API 配置有独立的本地存储与快照脱敏边界，不会自动进入钥匙串。

• ✓ MCP 策略阻止 secret-reveal 操作。基于规则的掩码处理不能保证任意日志、查询结果或其他工具输出都不含机密文本。
• ✓ SSH 密码、私钥路径与口令、数据库密码和本地凭据引用都保留在设备上。
• ✓ Cloud Sync 排除连接凭据/引用、设备本地路径、运行历史与标记为 Secret 的变量值，并脱敏可识别的 API 秘密。启用前检查脚本与自由文本，并在每台设备上配置被省略的值。
• ✓ 日常使用不要启用 UNFOUR_MCP_STORAGE_MODE=ephemeral；它会创建仅用于 CI 与协议检查的空内存 Registry。