persistent-chat-plugin/docs/MCP_SETUP.md

# MCP 配置（MCP_SETUP.md）

> Trae / Cursor 接入持久对话 MCP 插件的完整配置

---

## 1. Trae CN（macOS）

### 配置文件位置

```
~/.trae/mcp.json
```

### 完整配置

```json
{
  "mcpServers": {
    "persistent-chat": {
      "type": "stdio",
      "command": "/Users/karuo/.persistent-chat-local/ensure-hub.sh",
      "args": [
        "--workspace=${workspaceFolder}"
      ],
      "env": {
        "PCHAT_HTTP_PORT": "13458",
        "PCHAT_NODE": "/usr/local/opt/node@22/bin/node",
        "PCHAT_HUB_HOST": "192.168.110.101",
        "NO_PROXY": "192.168.110.101,127.0.0.1,localhost"
      },
      "disabled": false,
      "autoApprove": [
        "wait_for_user_input",
        "init_conversation",
        "merge_conversation",
        "select_conversation"
      ]
    }
  }
}
```

### 关键字段

| 字段 | 值 | 说明 |
|:---|:---|:---|
| `command` | `~/.persistent-chat-local/ensure-hub.sh` | 启动器，桥接 stdio ↔ HTTP |
| `PCHAT_HUB_HOST` | `192.168.110.101` | 远端 NAS IP（主） |
| `PCHAT_HTTP_PORT` | `13458` | Hub 端口 |
| `PCHAT_NODE` | `/usr/local/opt/node@22/bin/node` | Node 22 路径 |
| `NO_PROXY` | `192.168.110.101,127.0.0.1,localhost` | 绕过代理直连 |
| `autoApprove` | 4 个工具全开 | 不弹确认框 |

### 加载步骤

1. 写入 `~/.trae/mcp.json`
2. **Trae 必须 `Cmd+Q` 完全退出**（不是关窗）
3. 重新打开 Trae
4. 看 SOLO Agent 窗口的工具列表 → 出现 `persistent-chat` 4 个工具

### 验证

```bash
# 1. 看 Trae 进程里是否有 server.js
ps aux | grep "persistent-chat-local/server.js" | grep -v grep
# 期望：看到 1 个进程，env 含 PCHAT_HUB_HOST=192.168.110.101

# 2. 在 Trae 里发："开始测试"
# 期望：4 工具出现 + 拿到 ct_ 开头的 token
```

---

## 2. Cursor

### 配置文件位置

```
~/Documents/个人/.cursor/mcp.json
```

### 完整配置（与 Trae 相同）

```json
{
  "mcpServers": {
    "persistent-chat": {
      "type": "stdio",
      "command": "/Users/karuo/.persistent-chat-local/ensure-hub.sh",
      "args": ["--workspace=${workspaceFolder}"],
      "env": {
        "PCHAT_HTTP_PORT": "13458",
        "PCHAT_NODE": "/usr/local/opt/node@22/bin/node",
        "PCHAT_HUB_HOST": "192.168.110.101",
        "NO_PROXY": "192.168.110.101,127.0.0.1,localhost"
      },
      "disabled": false,
      "autoApprove": [
        "wait_for_user_input",
        "init_conversation",
        "merge_conversation",
        "select_conversation"
      ]
    }
  }
}
```

### 加载步骤

1. 写入 `~/Documents/个人/.cursor/mcp.json`
2. Cursor → 设置 → MCP → Refresh
3. 看 `persistent-chat` 是否绿色点
4. 面板访问：Ctrl+L → 输入 `/mcp`

---

## 3. 多 IDE 共存

### 场景
- 同时开 Trae 和 Cursor，都想用持久对话
- 共享同一个 Hub（远端 NAS）

### 配置要点

**两边的 mcp.json 保持一致**，都指向同一个 Hub：

```json
"PCHAT_HUB_HOST": "192.168.110.101"
```

**垂直绑定隔离**：
- 不同工作区 → 不同 session
- 不同 Cursor 标签 → 不同 session
- 同工作区 + 同标签 → 复用 session

**冲突场景**：
- Trae 标签 = "学习" + Cursor 标签 = "学习" → 互窜（不推荐）
- 建议：Trae 用 "Trae_xxx"，Cursor 用 "Cursor_xxx"

---

## 4. 双 Hub 配置（远端 + 本地）

### 场景
- 远端 NAS 24×7 在
- 本地 launchd 守护备份
- 远端挂时自动 fallback

### 方案：脚本切换

**ensure-hub.sh 增强版**（可加 fallback）：

```bash
#!/bin/bash
# /Users/karuo/.persistent-chat-local/ensure-hub.sh
HUB_HOST="${PCHAT_HUB_HOST:-127.0.0.1}"
# 测试主 Hub
if ! curl -sf "http://${HUB_HOST}:13458/api/health" -m 2 > /dev/null; then
  # 失败，fallback 到本地
  HUB_HOST="127.0.0.1"
fi
export PCHAT_HUB_HOST="$HUB_HOST"
exec /usr/local/opt/node@22/bin/node \
  /Users/karuo/.persistent-chat-local/server.js \
  --workspace="${1#--workspace=}"
```

这样远端挂时自动回退到本地（launchd 守护一直跑）。

---

## 5. 工具参数详解

### 5.1 init_conversation

```typescript
{
  token?: string;              // 已有 token（merge 用）
  cursorTitle: string;         // 必填：Cursor 标签
  newPlan?: boolean;           // true=换计划，归档旧 ct_
  planLabel?: string;          // 计划名（newPlan 时必填）
  workspace?: string;          // 工作区路径
}
```

**返回**：
```json
{
  "Conversation initialized. pchat-token: ct_xxxx"
  "🆕 新计划线程：ct_xxxx"
  "[BINDING_AUTO_NEW] 新对话已自动绑定"
}
```

### 5.2 select_conversation

```typescript
{
  token: string;               // 必填：要复用的 ct_
  cursorTitle: string;         // 必填：当前 Cursor 标签
}
```

**返回**：
```json
{
  "[BINDING_REUSE]"
  "🔄 恢复对话: ct_xxxx"
}
```

### 5.3 wait_for_user_input

```typescript
{
  token: string;               // 必填
  message: string;             // 提示用户的话
  timeout?: number;            // 最长等多久（ms），默认 60000
  renewalOnly?: boolean;       // true=只续约不等消息
}
```

**返回**：
```json
{
  "<用户发的消息 或 '保活续跑' 默认文本>"
  "[pchat-token: ct_xxxx]"
  "校验#N"
}
```

### 5.4 merge_conversation

```typescript
{
  fromToken: string;           // 源 token
  toToken: string;             // 目标 token
  cursorTitle: string;         // 当前标签
}
```

**用途**：把两个 plan 的上下文合并。

---

## 6. 完整对话循环示例

```javascript
// 1. 起新计划
const init = await mcp.call('init_conversation', {
  cursorTitle: '持久对话永久续跑-20260626',
  newPlan: true,
  planLabel: '永久续跑三段式',
});
const token = extractToken(init); // ct_xxxx

// 2. 干活（可任意调用其他工具）
// ...

// 3. 真挂起等用户
const reply = await mcp.call('wait_for_user_input', {
  token,
  message: '【真挂起】请发任务或"继续"',
  timeout: 1800000, // 30 分钟
});
// 收到用户消息 → reply.text

// 4. 复用旧 session
await mcp.call('select_conversation', {
  token,
  cursorTitle: '持久对话永久续跑-20260626',
});

// 5. 循环到用户说"结束持久对话"
```

---

## 7. 常见配置错误

| 错误 | 现象 | 修复 |
|:---|:---|:---|
| `PCHAT_NODE` 路径错 | `node not found` | `which node` 改 |
| `PCHAT_HUB_HOST` 用 0.0.0.0 | 端口冲突 | 改成具体 IP |
| `NO_PROXY` 缺 | 代理拦截 | 加 `192.168.110.101` |
| `autoApprove` 缺 | 每次弹窗 | 加 4 个工具名 |
| Trae 没重启 | MCP 不加载 | `Cmd+Q` 退出 |
| Cursor 没 refresh | 看不到 | 设置 → MCP → Refresh |

---

> 最后更新：2026-06-26 · 卡若AI