# Quick KG MCP Server

> 一个为 Amazon Q Developer (Kiro) 设计的 MCP Server，让 AI Agent 能够自动抓取在线文档、构建本地知识图谱和语义索引，帮助你快速建立项目知识库。

## 背景与动机

[Amazon Q Developer](https://aws.amazon.com/q/developer/) 内置了强大的知识库功能，支持 Keyword Search、Semantic Search 和 Knowledge Graph Extraction。但这些功能只能手动在控制台操作本地文件夹，无法自动从远程拉取文档。

对于许多云服务产品（如 RacoreCloud CDN），API 文档通过 [llms.txt](https://llmstxt.org/) 标准提供所有文档链接。我们需要一个桥梁工具，让 Agent 能够：

1. **自动抓取远程文档到本地** — 解析 llms.txt 并批量下载所有文档
2. **触发知识图谱提取** — 从文档中提取实体和关系，构建结构化知识
3. **建立语义索引** — 对文档进行分块、向量化，支持语义搜索
4. **提供多模式搜索** — 关键词搜索、语义搜索、混合搜索

这就是 `quick-kg-mcp` 的由来。它作为 MCP Server 接入 Amazon Q Developer，让 Agent 可以通过工具调用完成整个 **文档 → 知识库** 的自动化流水线。

## 功能特性

| # | 工具 | 说明 |
|---|------|------|
| 1 | `crawl_docs` | 从 llms.txt 抓取所有文档链接并下载到本地 |
| 2 | `kg_folder_rebuild` | 对本地文件夹进行知识图谱提取（实体 + 关系） |
| 3 | `kg_folder_configure` | 配置文件夹的提取参数（指令、模型等） |
| 4 | `kg_build` | 图谱维护操作（去重 / 清理孤儿节点 / 全维护） |
| 5 | `register_file_for_rag` | 注册单个文件到语义索引 |
| 6 | `index_directory` | 批量索引整个目录到语义索引 |
| 7 | `file_rag_search` | 语义搜索已索引的文件内容 |
| 8 | `kg_add` | 手动添加实体和关系到知识图谱 |
| 9 | `kg_search` | 多模式知识图谱搜索（关键词 / 语义 / 混合） |

## 快速开始

### 前置要求

- Node.js >= 18
- Amazon Q Developer (Kiro) 桌面版

### 安装

```bash
git clone https://github.com/pockees/quick-kg-mcp.git
cd quick-kg-mcp
npm install
npm run build
```

### 配置 MCP Server

在 MCP 配置文件（如 `mcp.json`）中添加：

```json
{
  "mcpServers": {
    "quick-kg-mcp": {
      "command": "node",
      "args": ["/path/to/quick-kg-mcp/dist/index.js"],
      "env": {
        "KG_BASE_DIR": "/path/to/your/knowledge-base",
        "KG_LLMS_TXT_URL": "https://docs.racorecloud.com/llms.txt",
        "KG_CRAWL_CONCURRENCY": "5"
      }
    }
  }
}
```

### 配置说明

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `KG_BASE_DIR` | 数据存储根目录 | `<项目根>/data` |
| `KG_LLMS_TXT_URL` | llms.txt 的 URL | `https://docs.racorecloud.com/llms.txt` |
| `KG_CRAWL_CONCURRENCY` | 并发抓取数 | `5` |
| `KG_CHUNK_SIZE` | RAG 分块大小（字符） | `1000` |
| `KG_CHUNK_OVERLAP` | RAG 分块重叠（字符） | `200` |

## 使用方法

### 完整工作流示例

典型使用流程如下：

**1️⃣ 让 Agent 抓取文档：**

> "帮我更新 RacoreCloud 的 API 文档"

Agent 调用 `crawl_docs` → 解析 llms.txt → 并发下载所有文档到本地

**2️⃣ 建立知识图谱：**

> "对下载的文档进行知识提取"

Agent 调用 `kg_folder_rebuild` → 从每个文件提取实体和关系 → 写入图谱存储

**3️⃣ 建立语义索引：**

> "索引这些文档以便搜索"

Agent 调用 `index_directory` → 文档分块 → 向量化 → 存入向量索引

**4️⃣ 搜索查询：**

> "CDN 加速域名怎么配置？"

Agent 调用 `file_rag_search` 或 `kg_search` → 返回相关文档片段或实体信息

---

### 工具详细说明

#### 1. crawl_docs

从 llms.txt 抓取所有文档链接并下载到本地存储。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `url` | string | 否 | 覆盖默认的 llms.txt URL |
| `output_folder` | string | 否 | 输出目录，默认 `./data/docs` |

**调用示例：**

```json
{
  "url": "https://docs.racorecloud.com/llms.txt",
  "output_folder": "/data/my-docs"
}
```

**返回示例：**

```json
{
  "totalLinks": 85,
  "successCount": 83,
  "failureCount": 2,
  "failures": [
    { "url": "https://example.com/broken", "error": "HTTP 404: Not Found" }
  ],
  "savedTo": "/path/to/data/docs"
}
```

---

#### 2. kg_folder_rebuild

读取文件夹中所有符合条件的文件，提取实体和关系，写入知识图谱。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `folder_path` | string | 是 | 要处理的本地文件夹路径 |

**调用示例：**

```json
{
  "folder_path": "/data/docs/docs.racorecloud.com"
}
```

**返回示例：**

```json
{
  "entitiesExtracted": 156,
  "relationshipsExtracted": 89,
  "filesProcessed": 85
}
```

---

#### 3. kg_folder_configure

为特定文件夹配置知识提取参数。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `folder_path` | string | 是 | 要配置的文件夹路径 |
| `special_instructions` | string | 否 | 自定义提取指令 |
| `extraction_model` | string | 否 | 提取模型：`balanced`、`detailed`、`fast` |

**调用示例：**

```json
{
  "folder_path": "/data/docs/docs.racorecloud.com",
  "special_instructions": "重点提取 API 端点和参数信息",
  "extraction_model": "detailed"
}
```

**返回示例：**

```json
{
  "message": "Configuration saved successfully",
  "folderPath": "/data/docs/docs.racorecloud.com"
}
```

---

#### 4. kg_build

执行知识图谱维护操作，保持图谱整洁高效。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `mode` | string | 是 | `compact`（去重）、`cleanup`（清理）、`maintenance`（全维护） |

**模式说明：**
- `compact` — 合并重复实体（按名称不区分大小写匹配）
- `cleanup` — 移除孤儿实体和无效关系
- `maintenance` — 依次执行去重和清理

**调用示例：**

```json
{
  "mode": "maintenance"
}
```

**返回示例：**

```json
{
  "mode": "maintenance",
  "entitiesMerged": 12,
  "entitiesRemoved": 3,
  "relationshipsRemoved": 5,
  "message": "Maintenance complete. Merged 12 duplicate entities, removed 3 orphan entities and 5 invalid relationships."
}
```

---

#### 5. register_file_for_rag

将单个文件注册到语义索引，进行分块和向量化。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_path` | string | 是 | 要索引的本地文件路径 |

**调用示例：**

```json
{
  "file_path": "/data/docs/docs.racorecloud.com/api-416453366.md"
}
```

**返回示例：**

```json
{
  "chunksIndexed": 8,
  "filePath": "/data/docs/docs.racorecloud.com/api-416453366.md",
  "message": "File registered for RAG search with 8 chunks."
}
```

---

#### 6. index_directory

批量索引整个目录中所有符合条件的文件。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `directory_path` | string | 是 | 要索引的本地目录路径 |

**调用示例：**

```json
{
  "directory_path": "/data/docs/docs.racorecloud.com"
}
```

**返回示例：**

```json
{
  "filesIndexed": 85,
  "totalChunks": 642,
  "message": "Indexed 85 files with 642 total chunks from directory: /data/docs/docs.racorecloud.com"
}
```

---

#### 7. file_rag_search

使用语义向量相似度搜索已索引的文件内容。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `query` | string | 是 | 搜索查询文本 |
| `folder_path` | string | 否 | 限定搜索范围的文件夹路径 |

**调用示例：**

```json
{
  "query": "如何配置 CDN 加速域名",
  "folder_path": "/data/docs/docs.racorecloud.com"
}
```

**返回示例：**

```json
{
  "results": [
    {
      "filePath": "/data/docs/docs.racorecloud.com/api-416453370.md",
      "content": "## 添加加速域名\n\n调用 AddCdnDomain 接口...",
      "similarity": 0.92
    }
  ],
  "total": 5
}
```

---

#### 8. kg_add

手动添加实体和关系到知识图谱。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `nodes` | string | 是 | JSON 字符串数组：`[{name, category, summary, properties?}]` |
| `edges` | string | 否 | JSON 字符串数组：`[{from_name, to_name, relation, properties?}]` |
| `source_type` | string | 否 | 来源类型标签，默认 `"local"` |
| `source_file` | string | 否 | 来源文件路径（溯源追踪） |

**调用示例：**

```json
{
  "nodes": "[{\"name\": \"AddCdnDomain\", \"category\": \"API\", \"summary\": \"添加加速域名接口\"}]",
  "edges": "[{\"from_name\": \"AddCdnDomain\", \"to_name\": \"CDN\", \"relation\": \"belongs_to\"}]",
  "source_type": "manual"
}
```

**返回示例：**

```json
{
  "nodesAdded": 1,
  "edgesAdded": 1,
  "message": "Added 1 nodes and 1 edges to the knowledge graph"
}
```

---

#### 9. kg_search

多模式知识图谱搜索，支持关键词、语义和混合搜索。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `query` | string | 是 | 搜索查询文本 |
| `category` | string | 否 | 按实体类别过滤（不区分大小写） |
| `mode` | string | 否 | 搜索模式：`keyword`、`semantic`、`hybrid`，默认 `keyword` |
| `node_id` | string | 否 | 限定搜索范围到从该节点可达的实体 |
| `hops` | number | 否 | 从 node_id 出发的关系跳数 |
| `include_edges` | boolean | 否 | 是否包含关系/边数据 |
| `since` | string | 否 | ISO 日期字符串，按创建或修改日期过滤 |

**调用示例：**

```json
{
  "query": "CDN",
  "category": "API",
  "mode": "keyword",
  "include_edges": true
}
```

**返回示例：**

```json
{
  "entities": [
    {
      "id": "abc-123",
      "name": "AddCdnDomain",
      "entityType": "API",
      "summary": "添加加速域名接口",
      "properties": {}
    }
  ],
  "edges": [
    {
      "sourceEntityId": "abc-123",
      "targetEntityId": "def-456",
      "relationshipType": "belongs_to"
    }
  ],
  "total": 1
}
```

## 数据存储结构

```
<KG_BASE_DIR>/
├── docs/                     # 抓取的文档
│   └── docs.racorecloud.com/ # 按域名组织
│       ├── api-416453366.md
│       ├── api-416453367.md
│       └── ...
├── graph/                    # 知识图谱数据
│   ├── graph.json            # 实体和关系
│   └── folder-configs.json   # 文件夹提取配置
└── rag/                      # RAG 索引数据
    ├── chunks.json           # 文档分块
    └── vectors.json          # 向量嵌入
```

## 与 Amazon Q Developer 内置知识库的关系

Amazon Q Developer 控制台中的 "Local folders" 功能（Keyword Search、Semantic Search、Knowledge Graph Extraction）是独立的内置功能。`quick-kg-mcp` 是一个补充工具，它提供了：

- **自动化** — Agent 可以通过工具调用自动完成文档抓取和索引，无需手动操作控制台
- **远程文档支持** — 可以从远程 URL 拉取文档，而内置功能只能操作已存在的本地文件
- **API 文档一键入库** — 对于使用 llms.txt 标准的 API 文档站点，一条命令即可完成入库
- **可编程的知识图谱操作** — 手动添加实体/关系、图谱维护、多模式搜索等

两者可以配合使用：先用 `quick-kg-mcp` 将远程文档拉取到本地目录，再在 Amazon Q Developer 中将该目录添加为本地知识库文件夹。

## 开发

### 本地开发

```bash
npm run dev          # 使用 tsx 热重载运行
npm run build        # TypeScript 编译
npm run test         # 运行测试
npm start            # 运行编译后的版本
```

### 项目结构

```
src/
├── config.ts                 # 配置加载（环境变量 + 默认值）
├── errors.ts                 # 统一错误类型定义
├── types.ts                  # 共享类型定义
├── index.ts                  # 入口文件
├── server.ts                 # MCP Server 初始化与工具注册
├── graph/                    # 知识图谱模块
│   ├── graph-store.ts        # 图谱存储（实体/关系 CRUD）
│   ├── graph-extractor.ts    # 实体与关系提取器
│   ├── graph-search.ts       # 图谱搜索逻辑
│   └── folder-config.ts      # 文件夹配置管理
├── rag/                      # RAG 模块
│   ├── chunker.ts            # 文档分块器
│   ├── embedder.ts           # 向量嵌入器
│   └── vector-store.ts       # 本地向量存储
├── storage/                  # 存储抽象层
│   └── storage-manager.ts    # 文件读写管理
└── tools/                    # MCP 工具实现
    ├── crawl-docs.ts         # crawl_docs
    ├── kg-folder-rebuild.ts  # kg_folder_rebuild
    ├── kg-folder-configure.ts# kg_folder_configure
    ├── kg-build.ts           # kg_build
    ├── rag-register.ts       # register_file_for_rag
    ├── index-directory.ts    # index_directory
    ├── file-rag-search.ts    # file_rag_search
    ├── kg-add.ts             # kg_add
    └── kg-search.ts          # kg_search
```

### 支持的文件类型

知识图谱提取和 RAG 索引支持以下文件类型：

`.md` `.txt` `.json` `.ts` `.js` `.html` `.xml` `.yaml` `.yml` `.csv` `.py`

## 许可证

MIT

## 致谢

- [Model Context Protocol](https://modelcontextprotocol.io/) — 标准化 AI 工具协议
- [Amazon Q Developer](https://aws.amazon.com/q/developer/) — AI 开发助手
- [llms.txt](https://llmstxt.org/) — 面向 LLM 的网站文档标准