# Cursor 集成指南

[Cursor](https://cursor.com/) 是 AI 代码编辑器，原生支持 MCP 协议。index1 可通过 MCP 或 CLI 两种方式接入。

## 前提条件

```bash
pipx install index1                    # 安装 index1
ollama pull nomic-embed-text           # 推荐，用于语义搜索
index1 index ./src ./docs              # 索引项目文件
```

## 安装后三步

<h3>⬛ 第 1 步：配置 MCP — 让 AI 能调用 index1</h3>

<h3>⬛ 第 2 步：添加搜索规则 — 让 AI 知道何时该调用</h3>

<h3>⬜ 第 3 步（可选）：CLI 备用方案</h3>

<h2 style="color:red">⚠️ 只做第 1 步 = 装了工具没教 AI 怎么用。第 2 步才是关键！</h2>

---

## 第 1 步：配置 MCP Server

### 方式 A：UI 配置

1. 打开 Cursor Settings（`Cmd+,` / `Ctrl+,`）
2. 搜索 "MCP" 或进入 Features → MCP Servers
3. 点击 "Add new MCP server"
4. 填写：
   - Name: `index1`
   - Type: `command`
   - Command: `index1 serve`

### 方式 B：配置文件

在项目根目录创建 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "index1": {
      "command": "index1",
      "args": ["serve"]
    }
  }
}
```

> 如果 `index1` 不在 PATH 中：`which index1`（macOS/Linux）或 `where.exe index1`（Windows）获取完整路径，替换 `"command"` 的值。

重启 Cursor 后，5 个 `docs_*` 工具在 Composer（Agent 模式）和 Chat 中可用。

---

## 第 2 步：添加搜索规则

> **这是最关键的一步。** 没有规则，Cursor AI 不知道什么时候该用 docs_search，经常直接搜全项目浪费上下文。

在项目根目录创建 **`.cursorrules`**：

```
# index1 搜索策略

本项目已配置 index1 MCP Server（docs_search 等 5 个工具）。

搜索代码时，严格遵循以下优先级：

1. 已知标识符（函数名/类名/文件名）→ 直接搜索文件，不需要 docs_search
2. 探索性问题（"XX 怎么实现的"、"XX 在哪"）→ 先用 docs_search 定位方向，再精确搜索
3. 中文问题查英文代码 → 必须用 docs_search（普通搜索不支持跨语言）
4. 高频关键词（config、search、import 等）→ 优先 docs_search，避免返回几百行噪声

典型工作流：
- docs_search("问题") → 定位文件和模块 → 在对应文件中精确搜索 → 读取代码

绝对不要：
- 对探索性问题直接全项目搜索常见关键词
- 跳过 docs_search 直接读大量文件
```

Cursor 每次对话都会读取 `.cursorrules`，自动按策略执行。

### 有规则 vs 没规则

```
❌ 没有规则：
   你: "搜索功能怎么实现的？"
   AI: 搜 "search" 全项目 → 881 行 → 35,895 tokens 💥

✅ 有规则：
   你: "搜索功能怎么实现的？"
   AI: docs_search("搜索功能") → 5 条 → 460 tokens ✓
       在 search.py 中精确搜索 → 100 tokens ✓
   节省 97%
```

### 也同时适用 Claude Code / OpenClaw

如果你同时使用 Cursor 和 Claude Code / OpenClaw，在 `.claude/CLAUDE.md` 中也添加相同的搜索策略。`.cursorrules` 和 `CLAUDE.md` 各管各的工具，互不冲突。

---

## 第 3 步（可选）：CLI 备用方案

即使不配置 MCP，也可以在 Cursor 的内置终端中直接使用：

```bash
index1 search "认证怎么实现的"     # 语义搜索
index1 get <chunk_id>             # 获取片段完整内容
index1 status                     # 查看索引状态
```

适用场景：
- MCP 配置还没设好时的临时方案
- 快速搜索，不需要 AI 自动调用
- 调试和验证索引内容

### MCP vs CLI 对比

| | MCP Server | CLI |
|---|---|---|
| AI 自动调用 | ✅ AI 根据问题自动搜索 | ❌ 需要手动在终端运行 |
| 配置复杂度 | 需要 mcp.json + .cursorrules | 零配置 |
| 适用场景 | Composer / Chat | 终端 |
| 上下文集成 | 搜索结果自动进入对话 | 需要手动复制 |

推荐：**先用 CLI 验证 index1 正常工作，再配置 MCP + 规则获得最佳体验**。

---

## 验证集成

在 Cursor Composer（Agent 模式）中测试：

```
你: 用 docs_search 搜索项目里的核心模块
→ 应返回搜索结果

你: 搜索功能怎么实现的？
→ AI 应先调用 docs_search，而不是直接搜全项目
```

如果 AI 不调用 docs_search：
1. 检查 Composer 是否在 **Agent 模式**
2. 检查 `.cursorrules` 是否存在且内容正确

## 故障排查

| 问题 | 原因 | 解决 |
|------|------|------|
| MCP 工具没出现 | 配置文件路径错误 | 确认 `.cursor/mcp.json` 在项目根目录 |
| AI 不用 docs_search | 没加搜索规则 | **做第 2 步**，创建 `.cursorrules` |
| Composer 不调用工具 | 未开启 Agent 模式 | Composer 切换到 Agent 模式 |
| `command not found` | index1 不在 PATH | `which index1` 获取完整路径 |
| 搜索无结果 | 未索引 | `index1 index ./src ./docs` |
| 中文搜索 0 结果 | 无 Ollama | `ollama pull nomic-embed-text` |

## 完整项目结构

```
项目根目录/
├── .cursor/
│   └── mcp.json                 ← 第 1 步：MCP 配置
├── .cursorrules                 ← 第 2 步：搜索规则（关键！）
├── src/
└── docs/
```
