AI Agent 集成指南

语言 / Language：简体中文 · English

RustFox 内置 Agent 控制面：应用启动时自动拉起一个本机 HTTP 服务（仅 127.0.0.1）， AI Agent 可以直接把 cURL 命令保存为 RustFox 接口，也可以查询项目与接口列表。

两种接入方式：

1. 工作原理

AI Agent ──(stdio MCP)──→ rustfox-mcp ──┐
                                        ├──→ Agent 控制面 (127.0.0.1:4110~4129)
AI Agent ──(HTTP + Bearer token)────────┘         │
                                             SQLite 落库 → UI 实时刷新

• 控制面随 RustFox 桌面应用启动自动拉起，无需手动开启；
• 端口从 4110 起自动探测（避开 Mock 的 4010 段）；
• 所有请求需携带令牌：Authorization: Bearer <token> 或 X-Agent-Token。

2. 找到你的 Token

Token 是控制面的访问凭证，首次启动应用时自动生成：

• 文件位置：{数据目录}/agent-token（权限 0600）
• 数据目录：
  • Windows：%APPDATA%\RustFox\agent-token
  • Linux：~/.local/share/RustFox/agent-token
• 应用内也可确认：顶栏「设置」旁无入口时，可在 DevTools Console 执行 await __TAURI_INTERNALS__.invoke('plugin:fox|agent_status') 查看 tokenPath。

开发构建（tauri dev）使用 RustFox-dev 目录，与正式版隔离。

3. 方式一：MCP Server

3.1 获取 rustfox-mcp

v0.0.10 起，安装包已内置 rustfox-mcp，按平台取对应路径即可：

git clone https://github.com/weihubeats/RustFox.git
cd RustFox && cargo build --release -p fox-mcp
# 产物：target/release/rustfox-mcp
sudo cp target/release/rustfox-mcp /usr/local/bin/   # 可选：放进 PATH

3.2 配置客户端

v0.0.10+ 安装包的二进制不在 PATH，推荐直接填 §3.1 表中绝对路径（macOS 安装包常见坑：裸 rustfox-mcp 报 spawn ... ENOENT）。仅在已加入 PATH 时才能写裸命令。

Claude Code — 项目根目录 .mcp.json：

{
  "mcpServers": {
    "rustfox": { "command": "/Applications/RustFox.app/Contents/MacOS/rustfox-mcp" }
  }
}

开发模式（tauri dev）或已在 PATH，则可写：

{ "command": "rustfox-mcp" }

Cursor — Settings → MCP → Add Server，Command 填绝对路径 /Applications/RustFox.app/Contents/MacOS/rustfox-mcp（macOS）或对应平台路径。

配置后重启客户端 / 重载会话，工具列表出现 4 个工具即成功：

之后对话里说「把这个 curl 存到 RustFox」即可；导入成功桌面端侧栏自动刷新并弹提示。

3.3 save_curl 参数说明

导入行为：

• URL 拆解为 base_url + 路径 + query 参数（与手动 cURL 导入一致），接口状态为「设计中」草稿；
• 项目变量 base_url 缺失时自动写入本次 URL 的 origin；
• 已有不同 base_url 时不覆盖，响应带 warning 字段，Agent 会转达。

3.4 使用示例

① 已有 cURL，一句话入库（Claude Code / Cursor 通用）：

把这个 curl 存到 RustFox：
curl -X POST https://api.example.com/orders \
  -H "Content-Type: application/json" \
  -d '{"userId":1,"amount":99}'

② Java 代码里直接让 AI 存接口：贴出 Controller 代码（或 Cursor 选中方法），AI 自动构造 cURL 并调用 save_curl：

把下面这个接口保存到 RustFox：
@PostMapping("/orders")
public Result<Long> createOrder(@RequestBody CreateOrderReq req) {
    return orderService.create(req);
}

用中文汇报结果：POST /orders 已保存，base_url 推导为 ...，接口名缺省为 orders。

③ 指定项目 / 文件夹：先 list_projects 拿到 projectId，再导入到目标项目：

list_projects 里找 projectId，然后 save_curl：
curl -X POST http://127.0.0.1:8080/api/users -d '{"name":"foo"}' name="创建用户" projectId=<projectId>

多项目库时若漏填 projectId，save_curl 会报错并列出候选，照抄 projectId 重试即可。

4. 方式二：直接 HTTP

适合自研脚本或暂不支持 MCP 的 Agent。

示例：

TOKEN=$(cat "$HOME/Library/Application Support/RustFox/agent-token")
curl -s http://127.0.0.1:4110/agent/curl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"curl -X POST -H \"Content-Type: application/json\" -d \"{\\\"a\\\":1}\" https://api.example.com/orders"}'

字段同时接受 camelCase 与 snake_case（projectId / project_id）。 错误体统一 {code, message}：VALIDATION(400) / NOT_FOUND(404) / UNAUTHORIZED(401)。

5. 安全设计

• 只绑定 127.0.0.1，外网不可达；
• 随机 UUID 令牌，文件权限 0600；
• 写操作仅限「导入接口」一种，不可删除/修改已有数据；
• 不读取密钥环中的加密环境变量明文。

6. 排障

在 GitHub 上查看本页源文