KnowledgeGraph MCP Server

警告

我对这类自动化上下文管理工具已经不再抱有幻想，因为它几乎无法控制。过一段时间后，我总是不得不手动收拾残局，或者纠正大模型不恰当的记录。 于是，我创建了一个工具，让大模型 Agent 能够访问动态加载的上下文。不过，上下文本身是由用户创建的：https://github.com/n-r-w/agent-standards-mcp

KnowledgeGraph MCP 服务

一种让大模型跨对话拥有持久记忆的简单方法。该服务让 Claude 或 vscode 能够使用知识图谱记住关于你、你的项目和你的偏好的信息。

主要特性：

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

完整设置指南

按顺序执行以下步骤，让知识图谱与 Claude 配合工作：

第 1 步：选择你的安装方式

方式 A：NPX（最简单 - 无需下载）

# Test that it works
npx knowledgegraph-mcp --help

方式 B：Docker

# Clone and build
git clone https://github.com/n-r-w/knowledgegraph-mcp.git
cd knowledgegraph-mcp
docker build -t knowledgegraph-mcp .

第 2 步：选择你的数据库

SQLite（默认 - 无需设置）：

• 无需安装数据库
• 数据库文件会自动创建在 [you home folder]/.knowledge-graph/
• 非常适合个人使用和大多数场景
• 这是默认后端

PostgreSQL（适合高级用户）：

• 在你的系统上安装 PostgreSQL
• 创建数据库：CREATE DATABASE knowledgegraph;
• 更适合有多个并发用户的生产环境使用

第 3 步：配置客户端

Claude Desktop

编辑你的 Claude Desktop 配置文件：

找到你的配置文件：

• 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": {
    "Knowledge Graph": {
      "command": "npx",
      "args": ["-y", "knowledgegraph-mcp"]
    }
  }
}

注意：SQLite 会自动在 [you home folder]/.knowledge-graph/knowledgegraph.db 中创建数据库。要使用自定义路径，请添加："KNOWLEDGEGRAPH_SQLITE_PATH": "/path/to/your/database.db"

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

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "[you home folder]/.knowledge-graph:/app/.knowledge-graph",
        "knowledgegraph-mcp"
      ]
    }
  }
}

注意：卷挂载可确保你的数据在多次 Docker 运行之间持久保留。要使用自定义路径，请添加：-e KNOWLEDGEGRAPH_SQLITE_PATH=/app/.knowledge-graph/custom.db

如果你选择 PostgreSQL：

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "npx",
      "args": ["-y", "knowledgegraph-mcp"],
      "env": {
        "KNOWLEDGEGRAPH_STORAGE_TYPE": "postgresql",
        "KNOWLEDGEGRAPH_CONNECTION_STRING": "postgresql://postgres:yourpassword@localhost:5432/knowledgegraph"
      }
    }
  }
}

VS Code

如果你还想在 VS Code 中使用它，请将以下内容添加到你的用户设置（JSON）中，或创建 .vscode/mcp.json：

使用 NPX + SQLite（默认）：

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "npx",
        "args": ["-y", "knowledgegraph-mcp"],
      }
    }
  }
}

使用 Docker（默认 SQLite）：

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=sqlite://./knowledgegraph.db",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

使用 Docker + PostgreSQL：

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

# Create the database (run this once)
psql -h 127.0.0.1 -p 5432 -U postgres -c "CREATE DATABASE knowledgegraph;"

然后配置 VS Code：

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "--network", "host",
          "-e", "KNOWLEDGEGRAPH_STORAGE_TYPE=postgresql",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=postgresql://postgres:[email protected]:5432/knowledgegraph",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

备选 Docker + PostgreSQL（如果 --network host 无法正常工作）：

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "--add-host", "host.docker.internal:host-gateway",
          "-e", "KNOWLEDGEGRAPH_STORAGE_TYPE=postgresql",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=postgresql://postgres:[email protected]:5432/knowledgegraph",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

重要提示：

• 将 yourpassword 替换为你实际的 PostgreSQL 密码
• 启动前确保 knowledgegraph 数据库已存在
• 如果遇到连接错误，请尝试上面的备选配置
• 有关 Docker + PostgreSQL 问题的故障排除，请参阅常见问题部分

第 4 步：选择你的大模型系统提示词

自定义：

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

大模型兼容性：

• 所有大模型的表现各不相同。对某些模型来说，通用指令就足够了，而其他模型则需要详细描述一切
• 使用 LLM 解释它为什么没有使用知识图谱。向它提问 Explain STEP-BY-STEP why you didn't use the knowledge graph? DO NOT DO ANYTHING ELSE，以获取详细报告并找出指令中的问题。

可用提示词：

• 知识图谱
• 任务管理
• 代码质量
• 一体化
• 维护知识图谱

第 5 步：重启 Claude Desktop（或 VS Code）

关闭并重新打开 Claude Desktop。你现在应该能在可用工具中看到 "Knowledge Graph"。

第 6 步：测试其是否正常工作

面向大模型的快速测试命令：

1. "Remember that I prefer morning meetings" → 创建偏好实体
2. "John Smith works at Google as a software engineer" → 创建人员 + 公司 + 关系
3. "Find all people who work at Google" → 测试搜索和关系
4. "Mark the morning meetings preference as urgent" → 测试标签

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

工作原理 - 大模型强大功能

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

1. 实体 - 你的知识节点

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

真实示例 - 项目管理：

{
  "name": "Sarah_Chen",
  "entityType": "person",
  "observations": ["Senior React developer", "Leads frontend team", "Available for urgent tasks"],
  "tags": ["developer", "team-lead", "available"]
}

大模型收益： 通过标签搜索即时找到"所有可用的团队负责人"。

2. 关系 - 实现发现式查询

连接实体以回答诸如"谁负责什么工作？"之类的复杂问题。

真实示例 - 团队结构：

{
  "from": "Sarah_Chen",
  "to": "Project_Alpha",
  "relationType": "leads"
}

大模型收益： 查询"查找 Sarah 领导的所有项目"或"谁领导 Project Alpha？"

3. 观察 - 原子事实

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

真实示例 - 可操作信息：

• "Available for urgent tasks" → 查找可用人员
• "Uses React 18.2" → 查找使用特定技术的项目
• "Deadline: March 15, 2024" → 查找即将到来的截止日期

4. 标签 - 即时筛选

实现即时的状态和类别搜索。

真实示例 - 项目工作流：

• ["urgent", "in-progress", "frontend"] → 查找紧急前端任务
• ["completed", "bug-fix"] → 跟踪已完成的 bug 修复
• ["available", "senior"] → 查找可用的高级员工

配置选项

环境变量

该服务支持多个用于自定义的环境变量：

数据库配置

• 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

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

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

输入：

• entities (Entity[])：实体对象数组。每个对象需要：
  • name (string)：唯一标识符，非空
  • entityType (string)：类别（例如 'person'、'project'），非空
  • observations (string[])：关于实体的事实，必须包含至少 1 个非空字符串
  • tags (string[]，可选)：用于筛选的精确匹配标签
• project_id (string，可选)：用于隔离数据的项目名称

create_relations

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

• 即时收益： 查找某公司的所有人员、使用某项技术的所有项目、所有依赖关系
• 关键用途： 团队结构、项目依赖、技术栈
• 示例： 'John works_at Google'、'React depends_on JavaScript'、'Project_Alpha managed_by Sarah'

输入：

• relations (Relation[])：关系对象数组。每个对象需要：
  • from (string)：源实体名称（必须存在）
  • to (string)：目标实体名称（必须存在）
  • relationType (string)：使用主动语态的关系类型（works_at、manages、depends_on、uses）
• project_id (string，可选)：用于隔离数据的项目名称

add_observations

向现有实体添加事实性观察。

• 要求： 目标实体必须存在，每次更新至少 1 条非空观察
• 最佳实践： 保持观察原子化且具体

输入：

• observations (ObservationUpdate[])：观察更新数组。每个对象需要：
  • entityName (string)：目标实体名称（必须存在）
  • observations (string[])：要添加的新事实，必须包含至少 1 个非空字符串
• project_id (string，可选)：用于隔离数据的项目名称

add_tags

添加状态/类别标签，以便即时筛选。

• 即时收益： 按状态（urgent、completed、in-progress）或类型（technical、personal）查找实体
• 必需： 用于高效的项目管理和快速检索
• 示例： ['urgent', 'completed', 'bug', 'feature', 'personal']

输入：

• updates (TagUpdate[])：标签更新数组。每个对象需要：
  • entityName (string)：目标实体名称（必须存在）
  • tags (string[])：要添加的状态/类别标签（精确匹配、区分大小写）
• project_id (string，可选)：用于隔离数据的项目名称

数据检索工具

read_graph

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

• 使用场景： 全面概览、了解当前状态、查看所有连接
• 范围： 返回指定项目中的所有内容

输入：

• project_id (string, 可选): 用于隔离数据的项目名称

search_knowledge

搜索按文本或标签查找实体。支持多个查询以进行批量搜索。

• 强制策略： 1) 首先尝试 searchMode='exact' 2) 如果没有结果，使用 searchMode='fuzzy' 3) 如果仍为空，将 fuzzyThreshold 降低到 0.1
• 精确模式： 完全子字符串匹配（快速、精确）
• 模糊模式： 相似/拼写错误的词条（较慢、范围更广）
• 标签搜索： 使用 exactTags 进行精确分类过滤
• 多个查询： 在一次调用中搜索多个对象并自动去重

输入：

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

示例：

• 基本搜索: search_knowledge(query="JavaScript", searchMode="exact")
• 分页搜索: search_knowledge(query="React", page=0, pageSize=20)
• 大型数据集: search_knowledge(query="components", page=2, pageSize=100)
• 多个查询: search_knowledge(query=["JavaScript", "React"], page=0, pageSize=30)
• 标签 + 分页: search_knowledge(query="React", exactTags=["frontend"], page=1, pageSize=25)
• 仅标签搜索: search_knowledge(exactTags=["urgent", "bug"], tagMatchMode="all") - 无需查询

分页优势：

• 性能：使用 OFFSET/LIMIT 进行数据库级分页，高效处理大型数据集
• 内存：通过限制每次请求的结果数量减少内存使用
• 导航：分页元数据提供 totalPages、currentPage 和导航提示
• 可扩展性：高效处理包含数千个实体的知识图谱

open_nodes

检索按精确名称获取特定实体及其相互连接。

• 返回： 请求的实体以及它们之间的关系
• 使用场景： 当你知道精确的实体名称并希望获取详细信息时

输入：

• names (string[]): 要检索的实体名称数组
• project_id (string, 可选): 用于隔离数据的项目名称

数据管理工具

delete_entities

永久删除实体及其所有关系。

• 警告： 无法撤销，会级联移除所有连接
• 使用场景： 实体不再相关或创建时出错

输入：

• entityNames (string[]): 要删除的实体名称数组
• project_id (string, 可选): 用于隔离数据的项目名称

delete_observations

从实体中移除特定观察记录，同时保持实体完好。

• 使用场景： 纠正错误信息或移除过时细节
• 保留： 实体和其他观察记录保持不变

输入：

• deletions (ObservationDeletion[]): 删除请求数组。每个请求需要：
  • entityName (string): 目标实体名称
  • observations (string[]): 要移除的特定观察记录
• project_id (string, 可选): 用于隔离数据的项目名称

delete_relations

当连接发生变化时，更新关系结构。

• 关键场景： 职位变动（移除旧的 'works_at'）、项目完成（移除 'assigned_to'）、技术迁移（移除旧的 'uses'）
• 维护目标： 准确的网络结构，并防止混淆
• 工作流： 创建新关系时，始终移除过时的关系

输入：

• relations (Relation[])：要删除的关系数组。每个关系 REQUIRES：
  • from (string)：源实体名称
  • to (string)：目标实体名称
  • relationType (string)：要移除的确切关系类型
• project_id (string, optional)：用于隔离数据的项目名称

remove_tags

通过移除过时标签来更新实体状态。

• 关键场景： 用于状态跟踪 - 完成时移除 'in-progress'，解决后移除 'urgent'
• 维护目标： 干净的搜索结果和准确的状态
• 工作流： 添加新状态标签时，始终移除旧的状态标签

输入：

• updates (TagUpdate[])：标签移除请求数组。每个请求 REQUIRES：
  • entityName (string)：目标实体名称
  • tags (string[])：要移除的过时标签（精确匹配、区分大小写）
• project_id (string, optional)：用于隔离数据的项目名称

开发与测试

多后端测试

本项目包含全面的多后端测试，以确保在 SQLite 和 PostgreSQL 上的兼容性：

针对两个后端运行测试：

npm run test:multi-backend

运行所有测试（原始 + 多后端）：

npm run test:all-backends

使用 Taskfile（如果已安装）：

task test:multi-backend
task test:comprehensive

开发设置

克隆并设置：

git clone https://github.com/n-r-w/knowledgegraph-mcp.git
cd knowledgegraph-mcp
npm install
npm run build

运行测试：

npm test                    # All tests including multi-backend
npm run test:unit          # Unit tests only
npm run test:performance   # Performance benchmarks

故障排除

如果您在设置或使用过程中遇到任何问题，请参阅我们的全面故障排除指南，其中涵盖：

• 输入验证错误
• 数据库连接问题
• 配置问题
• Docker 相关挑战
• 测试执行失败
• 性能优化

该指南包含针对常见问题的分步解决方案，以及帮助识别问题的诊断命令。

基于 MCP Memory Server

这是官方 MCP Memory Server 的增强版本，具有额外功能：

• 多种存储选项：PostgreSQL（推荐）或 SQLite（本地文件）
• 项目隔离：保持不同项目相互隔离
• 更好的搜索：使用模糊搜索查找信息
• 易于设置：Docker 支持和简单安装

许可证

MIT License - 可自由使用、修改和分发本软件。