npm package: @insightsuen/cognee
Description: Cognee 知识图谱 MCP 服务器
Latest version: 0.1.0

# cognee MCP Server

通过 MCP 协议操作自托管 [Cognee](https://github.com/topoteretes/cognee) 知识图谱，支持数据集管理、数据增删改查、知识图谱构建与多模式语义搜索。

## 使用方式

### 1. 本地构建 — 使用默认环境变量

| 环境变量 | 必填 | 说明 |
|---------|------|------|
| `COGNEE_URL` | ✅ | Cognee 实例地址，如 `http://localhost:8000` |
| `COGNEE_API_TOKEN` | 否 | 认证 Token；未开启认证时可省略 |

在 MCP 客户端（Cursor / Claude Desktop）的配置文件中：

```json
{
  "mcpServers": {
    "cognee": {
      "command": "node",
      "args": ["/path/to/Insight-MCP/servers/cognee/dist/index.js"],
      "env": {
        "COGNEE_URL": "http://localhost:8000",
        "COGNEE_API_TOKEN": "your-jwt-token"
      }
    }
  }
}
```

不想明文写在配置文件中？在 `~/.zshrc` 里 `export` 环境变量，然后省略 `env` 字段，子进程会自动继承：

```json
{
  "mcpServers": {
    "cognee": {
      "command": "node",
      "args": ["/path/to/Insight-MCP/servers/cognee/dist/index.js"]
    }
  }
}
```

---

### 2. CLI 参数直传

适合临时测试，直接在 `args` 中传入值：

```json
{
  "mcpServers": {
    "cognee": {
      "command": "node",
      "args": [
        "/path/to/Insight-MCP/servers/cognee/dist/index.js",
        "--url=http://localhost:8000",
        "--api-key=your-jwt-token"
      ]
    }
  }
}
```

---

### 3. 指定自定义环境变量名

凭证已存储在其他变量名下时，通过 `--*-env` 参数指定读取哪个变量：

```json
{
  "mcpServers": {
    "cognee": {
      "command": "node",
      "args": [
        "/path/to/Insight-MCP/servers/cognee/dist/index.js",
        "--url-env=MY_COGNEE_URL",
        "--api-key-env=MY_COGNEE_TOKEN"
      ]
    }
  }
}
```

凭证配置方式总览：

| 凭证 | 默认环境变量 | CLI 直传 | 指定环境变量 |
|------|------------|---------|------------|
| 实例地址 | `COGNEE_URL` | `--url=xxx` | `--url-env=VAR` |
| API Token | `COGNEE_API_TOKEN` | `--api-key=xxx` | `--api-key-env=VAR` |

---

### 4. 开发模式（从源码构建）

**第一步：构建**

```bash
# 在项目根目录执行
pnpm install
pnpm --filter @insightsuen/cognee build
```

**第二步：在 MCP 客户端中注册本地构建产物**

```json
{
  "mcpServers": {
    "cognee-dev": {
      "command": "node",
      "args": [
        "/path/to/Insight-MCP/servers/cognee/dist/index.js",
        "--url=http://localhost:8000"
      ],
      "env": {
        "COGNEE_API_TOKEN": "your-jwt-token"
      }
    }
  }
}
```

**热重载开发**：修改源码后重新构建即可，无需重启 MCP 客户端：

```bash
pnpm --filter @insightsuen/cognee dev   # 监听文件变化，自动编译
```

## 典型工作流

Cognee 中数据需要经过「添加 → 构建图谱 → 搜索」三个阶段：

```
cognee-add-data         # 1. 向数据集添加原始文本
       ↓
cognee-cognify          # 2. 将数据集构建为知识图谱（可能耗时较长）
       ↓
cognee-search           # 3. 进行语义搜索
```

## 可用工具

### `cognee-list-datasets`

列出 Cognee 中所有数据集。

无参数。

---

### `cognee-list-data`

列出指定数据集中的所有数据项。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `datasetId` | string | ✅ | 数据集 ID（UUID，可从 `cognee-list-datasets` 获取） |

---

### `cognee-search`

在 Cognee 知识图谱中进行语义搜索，支持多种搜索类型。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `query` | string | ✅ | 搜索查询文本 |
| `searchType` | enum | 否 | 搜索类型，默认 `GRAPH_COMPLETION`，见下表 |
| `datasets` | string[] | 否 | 按名称限定搜索的数据集列表 |
| `datasetIds` | string[] | 否 | 按 UUID 限定搜索的数据集列表 |
| `topK` | number | 否 | 返回结果数量，默认 10，最大 100 |
| `systemPrompt` | string | 否 | 用于 Completion 类搜索的系统提示词 |

**搜索类型（`searchType`）：**

| 类型 | 说明 |
|------|------|
| `GRAPH_COMPLETION`（默认） | 基于图谱的智能问答补全 |
| `RAG_COMPLETION` | 检索增强生成 |
| `SUMMARIES` | 返回内容摘要 |
| `CHUNKS` | 返回原始文本块 |
| `CHUNKS_LEXICAL` | 词汇匹配文本块 |
| `TRIPLET_COMPLETION` | 基于知识三元组补全 |
| `GRAPH_SUMMARY_COMPLETION` | 图摘要补全 |
| `NATURAL_LANGUAGE` | 自然语言查询 |
| `CYPHER` | Cypher 图查询语言 |
| `GRAPH_COMPLETION_COT` | 图补全（思维链模式） |
| `FEELING_LUCKY` | 自动选择最优搜索策略 |
| `TEMPORAL` | 时序数据查询 |
| `CODING_RULES` | 代码规则查询 |

> 按名称传入 `datasets` 只能搜索当前用户拥有的数据集；跨用户共享的数据集需使用 `datasetIds`（UUID）。

---

### `cognee-add-data`

向指定数据集添加文本数据，数据集不存在时自动创建。添加后需调用 `cognee-cognify` 才能被搜索到。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `data` | string | ✅ | 要添加的文本内容 |
| `datasetName` | string | ✅ | 目标数据集名称 |

---

### `cognee-update-data`

更新数据集中指定数据项的内容。更新后需重新 `cognee-cognify` 以刷新知识图谱。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `dataId` | string | ✅ | 要更新的数据项 ID（UUID） |
| `datasetId` | string | ✅ | 数据项所属的数据集 ID（UUID） |
| `data` | string | ✅ | 新的文本内容 |

---

### `cognee-delete-data`

删除数据集中的指定数据项。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `datasetId` | string | ✅ | 数据集 ID（UUID） |
| `dataId` | string | ✅ | 要删除的数据项 ID（UUID） |

---

### `cognee-delete-dataset`

删除整个数据集及其包含的所有数据，操作不可逆。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `datasetId` | string | ✅ | 要删除的数据集 ID（UUID） |

---

### `cognee-cognify`

将数据集中的原始数据构建为知识图谱，添加数据后必须执行此操作才能进行搜索。处理时间取决于数据量，可能较长。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `datasets` | string[] | 否 | 按名称指定要处理的数据集；不指定则处理所有 |
| `datasetIds` | string[] | 否 | 按 UUID 指定要处理的数据集 |
| `customPrompt` | string | 否 | 自定义实体提取提示词 |

---

### `cognee-cognify-status`

查询数据集的 cognify 流水线处理状态。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `datasetIds` | string[] | ✅ | 要查询状态的数据集 UUID 列表（至少一个） |