知识图谱-mcp

Name: 知识图谱-mcp
Author: n-r-w

作者：n-r-w15 星标更新：2025-11-11

安装使用来源：spider==github.com

项目介绍

警告

我对这种自动上下文管理工具已经失去了信心，因为几乎不可能控制它。一段时间后，我总是不得不手动清理混乱或纠正不适当的LLM笔记。因此，我创建了一个工具，使LLM代理能够访问动态加载的上下文。然而，上下文本身是由用户创建的：https://github.com/n-r-w/agent-standards-mcp

知识图谱MCP服务器

一种简单的方法，让LLMs在对话之间拥有持久的记忆。此服务器允许Claude或VSCode记住关于您、您的项目以及您的偏好的信息，使用知识图谱。

关键特性：

多种存储后端：推荐使用PostgreSQL或SQLite（本地文件）
项目隔离：保持不同项目的隔离（通过提示自动检测）
更好的搜索：使用模糊搜索和分页查找信息

完整设置指南

按照以下步骤操作，以使知识图谱与Claude一起工作：

第一步：选择安装方法

选项A：NPX（最简单 - 不需要下载）

# 测试是否正常工作
npx knowledgegraph-mcp --help

选项B：Docker

# 克隆并构建
git clone https://github.com/n-r-w/knowledgegraph-mcp.git
cd knowledgegraph-mcp
docker build -t knowledgegraph-mcp .

第二步：选择数据库

SQLite（默认 - 不需要设置）：

不需要安装数据库
数据库文件会自动创建在 [你的主目录]/.knowledge-graph/
适用于个人使用和大多数场景
这是默认后端

PostgreSQL（高级用户）：

在系统上安装PostgreSQL
创建一个数据库：CREATE DATABASE knowledgegraph;
对于多个并发用户的生产使用更佳

第三步：配置客户端

Claude桌面

编辑你的Claude桌面配置文件：

找到你的配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

如果你选择了NPX + SQLite（默认且最简单）：

{
  "mcpServers": {
    "知识图谱": {
      "命令": "npx",
      "参数": ["-y", "knowledgegraph-mcp"]
    }
  }
}

注意：SQLite会自动在 [你的主目录]/.knowledge-graph/knowledgegraph.db 中创建数据库。要使用自定义位置，请添加："KNOWLEDGEGRAPH_SQLITE_PATH": "/path/to/your/database.db"

如果你选择了Docker + SQLite（默认）：

{
  "mcpServers": {
    "知识图谱": {
      "命令": "docker",
      "参数": [
        "run", "-i", "--rm",
        "-v", "[你的主目录]/.knowledge-graph:/app/.knowledge-graph",
        "knowledgegraph-mcp"
      ]
    }
  }
}

注意：卷挂载确保了数据在Docker运行之间持久存在。对于自定义路径，请添加：-e KNOWLEDGEGRAPH_SQLITE_PATH=/app/.knowledge-graph/custom.db

如果你选择了PostgreSQL：

{
  "mcpServers": {
    "知识图谱": {
      "命令": "npx",
      "参数": ["-y", "knowledgegraph-mcp"],
      "环境变量": {
        "KNOWLEDGEGRAPH_STORAGE_TYPE": "postgresql",
        "KNOWLEDGEGRAPH_CONNECTION_STRING": "postgresql://postgres:yourpassword@localhost:5432/knowledgegraph"
      }
    }
  }
}

VS Code

如果你想在VS Code中也使用这个功能，可以在用户设置（JSON）中添加以下内容，或者创建 .vscode/mcp.json 文件：

使用NPX + SQLite（默认）：

{
  "mcp": {
    "服务器": {
      "知识图谱": {
        "命令": "npx",
        "参数": ["-y", "knowledgegraph-mcp"],
      }
    }
  }
}

使用Docker（默认SQLite）：

{
  "mcp": {
    "服务器": {
      "知识图谱": {
        "命令": "docker",
        "参数": [
          "run", "-i", "--rm",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=sqlite://./knowledgegraph.db",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

使用Docker + PostgreSQL：

首先，确保你的PostgreSQL数据库已设置好：

# 创建数据库（仅需运行一次）
psql -h 127.0.0.1 -p 5432 -U postgres -c "CREATE DATABASE knowledgegraph;"

然后配置VS Code：

{
  "mcp": {
    "服务器": {
      "知识图谱": {
        "命令": "docker",
        "参数": [
          "run", "-i", "--rm",
          "--network", "host",
          "-e", "KNOWLEDGEGRAPH_STORAGE_TYPE=postgresql",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=postgresql://postgres:yourpassword@127.0.0.1:5432/knowledgegraph",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

替代Docker + PostgreSQL（如果 --network host 不起作用）：

{
  "mcp": {
    "服务器": {
      "知识图谱": {
        "命令": "docker",
        "参数": [
          "run", "-i", "--rm",
          "--add-host", "host.docker.internal:host-gateway",
          "-e", "KNOWLEDGEGRAPH_STORAGE_TYPE=postgresql",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=postgresql://postgres:yourpassword@host.docker.internal:5432/knowledgegraph",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

重要注意事项：

将 yourpassword 替换为你实际的PostgreSQL密码

确保在启动前 knowledgegraph 数据库已存在

如果遇到连接错误，请尝试上述替代配置

对于Docker + PostgreSQL问题的故障排除，请参阅常见问题部分

第四步：选择你的LLM系统提示

定制化：

根据你的领域修改实体类型
调整搜索策略以适应你的数据模式
添加特定领域的标签和关系类型

LLM兼容性：

所有LLM表现不同。对某些LLM来说，一般指令就足够了，而另一些则需要详细描述一切
使用LLM解释为什么没有使用知识图谱。询问 解释为什么你没有使用知识图谱？不要做其他任何事情 以获得详细的报告并识别指令中的问题。

可用提示：

第五步：重启Claude桌面（或VS Code）

关闭并重新打开Claude桌面。你应该现在能看到“知识图谱”在可用工具中。

第六步：测试其是否工作

快速测试命令给LLM：

"记住我喜欢早上开会" → 创建偏好实体
"约翰·史密斯在谷歌担任软件工程师" → 创建人 + 公司 + 关系
"找出所有在谷歌工作的人" → 测试搜索和关系
"标记早上会议偏好为紧急" → 测试标签

注意：服务包括全面的输入验证以防止错误。如果遇到任何问题，请查看故障排除指南以获取常见解决方案。

工作原理 - LLM强大功能

知识图谱通过四个相互关联的概念实现强大的查询：

1. 实体 - 你的知识节点

存储人员、项目、公司、技术作为可搜索的实体。

真实示例 - 项目管理：

{
  "名称": "Sarah_Chen",
  "实体类型": "人员",
  "观察": ["资深React开发者", "领导前端团队", "可用于紧急任务"],
  "标签": ["开发者", "团队领导", "可用"]
}

LLM益处：通过标签搜索即时找到“所有可用的团队领导”。

2. 关系 - 启用发现查询

连接实体以回答复杂的问题，如“谁在做什么？”

真实示例 - 团队结构：

{
  "从": "Sarah_Chen",
  "到": "Project_Alpha",
  "关系类型": "领导"
}

LLM益处：查询“找出Sarah领导的所有项目”或“谁领导Project Alpha？”

3. 观察 - 原子事实

存储关于实体的具体、可搜索的事实。

真实示例 - 可操作信息：

“可用于紧急任务” → 查找可用人员
“使用React 18.2” → 查找具有特定技术的项目
“截止日期：2024年3月15日” → 查找即将到期的截止日期

4. 标签 - 即时过滤

启用即时状态和类别搜索。

真实示例 - 项目工作流程：

["紧急", "进行中", "前端"] → 查找紧急前端任务
["已完成", "修复错误"] → 跟踪已完成的错误修复
["可用", "资深"] → 查找可用的资深员工

配置选项

环境变量

服务器支持几个环境变量用于定制：

数据库配置

KNOWLEDGEGRAPH_STORAGE_TYPE：数据库类型（sqlite 或 postgresql，默认：sqlite）
KNOWLEDGEGRAPH_CONNECTION_STRING：数据库连接字符串
KNOWLEDGEGRAPH_SQLITE_PATH：自定义SQLite数据库路径（可选）
KNOWLEDGEGRAPH_PROJECT：用于数据隔离的项目标识符（默认：knowledgegraph_default_project）

搜索配置

KNOWLEDGEGRAPH_SEARCH_MAX_RESULTS：从数据库搜索返回的最大结果数（默认：100，最大：1000）
KNOWLEDGEGRAPH_SEARCH_BATCH_SIZE：处理大型查询数组的批处理大小（默认：10，最大：50）
KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES：客户端搜索加载的最大实体数（默认：10000，最大：100000）
KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE：客户端搜索处理大型数据集的块大小（默认：1000，最大：10000）

注意：搜索限制会自动验证并调整到安全范围，以防止性能问题。

性能优化

搜索系统包含几个性能优化：

实体加载限制：

KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES 限制客户端搜索加载的实体数量
防止大数据集的内存问题
达到限制时记录警告
适用于SQLite和PostgreSQL后端

分块处理：

KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE 控制大型实体集的块大小
当实体数量超过块大小时自动使用
改善内存使用和搜索性能
通过去重保持结果准确性

根据数据集大小推荐值：

小规模（< 1,000个实体）：默认值效果良好
中等规模（1,000 - 10,000个实体）：考虑 KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES=5000，KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE=500
大规模（> 10,000个实体）：尽可能使用数据库级搜索，或 KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES=2000，KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE=200

性能监控：

当应用限制时记录警告
自动记录分块以提高透明度
配置验证防止次优设置

可用工具

服务器提供这些工具来管理你的知识图谱：

数据创建工具

create_entities

创建新的实体（人员、概念、对象）在知识图谱中。

何时使用：用于尚未存在的实体
约束：每个实体必须至少有一个非空观察
行为：忽略已有名称的实体（使用add_observations更新）

输入：

entities（Entity[]）：实体对象数组。每个都需要：
- name（字符串）：唯一标识符，非空
- entityType（字符串）：类别（例如，'人员'，'项目'），非空
- observations（字符串[]）：关于实体的事实，必须包含至少一个非空字符串
- tags（字符串[]，可选）：精确匹配标签用于过滤
project_id（字符串，可选）：项目名称以隔离数据

create_relations

连接实体以启用强大的查询和发现。

立即好处：找出一家公司的所有人，使用某种技术的所有项目，所有依赖项
关键用途：团队结构，项目依赖项，技术堆栈
示例：'John works_at Google'，'React depends_on JavaScript'，'Project_Alpha managed_by Sarah'

输入：

relations（Relation[]）：关系对象数组。每个都需要：
- from（字符串）：源实体名称（必须存在）
- to（字符串）：目标实体名称（必须存在）
- relationType（字符串）：主动语态的关系类型（works_at，manages，depends_on，uses）
project_id（字符串，可选）：项目名称以隔离数据

add_observations

添加事实观察到现有实体。

要求：目标实体必须存在，每次更新至少一个非空观察
最佳实践：保持观察原子性和具体性

输入：

observations（ObservationUpdate[]）：观察更新数组。每个都需要：
- entityName（字符串）：目标实体名称（必须存在）
- observations（字符串[]）：要添加的新事实，必须包含至少一个非空字符串
project_id（字符串，可选）：项目名称以隔离数据

add_tags

添加状态/类别标签以实现即时过滤。

立即好处：按状态（紧急，完成，进行中）或类型（技术，个人）查找实体
必需：高效项目管理和快速检索
示例：['紧急', '完成', '错误', '功能', '个人']

输入：

updates（TagUpdate[]）：标签更新数组。每个都需要：
- entityName（字符串）：目标实体名称（必须存在）
- tags（字符串[]）：要添加的状态/类别标签（精确匹配，区分大小写）
project_id（字符串，可选）：项目名称以隔离数据

数据检索工具

read_graph

检索完整的知识图谱，包括所有实体和关系。

使用案例：全面概览，了解当前状态，看到所有连接
范围：返回指定项目中的所有内容

输入：

project_id（字符串，可选）：项目名称以隔离数据

search_knowledge

搜索实体通过文本或标签。支持多查询批量搜索。

强制策略：1）先尝试searchMode='exact' 2）如果没有结果，使用searchMode='fuzzy' 3）如果仍然为空，降低fuzzyThreshold至0.1
精确模式：完美的子串匹配（快速，精确）
模糊模式：相似/拼写错误的术语（较慢，更广泛）
标签搜索：使用exactTags进行精确类别过滤
多查询：在一个调用中搜索多个对象，并自动去重

输入：

query（字符串 | 字符串[]，可选）：文本搜索查询。可以是单个字符串或字符串数组用于多个对象搜索。当提供exactTags进行标签搜索时可选。
searchMode（字符串，可选）："exact" 或 "fuzzy"（默认："exact"）。只有在exact返回无结果时才使用fuzzy
fuzzyThreshold（数字，可选）：模糊相似度阈值。0.3=默认，0.1=非常宽泛，0.7=非常严格。较低值找到更多结果
exactTags（字符串[]，可选）：用于精确匹配搜索的标签（区分大小写）。用于类别过滤
tagMatchMode（字符串，可选）：对于exactTags："any"=具有任一标签的实体，"all"=具有所有标签的实体（默认："any"）
page（数字，可选）：分页的页码（0开始，默认：0）
pageSize（数字，可选）：每页的结果数（1-1000，默认：50）
project_id（字符串，可选）：项目名称以隔离数据

示例：

基本搜索：search_knowledge(query="JavaScript", searchMode="exact")
分页搜索：`search_knowledge(query="React", page=0, pageSize=2