@chinjinyu/mcp-knowledge-graph-plus 0.1.1

package/README.md

@@ -0,0 +1,700 @@
+# MCP Knowledge Graph Plus
+
+一个基于 **Model Context Protocol (MCP)** 的知识图谱服务器，使用 SQLite 数据库进行持久化存储。允许 AI 助手通过 MCP 协议创建、管理和查询结构化的知识数据。
+
+## 功能特性
+
+- 🔷 **节点管理** - 创建、编辑、删除知识节点
+- 🔗 **关系管理** - 建立和管理节点间的关系链接
+- 📝 **事实管理** - 为节点添加事实和备注
+- 🔍 **搜索查询** - 支持多字段、多逻辑的关键词搜索
+- 📊 **知识图谱** - 完整列出所有节点、关系和事实
+- 💾 **持久化存储** - 基于 SQLite 的本地数据库
+- 🚀 **MCP 协议** - 标准化的 AI 上下文通信协议
+
+## 系统要求
+
+- Node.js >= 18.0.0
+
+## 安装
+
+```bash
+# 克隆或进入项目目录
+cd mcp-knowledge-graph-plus
+
+# 安装依赖
+npm install
+
+# 构建项目
+npm run build
+```
+
+## 快速开始
+
+### 1. 构建项目
+
+```bash
+npm run build
+```
+
+### 2. 配置 MCP 客户端
+
+在你的 MCP 客户端配置中添加此服务器：
+
+```json
+{
+  "mcpServers": {
+    "knowledge-graph": {
+      "command": "node",
+      "args": ["/path/to/mcp-knowledge-graph-plus/dist/index.js"],
+      "env": {
+        "DB_PATH": "/path/to/your/database.db"
+      }
+    }
+  }
+}
+```
+
+### 3. 命令行参数
+
+支持通过命令行参数指定数据库路径：
+
+```bash
+# 方式 1: 使用等号
+node dist/index.js --db-path=/path/to/db.db
+
+# 方式 2: 使用空格
+node dist/index.js --db-path /path/to/db.db
+```
+
+### 4. 环境变量
+
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `DB_PATH` | 数据库文件路径 | `./default.db` |
+| `NODE_ENV` | 运行环境 (development/production/test) | `production` |
+
+## 可用工具 (Tools)
+
+---
+
+### 一、节点管理
+
+#### 1. `kg_node_add` - 添加节点
+
+添加新的知识节点及其关联的事实。
+
+**输入参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `nodes` | `array` | ✅ | 节点数组 |
+| `nodes[].name` | `string` | ✅ | 节点名称（唯一标识） |
+| `nodes[].type` | `string` | ✅ | 节点类型（如：概念、人物、地点） |
+| `nodes[].facts` | `string[]` | ❌ | 关联的事实描述数组 |
+
+**输出参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `added` | `number` | 成功创建的节点数量 |
+| `nodes` | `array` | 创建的节点列表 |
+| `nodes[].name` | `string` | 节点名称 |
+| `nodes[].type` | `string` | 节点类型 |
+| `nodes[].facts` | `string[]` | 创建的事实列表 |
+
+**示例：**
+
+```json
+// 输入
+{
+  "nodes": [
+    { "name": "人工智能", "type": "概念", "facts": ["是计算机科学的一个分支", "模拟人类智能"] },
+    { "name": "机器学习", "type": "技术", "facts": ["是 AI 的子领域"] }
+  ]
+}
+
+// 输出
+{
+  "added": 2,
+  "nodes": [
+    { "name": "人工智能", "type": "概念", "facts": ["是计算机科学的一个分支", "模拟人类智能"] },
+    { "name": "机器学习", "type": "技术", "facts": ["是 AI 的子领域"] }
+  ]
+}
+```
+
+---
+
+#### 2. `kg_node_edit` - 编辑节点
+
+修改现有节点的名称和/或类型。
+
+**输入参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `nodes` | `array` | ✅ | 节点编辑数组 |
+| `nodes[].name` | `string` | ✅ | 要编辑的节点当前名称 |
+| `nodes[].newName` | `string` | ❌ | 新名称（不填则不变） |
+| `nodes[].newType` | `string` | ❌ | 新类型（不填则不变） |
+
+**输出参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `updated` | `number` | 更新的节点数量 |
+| `nodes` | `array` | 更新后的节点列表 |
+
+**示例：**
+
+```json
+// 输入
+{
+  "nodes": [
+    { "name": "AI", "newName": "人工智能", "newType": "学科" },
+    { "name": "深度学习", "newType": "算法" }
+  ]
+}
+
+// 输出
+{
+  "updated": 2,
+  "nodes": [
+    { "name": "人工智能", "type": "学科" },
+    { "name": "深度学习", "type": "算法" }
+  ]
+}
+```
+
+---
+
+#### 3. `kg_node_del` - 删除节点
+
+删除指定节点（级联删除相关事实和关系）。
+
+**输入参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `names` | `string[]` | ✅ | 要删除的节点名称数组 |
+
+**输出参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `deleted` | `number` | 删除的节点数量 |
+| `nodes` | `array` | 被删除节点的详细信息 |
+
+**示例：**
+
+```json
+// 输入
+{ "names": ["过时的概念", "临时节点"] }
+
+// 输出
+{
+  "deleted": 2,
+  "nodes": [
+    { "name": "过时的概念", "type": "概念", "factsCount": 3, "linksCount": 5 },
+    { "name": "临时节点", "type": "测试", "factsCount": 0, "linksCount": 2 }
+  ]
+}
+```
+
+---
+
+#### 4. `kg_node_get` - 获取节点
+
+获取指定节点的详细信息（包含事实和关系）。返回所有涉及请求节点的链接，链接中会补全另一端的节点名称。
+
+**输入参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `names` | `string[]` | ✅ | 要查询的节点名称数组 |
+| `page` | `boolean` | ✅ | 是否启用分页 |
+| `pageNum` | `number` | ❌ | 页码（默认 1） |
+| `pageSize` | `number` | ❌ | 每页数量（默认 10） |
+
+**输出参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `nodes` | `array` | 节点列表 |
+| `links` | `array` | 涉及请求节点的链接列表 |
+| `pagination` | `object` | 分页信息（仅当启用分页时） |
+
+**示例：**
+
+```json
+// 输入
+{ "names": ["人工智能", "机器学习"], "page": false }
+
+// 输出
+{
+  "nodes": [
+    { "name": "人工智能", "type": "概念", "facts": ["是计算机科学的一个分支"] },
+    { "name": "机器学习", "type": "技术", "facts": ["是 AI 的子领域"] }
+  ],
+  "links": [
+    { "from": "人工智能", "to": "机器学习", "type": "包含" }
+  ]
+}
+```
+
+---
+
+### 二、链接管理
+
+#### 5. `kg_link_add` - 添加链接
+
+在两个节点之间创建有向关系链接。
+
+**输入参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `links` | `array` | ✅ | 链接数组 |
+| `links[].from` | `string` | ✅ | 起始节点名称 |
+| `links[].to` | `string` | ✅ | 目标节点名称 |
+| `links[].type` | `string` | ✅ | 关系类型 |
+
+**输出参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `added` | `number` | 创建的链接数量 |
+| `links` | `array` | 创建的链接列表 |
+
+**示例：**
+
+```json
+// 输入
+{
+  "links": [
+    { "from": "人工智能", "to": "机器学习", "type": "包含" },
+    { "from": "机器学习", "to": "深度学习", "type": "包含" }
+  ]
+}
+
+// 输出
+{
+  "added": 2,
+  "links": [
+    { "from": "人工智能", "to": "机器学习", "type": "包含" },
+    { "from": "机器学习", "to": "深度学习", "type": "包含" }
+  ]
+}
+```
+
+---
+
+#### 6. `kg_link_edit` - 编辑链接
+
+修改现有链接的类型。
+
+**输入参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `links` | `array` | ✅ | 链接编辑数组 |
+| `links[].from` | `string` | ✅ | 起始节点名称 |
+| `links[].to` | `string` | ✅ | 目标节点名称 |
+| `links[].old` | `string` | ✅ | 原关系类型 |
+| `links[].new` | `string` | ✅ | 新关系类型 |
+
+**输出参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `updated` | `number` | 更新的链接数量 |
+| `links` | `array` | 更新后的链接列表 |
+
+**示例：**
+
+```json
+// 输入
+{
+  "links": [
+    { "from": "人工智能", "to": "自然语言处理", "old": "相关", "new": "包含" }
+  ]
+}
+
+// 输出
+{
+  "updated": 1,
+  "links": [
+    { "from": "人工智能", "to": "自然语言处理", "type": "包含" }
+  ]
+}
+```
+
+---
+
+#### 7. `kg_link_del` - 删除链接
+
+删除指定的链接。
+
+**输入参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `links` | `array` | ✅ | 要删除的链接数组 |
+| `links[].from` | `string` | ✅ | 起始节点名称 |
+| `links[].to` | `string` | ✅ | 目标节点名称 |
+| `links[].type` | `string` | ✅ | 关系类型 |
+
+**输出参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `deleted` | `number` | 删除的链接数量 |
+| `links` | `array` | 被删除的链接列表 |
+
+**示例：**
+
+```json
+// 输入
+{
+  "links": [
+    { "from": "人工智能", "to": "机器学习", "type": "包含" }
+  ]
+}
+
+// 输出
+{
+  "deleted": 1,
+  "links": [
+    { "from": "人工智能", "to": "机器学习", "type": "包含" }
+  ]
+}
+```
+
+---
+
+### 三、事实管理
+
+#### 8. `kg_fact_add` - 添加事实
+
+为现有节点添加事实。
+
+**输入参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `facts` | `array` | ✅ | 事实数组 |
+| `facts[].node` | `string` | ✅ | 节点名称 |
+| `facts[].contents` | `string[]` | ✅ | 事实内容数组 |
+
+**输出参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `added` | `number` | 创建的事实数量 |
+| `facts` | `array` | 创建的事实列表（按节点分组） |
+
+**示例：**
+
+```json
+// 输入
+{
+  "facts": [
+    { "node": "人工智能", "contents": ["由图灵测试提出", "始于 1950 年代"] },
+    { "node": "机器学习", "contents": ["使用统计学习方法"] }
+  ]
+}
+
+// 输出
+{
+  "added": 3,
+  "facts": [
+    { "node": "人工智能", "contents": ["由图灵测试提出", "始于 1950 年代"] },
+    { "node": "机器学习", "contents": ["使用统计学习方法"] }
+  ]
+}
+```
+
+---
+
+#### 9. `kg_fact_edit` - 编辑事实
+
+修改现有事实的内容。
+
+**输入参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `facts` | `array` | ✅ | 事实编辑数组 |
+| `facts[].node` | `string` | ✅ | 节点名称 |
+| `facts[].old` | `string` | ✅ | 原事实内容（必须精确匹配） |
+| `facts[].new` | `string` | ✅ | 新事实内容 |
+
+**输出参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `updated` | `number` | 更新的事实数量 |
+| `facts` | `array` | 更新后的事实列表 |
+
+**示例：**
+
+```json
+// 输入
+{
+  "facts": [
+    { "node": "人工智能", "old": "始于 1950 年代", "new": "正式诞生于 1956 年达特茅斯会议" }
+  ]
+}
+
+// 输出
+{
+  "updated": 1,
+  "facts": [
+    { "node": "人工智能", "content": "正式诞生于 1956 年达特茅斯会议" }
+  ]
+}
+```
+
+---
+
+#### 10. `kg_fact_del` - 删除事实
+
+删除节点的事实记录。
+
+**输入参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `facts` | `array` | ✅ | 要删除的事实数组 |
+| `facts[].node` | `string` | ✅ | 节点名称 |
+| `facts[].contents` | `string[]` | ✅ | 要删除的事实内容数组 |
+
+**输出参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `deleted` | `number` | 删除的事实数量 |
+| `facts` | `array` | 被删除的事实列表 |
+
+**示例：**
+
+```json
+// 输入
+{
+  "facts": [
+    { "node": "人工智能", "contents": ["由图灵测试提出"] }
+  ]
+}
+
+// 输出
+{
+  "deleted": 1,
+  "facts": [
+    { "node": "人工智能", "content": "由图灵测试提出" }
+  ]
+}
+```
+
+---
+
+### 四、查询工具
+
+#### 11. `kg_list` - 列出所有数据
+
+列出知识图谱中的所有节点和链接。支持分页，链接会补全另一端的节点名称。
+
+**输入参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `page` | `boolean` | ✅ | 是否启用分页 |
+| `pageNum` | `number` | ❌ | 页码（默认 1） |
+| `pageSize` | `number` | ❌ | 每页数量（默认 10） |
+
+**输出参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `nodes` | `array` | 节点列表 |
+| `links` | `array` | 链接列表 |
+| `pagination` | `object` | 分页信息（仅当启用分页时） |
+
+**示例：**
+
+```json
+// 输入 - 不分页
+{ "page": false }
+
+// 输出
+{
+  "nodes": [
+    { "name": "人工智能", "type": "概念", "facts": ["是计算机科学的一个分支"] },
+    { "name": "机器学习", "type": "技术", "facts": ["是 AI 的子领域"] }
+  ],
+  "links": [
+    { "from": "人工智能", "to": "机器学习", "type": "包含" }
+  ]
+}
+
+// 输入 - 分页
+{ "page": true, "pageNum": 1, "pageSize": 10 }
+
+// 输出
+{
+  "nodes": [...],
+  "links": [...],
+  "pagination": {
+    "page": 1,
+    "pageSize": 10,
+    "total": 25,
+    "pages": 3,
+    "hasNext": true,
+    "hasPrev": false
+  }
+}
+```
+
+---
+
+#### 12. `kg_search` - 搜索节点
+
+按关键词搜索节点。默认搜索节点名称、类型和事实内容。
+
+**输入参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `query` | `string[]` | ✅ | 搜索关键词数组 |
+| `page` | `boolean` | ✅ | 是否启用分页 |
+| `pageNum` | `number` | ❌ | 页码（默认 1） |
+| `pageSize` | `number` | ❌ | 每页数量（默认 10） |
+| `logic` | `string` | ❌ | 搜索逻辑：`or`（或）/ `and`（与），默认 `or` |
+| `fields` | `string[]` | ❌ | 搜索字段范围，默认 `["name", "type", "fact"]` |
+
+**搜索字段说明：**
+
+| 值 | 说明 |
+|---|------|
+| `name` | 在节点名称中搜索 |
+| `type` | 在节点类型中搜索 |
+| `fact` | 在事实内容中搜索 |
+| `link` | 在链接类型中搜索（返回有该类型链接的节点） |
+
+**输出参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `nodes` | `array` | 匹配的节点列表 |
+| `links` | `array` | 匹配节点相关的链接列表 |
+| `pagination` | `object` | 分页信息（仅当启用分页时） |
+
+**示例：**
+
+```json
+// 示例 1: OR 逻辑搜索（默认）
+// 输入
+{
+  "query": ["人工", "学习"],
+  "page": false
+}
+// 返回：节点名称、类型或事实中包含"人工"或"学习"的节点
+
+// 示例 2: AND 逻辑搜索
+// 输入
+{
+  "query": ["工程师", "Python"],
+  "logic": "and",
+  "page": false
+}
+// 返回：同时包含"工程师"和"Python"的节点
+
+// 示例 3: 指定搜索字段
+// 输入
+{
+  "query": ["works_at"],
+  "fields": ["link"],
+  "page": false
+}
+// 返回：有 works_at 链接关系的节点
+
+// 示例 4: 分页搜索
+// 输入
+{
+  "query": ["工程师"],
+  "fields": ["fact"],
+  "page": true,
+  "pageNum": 1,
+  "pageSize": 10
+}
+// 输出
+{
+  "nodes": [...],
+  "links": [...],
+  "pagination": {
+    "page": 1,
+    "pageSize": 10,
+    "total": 25,
+    "pages": 3,
+    "hasNext": true,
+    "hasPrev": false
+  }
+}
+```
+
+---
+
+## 项目结构
+
+```
+mcp-knowledge-graph-plus/
+├── src/
+│   ├── index.ts                 # 入口文件
+│   ├── application/             # 应用层（业务逻辑）
+│   │   └── services/            # 领域服务
+│   ├── core/                    # 核心层（配置、类型、错误）
+│   │   ├── config/              # 配置管理
+│   │   ├── errors/              # 错误定义
+│   │   └── types/               # 类型定义
+│   ├── infrastructure/          # 基础设施层
+│   │   ├── database/            # 数据库管理
+│   │   ├── di/                  # 依赖注入容器
+│   │   └── repositories/        # 数据仓库
+│   └── interfaces/              # 接口层
+│       └── mcp/                 # MCP 接口实现
+│           └── commands/        # 命令实现
+├── tests/                       # 测试文件
+├── dist/                        # 编译输出
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## 开发
+
+```bash
+# 构建
+npm run build
+
+# 运行测试
+npm test
+```
+
+## 架构设计
+
+本项目采用 **整洁架构 (Clean Architecture)** 设计：
+
+- **接口层 (Interfaces)** - MCP 协议适配器和命令处理
+- **应用层 (Application)** - 领域服务和业务逻辑
+- **核心层 (Core)** - 类型定义、配置和错误处理
+- **基础设施层 (Infrastructure)** - 数据库、依赖注入和数据持久化
+
+### 数据模型
+
+- **实体 (Entities)** - 知识节点，包含名称和类型
+- **关系 (Relations)** - 节点间的有向链接，包含关系类型
+- **事实 (Facts)** - 节点的附加事实和描述
+
+## 许可证
+
+MIT License

package/dist/application/services/FactService.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fact Service
+ */
+import type { Fact, CreateFactInput, UpdateFactInput } from '../../core/types/index.js';
+import type { FactRepository } from '../../infrastructure/repositories/FactRepository.js';
+import type { NodeRepository } from '../../infrastructure/repositories/NodeRepository.js';
+export declare class FactService {
+    private readonly factRepo;
+    private readonly nodeRepo;
+    constructor(factRepo: FactRepository, nodeRepo: NodeRepository);
+    createFacts(inputs: readonly CreateFactInput[]): Promise<readonly Fact[]>;
+    deleteFactsByContent(nodeName: string, contents: readonly string[]): Promise<number>;
+    updateFactsByContent(updates: readonly UpdateFactInput[]): Promise<readonly Fact[]>;
+    getNodeNameMap(entityIds: readonly number[]): Promise<Map<number, string>>;
+}
+//# sourceMappingURL=FactService.d.ts.map

package/dist/application/services/FactService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FactService.d.ts","sourceRoot":"","sources":["../../../src/application/services/FactService.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qDAAqD,CAAC;AAC1F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qDAAqD,CAAC;AAE1F,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,cAAc;IAGrC,WAAW,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;IAazE,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAMpF,oBAAoB,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;IAgBnF,cAAc,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAIjF"}