# MCP 工具参考

index1 MCP Server 提供 6 个工具，通过 stdio 模式供 AI 工具调用。

## 启动方式

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

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

或命令行启动：

```bash
index1 serve
```

---

## recall — 统一搜索

**一次检索同时搜索代码和经验。**

自动跨库搜索 corpus（代码索引）+ cognition（认知事实），服务端决定搜索策略，AI 无需关心数据在哪。

### 参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `query` | string | 是 | — | 搜索查询文本 |
| `collection` | string | 否 | None | 限定搜索范围 |
| `top_k` | int | 否 | 10 | 返回结果数量 |

### 返回格式

```json
{
  "code": [
    {
      "id": 42,
      "score": 0.85,
      "source": "src/search.py",
      "section": "hybrid_search()",
      "content": "def hybrid_search(query, ...):",
      "symbols": ["hybrid_search", "SearchResult"]
    }
  ],
  "facts": [
    {
      "id": 7,
      "score": 0.78,
      "assertion": "CJK 查询向量搜索效果远好于 BM25",
      "category": "discovery",
      "confidence": 0.9
    }
  ],
  "tactics": [
    {
      "id": 3,
      "trigger_pattern": "搜索代码",
      "steps": ["先 index1 recall", "再 Grep 精确查找"],
      "success_rate": 0.95
    }
  ],
  "model": { ... },
  "mode": "hybrid",
  "hint": null,
  "query_ms": 45
}
```

返回按类型分组：
- **code** — 代码片段（来自 corpus）
- **facts** — 经验事实（来自 cognition）
- **tactics** — 策略（来自 cognition）
- **model** — 心智模型（来自 cognition）

---

## learn — 统一写入

**2 个参数记录洞察/决策/教训。**

替代旧的 7 参数 `cog_save_fact`。类型（category）、置信度（confidence）、作用域（scope）全部自动推断。写入前自动去重。

### 参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `insight` | string | 是 | — | 一句话描述学到了什么 |
| `context` | string | 否 | "" | 补充上下文（为什么重要、相关背景），支持纯文本或 JSON |
| `collection` | string | 否 | None | 项目名称（默认从上下文推断） |
| `session_id` | string | 否 | None | 会话 ID（用于同 session 去重过滤） |

### 返回格式

**创建成功**：

```json
{
  "status": "created",
  "fact_id": 42,
  "auto_inferred": {
    "category": "bug_fix",
    "confidence": 0.85,
    "scope_files": ["src/db.py"],
    "scope_entities": ["FTS5"],
    "scope_modules": ["corpus"]
  },
  "similar_facts": []
}
```

**重复检测**：

```json
{
  "status": "duplicate",
  "method": "jaccard",
  "similarity": 0.92,
  "similar_facts": [{"id": 7, "assertion": "..."}]
}
```

---

## read — 文件内容读取

**磁盘优先读取，附带索引元数据。**

上下文压缩后快速恢复"文件有什么"的认知。文件从磁盘删除时自动从 chunks 重建。

### 参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `file_path` | string | 是 | — | 文件路径（支持绝对路径、相对路径、文件名模糊匹配） |
| `collection` | string | 否 | None | 限定集合 |
| `offset` | int | 否 | None | 起始行号（1-based） |
| `limit` | int | 否 | None | 读取行数 |

### 返回格式

```json
{
  "path": "src/search.py",
  "content": "...",
  "total_lines": 350,
  "returned_lines": [1, 350],
  "has_more": false,
  "source": "disk",
  "symbols": [
    {"name": "hybrid_search", "kind": "function", "line": 42, "signature": "def hybrid_search(query, ...)"}
  ],
  "chunk_count": 8,
  "last_indexed": "2026-02-10T15:30:00"
}
```

- **source**: `"disk"`（磁盘读取）或 `"chunks"`（从索引重建）
- **stale**: `true` 时表示文件已修改但未重新索引
- 大文件自动截断前 500 行，使用 `offset`/`limit` 分页读取

---

## status — 系统状态

**一览 corpus 索引 + cognition 记忆 + embedding 后端。**

### 参数

无参数。

### 返回格式

```json
{
  "db_path": "/Users/xxx/.claude-index1/knowledge.db",
  "doc_count": 42,
  "chunk_count": 380,
  "collections": ["my_project"],
  "last_indexed": "2026-02-10T15:30:00",
  "vec_loaded": true,
  "embedding": {
    "available": true,
    "backend": "onnx",
    "model": "BAAI/bge-small-en-v1.5",
    "dim": 384,
    "reason": null
  },
  "cognition": {
    "enabled": true,
    "facts": 156,
    "models": 3,
    "tactics": 12
  }
}
```

---

## reindex — 重建索引

**重新扫描并索引指定路径或集合。**

### 参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `collection` | string | 否 | None | 集合名称 |
| `path` | string | 否 | None | 要索引的文件或目录（不指定则使用 watch_paths） |

### 返回格式

```json
{
  "indexed": 42,
  "skipped": 5,
  "failed": 0,
  "total": 47
}
```

---

## config — 查看/修改配置

### 参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `key` | string | 否 | None | 配置键名 |
| `value` | string | 否 | None | 配置值 |

### 用法

- **查看全部**：不传参数
- **修改配置**：传 `key` + `value`
- **重连 Ollama**：`key="ollama_reconnect"` — 重置冷却计时器并尝试重连

### 返回格式

修改配置：

```json
{
  "message": "已更新 top_k = 20"
}
```

重连 Ollama：

```json
{
  "message": "Ollama 重连成功，向量搜索已恢复",
  "ollama_available": true,
  "model": "nomic-embed-text"
}
```
