登录 English

MCP

MCP 配置与文档

Unfour 运行本地 stdio MCP 服务，让兼容客户端通过与桌面应用相同的命令与策略边界，使用已授权且限定于工作区的 API、SSH、数据库、活动和系统能力。

使用要求

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

配置 Codex

  1. 在 Unfour 中打开 Settings → MCP。
  2. 在 Codex 区域选择 Configure Codex。Unfour 会检测已安装 MCP 命令、安全合并 Codex 配置，并显示状态。
  3. 配置改变后重启 Codex。

如需手动配置，请在 Settings → MCP 选择 Copy command，用该值替换下面占位符，再加入 Codex TOML 配置。

Codex config.toml
[mcp_servers.unfour]
command = "PASTE_COMMAND_FROM_SETTINGS_MCP"
args = []

配置 Cursor

  1. 在 Unfour 中打开 Settings → MCP。
  2. 在 Cursor 区域选择 Configure Cursor。Unfour 会检测并安全合并项目或用户级 MCP 配置。
  3. 配置改变后重启 Cursor。

如需手动配置，请选择 Copy command 并替换下面占位符。项目级配置保存到 .cursor/mcp.json，用户级配置保存到 ~/.cursor/mcp.json。

Cursor mcp.json
{
  "mcpServers": {
    "unfour": {
      "command": "PASTE_COMMAND_FROM_SETTINGS_MCP",
      "args": []
    }
  }
}

其他 MCP 客户端

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

能力范围

Workspace

检查当前工作区并管理受支持的工作区变量。代表工具包括 unfour.workspace.current 和 unfour.workspace.list_variables。

API

检查保存的请求和已脱敏历史，并发送已授权请求。代表工具包括 unfour.api.list_requests 和 unfour.api.send_request。

SSH

检查历史与任务、运行诊断或命令，并按策略读写远程文件。代表工具包括 unfour.ssh.list_history 和 unfour.ssh.run_diagnostic。

Database

列出保存的连接、浏览结构、运行只读查询或 explain，并执行受策略控制的 SQL。代表工具包括 unfour.db.list_connections 和 unfour.db.query_readonly。

Activity / System

通过 unfour.activity.list 与 unfour.system.health 查看近期已脱敏活动和存储就绪状态。

权限与确认

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

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

凭据与本地优先边界

MCP 进程打开与桌面应用相同的本地 Unfour 数据库，并仅在保存的 API、SSH 或数据库操作确实需要时，从操作系统凭据存储解析凭据。

  • MCP 工具不会返回原始凭据值。
  • SSH 密码、私钥路径与口令、数据库密码和本地凭据引用都保留在设备上。
  • Cloud Sync 不同步秘密、凭据引用、本地路径或运行历史；这些值需要在每台设备上单独配置。
  • 日常使用不要启用 UNFOUR_MCP_STORAGE_MODE=ephemeral；它会创建仅用于 CI 与协议检查的空内存 Registry。

常见问题排查

客户端找不到 Unfour

先打开一次 Unfour，确认 Settings → MCP 中 MCP 命令可用，再重新配置客户端并重启。

命令或配置错误

从 Settings → MCP 复制当前命令，保持 args 为空，并移除旧开发路径或 WindowsApps 路径。

看不到本地数据

先启动桌面应用，并确认客户端使用相同的 Stable、Test 或 Dev 存储 Profile；不要使用 ephemeral 模式。

配置已改变

重启 MCP 客户端，使其用更新后的命令启动新的 stdio 进程。

工具被阻止

检查当前工作区、环境、显式 MCP 策略，以及动作是只读、受保护还是需要确认。