# Cursor

推荐通过 Browser OAuth 连接 Cursor IDE，并以直接 MCP 作为受支持的无头备选方案。

- Canonical: https://docs.xmemo.dev/zh/docs/mcp/cursor
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 7fd7191e1dc893d17ccc57d383768ec709f689feebde935e92cbec85252ab1df
- Edition-Digest: 8814c8a95327bb3bd7dbe261c7b7acadbaeb1d5e2e0da9f1381a53c46689c8eb
- Source-Revision: sha256:5900c57d4a9131e42571635160707dd33bcf4854c638661503d89ccec7e4bdeb

## 前置条件

使用带有 设置 -> 功能 -> MCP 或市场支持的 Cursor IDE。接口与前置条件：

- 具体接口：Cursor IDE (~/.cursor/mcp.json 或 设置 -> 功能 -> MCP)。
- 端点：https://xmemo.dev/mcp。
- 首选认证模式：Browser OAuth。
- 备选认证模式：适用于无头和容器环境的直接承载令牌。
- 账户：在 https://xmemo.dev 拥有有效的 XMemo 账户。

## 安装 / 设置

打开 Cursor 设置 -> 功能 -> MCP 或配置 ~/.cursor/mcp.json。对于无头操作，请使用带有环境变量令牌引用的直接配置块，而不是浏览器流程：

- OAuth 路径：仅配置托管 URL，并在首次使用时触发浏览器同意。
- 直接后备：将令牌保留在 XMEMO_KEY 中，切勿直接保留在设置文件中。
- 不要在同一条目中将 OAuth URL 配置与 Authorization 标头混用。

## 设置凭据

OAuth 路径无需密钥 — 在首次提示时完成 Browser OAuth。对于直接无头后备，请在 shell 环境中设置 XMEMO_KEY，切勿将令牌值粘贴到 Cursor 设置中：

```bash
# OAuth path: no XMEMO_KEY needed (browser prompt)
# Direct fallback:
export XMEMO_KEY='<your-xmemo-token>'
```

## 生成 / 确认 XMEMO_AGENT_INSTANCE_ID

经过审查的 Cursor OAuth 和直接代码片段不需要客户端实例标头。如果无头包装器提供 XMEMO_AGENT_INSTANCE_ID，请为每个本地配置文件生成一次并重复使用。

## 保留现有配置块

首选 OAuth 路径：在 ~/.cursor/mcp.json 中使用经过审查的仅 URL Cursor 配置进行基于浏览器的 OAuth 认证：

```json
{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp"
    }
  }
}
```

## 直接后备配置块

直接无头后备：在无头或非交互式环境中运行 Cursor 时，配置引用本地环境中 ${env:XMEMO_KEY} 的 Authorization 标头：

```json
{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}"
      }
    }
  }
}
```

## 重启客户端

编辑配置后重启 Cursor 或在 设置 -> 功能 -> MCP 中关闭再打开 MCP 服务器，以使更改生效。

## 使用真实的召回调用进行测试

使第一次 MCP 调用为只读。这是实际的召回调用，而不是健康检查占位符，并且它不会写入记忆。

```text
recall({ query: "connection check", limit: 1 })
```

## 预期响应（字面形态）

成功的调用将返回以下公开的排序文本形态；引用和内容是来自授权记忆空间的真实值。

```text
### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>
```

## 首个实用任务：合成记忆生命周期

在 Cursor Composer 或 Agent 模式内演练完整的合成记忆任务：

- 1. 保存合成事实：要求 Cursor 记住规范 ("Demo project timestamps use UTC.") 到 "projects/demo-onboarding/conventions"。
- 2. 无状态转换：启动新的 Cursor Composer 聊天或重新打开项目工作区。
- 3. 带溯源归属的召回：查询 "demo project timestamp format"。确认返回的 Reference 和 Location。
- 4. 修正记忆：使用有效 ID 调用 update_memory，以使用 ISO 8601 格式化时间戳。
- 5. 可选清理：在入门测试完成后，使用记忆 ID 调用 forget。

## 功能与配置文件工具

Cursor 可以访问 MCP 文档契约中为 cursor-plugin 配置文件定义的限定工具：

- 核心记忆工具：remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context, search_knowledge。
- 快照与冲突工具：create_restart_snapshot, restore_restart_snapshot, list_memory_versions, list_memory_conflicts, resolve_memory_conflict。
- 项目与规划工具：get_mcp_identity, get_project_context, get_timeline, list_memory_todos, complete_memory_todo, create_memory_todo, update_project_decision, update_project_todo, update_state。
- 云端技能与治理：recall_cloud_skill, save_cloud_skill, propose_write, propose_todo_mutation, propose_profile_mutation, query_audit, record_event, memory_stats。

## 限制与边界

Cursor 的操作边界与约束：

- 配置纯净性：不要在同一个服务器块中将仅 OAuth URL 的配置与 Authorization 标头混用。
- 工作区边界：记忆访问严格限制在经过身份验证的用户的工作区内。
- 无头令牌要求：直接 MCP 后备需要显式配置环境令牌。

## 常见错误

Cursor 可能会在其 OAuth 路径或其直接无头后备中失败：

- invalid_grant — OAuth 授权码无效、已过期或已被使用：重新连接 Cursor 并再次授权。
- 401 invalid_token — 直接后备令牌缺失、已过期或无效：在无头环境中验证 XMEMO_KEY。
- 403 insufficient_scope — 凭据未授予 memory:read：批准所需的范围或签发包含该范围的令牌。

## 更新与移除

Cursor 的维护流程：

- 更新：在 Cursor MCP 设置中关闭再打开服务器以重新加载工具 schema。
- 移除：从 ~/.cursor/mcp.json 中删除 xmemo 条目，或从 Cursor MCP 设置中将其移除。

## Cursor

Direct client: configure in ~/.cursor/mcp.json with XMEMO_KEY in the environment. Run npx @xmemo/client mcp add cursor to install automatically.

```
{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "cursor",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```