MCP 服务器

Graphiti MCP Server

Graphiti 模型上下文协议 (MCP) 服务器 - 用于通过 Graphiti 进行知识图谱管理的 MCP 服务器

mateicanavra

研究与数据

访问服务器

README

Graphiti MCP 服务器

本仓库包含 Graphiti 模型上下文协议 (MCP) 服务器及其相关的命令行界面 (CLI) 工具。它允许 AI 代理使用 Graphiti 框架与知识图谱进行交互，以实现持久内存、实体提取和关系跟踪。

功能特性

通过 MCP（SSE 或 Stdio 传输）公开 Graphiti 功能。
提供用于在知识图谱中添加/搜索事件、节点和事实的工具。
支持自定义实体类型定义，以实现定制的提取。
包含一个 CLI (graphiti)，用于项目初始化、实体管理和 Docker 环境控制。
使用 Docker Compose 轻松部署 MCP 服务器和 Neo4j 数据库。
利用 uv 进行快速依赖管理。

前提条件

Python: 3.10 或更高版本 (python3 --version)。推荐使用 Python 3.11+（如 Dockerfile 中所用）。
Docker & Docker Compose: 运行 Neo4j 数据库和 MCP 服务器容器所必需。从 Docker 官方网站安装。

uv: 一个快速的 Python 包安装器和解析器。如果您没有安装，请先安装它（需要 pip 或 curl）：

# 使用 pip (如果您已经安装了 Python/pip，推荐使用)
pip install uv
# 或者使用 curl
# curl -LsSf https://astral.sh/uv/install.sh | sh
# source $HOME/.cargo/env # 或者您的 shell 的等效命令，如果使用 curl 方法

# 验证安装
uv --version

Git: 用于克隆仓库。

安装和设置指南

本指南介绍如何安装 graphiti CLI 并设置必要的环境。选择最适合您需求的路径：

对于普通用户（推荐）： 使用 pipx 全局安装 CLI，以管理项目和运行服务。
对于开发者： 如果您计划修改 CLI 或服务器代码，请使用 venv 设置本地开发环境。

1. 用户的标准安装（使用 `pipx`）

如果您主要想使用 graphiti CLI 来初始化项目、管理实体和运行 Docker 服务，这是强烈推荐的方法。pipx 将 CLI 安装到一个隔离的环境中，使其在系统范围内可用，而不会干扰其他 Python 项目。

为什么选择 pipx？

隔离： 防止依赖冲突。
干净的全局环境： 保持您的系统 Python 整洁。
安全： 避免使用 sudo pip 或修改系统 Python 带来的问题。

前提条件：

Python: 3.10+ (python3 --version)。
Docker & Docker Compose: 从 Docker 官方网站安装。
uv: 按照上面的前提条件部分中的说明进行操作。

pipx: 如果您没有安装：

# 安装 pipx (需要 Python 和 pip)
python3 -m pip install --user pipx
# 将 pipx 添加到您的 PATH
python3 -m pipx ensurepath
# 关闭并重新打开您的终端，或 source 您的 shell 配置文件（例如，~/.zshrc, ~/.bashrc）

步骤：

克隆此仓库： 您需要源代码来构建 CLI 并访问配置文件（如 base-compose.yaml）。将其克隆到一个稳定的位置（例如，~/dev/rawr-mcp-graphiti）。
```
# 选择一个合适的父目录
cd ~/dev
git clone <repository-url> rawr-mcp-graphiti
cd rawr-mcp-graphiti
```
配置环境变量（可选但推荐）：
- 复制示例 .env 文件 在克隆的仓库中：
```
# 确保您在克隆的仓库目录中（例如，~/dev/rawr-mcp-graphiti）
cp .env.example .env
```
- 编辑 .env： 填写所需的密钥和配置（Neo4j 凭据、OpenAI 密钥等）。有关详细信息，请参阅开发者设置下的“配置环境”部分。
使用 pipx 安装 CLI： 在您的终端中导航到克隆的仓库的根目录 (rawr-mcp-graphiti) 并运行：
```
# 确保您在克隆的仓库目录中
pipx install . --include-deps
```
- 这会将 rawr-mcp-graphiti 包安装到一个隔离的 pipx 环境中。
- --include-deps 确保包含必要的运行时依赖项。
首次运行和仓库路径配置：
- 首次运行需要访问仓库的 graphiti 命令（如 graphiti check-setup 或 graphiti compose）时，它可能无法自动找到仓库。
- 如果找不到，CLI 将以交互方式提示您输入克隆 rawr-mcp-graphiti 仓库的绝对路径。
- 输入正确的绝对路径（例如，/Users/your_user/dev/rawr-mcp-graphiti）。
- CLI 将验证路径并将其保存到配置文件 (~/.config/graphiti/repo_path.txt) 以供将来使用。
```
# 示例：从安装后的任何目录运行 check-setup
graphiti check-setup
# 如果需要，它将在此处提示输入仓库路径。
```

验证安装：

# 检查 pipx 将其安装在哪里
which graphiti
# 应该输出一个类似这样的路径：/Users/<your_user>/.local/bin/graphiti

# 验证 CLI 运行并且可以找到仓库（由于 MCP_GRAPHITI_REPO_PATH）
# 从任何目录运行此命令（例如，您的主目录 `cd ~`）
graphiti --help
graphiti check-setup # 如果已配置，现在应该可以从任何地方工作，而无需提示

如果 check-setup 失败，请确保保存在 ~/.config/graphiti/repo_path.txt 中的路径正确，或者删除该文件并再次运行该命令以重新提示。

更新： 在仓库中拉取更改后进行更新：

# 导航回仓库根目录
cd /path/to/your/rawr-mcp-graphiti
# 拉取最新的更改
git pull
# 升级 pipx 安装
pipx upgrade rawr-mcp-graphiti
# 如果需要，强制从更新的源重新安装：
# pipx reinstall --force rawr-mcp-graphiti

用户摘要： 克隆仓库，复制/编辑 .env，使用 pipx 安装。运行类似 graphiti check-setup 的命令；如果提示，请提供克隆仓库的绝对路径。该路径将自动保存以供将来使用。

2. 本地开发安装（使用 `venv`）

仅当您打算修改或贡献 graphiti CLI 或 MCP 服务器代码库本身时，才按照以下步骤操作。此设置使用 Python 虚拟环境 (.venv) 和可编辑安装，允许在激活的环境中运行 graphiti 时立即反映代码更改。

前提条件：

与标准安装相同（Python、Docker、uv）。此方法不需要 pipx。

步骤：

克隆仓库：

git clone <repository-url> rawr-mcp-graphiti
cd rawr-mcp-graphiti

配置环境：
- 复制示例环境文件：
```
cp .env.example .env
```
- 编辑 .env： 填写所需的密钥和配置：
  - NEO4J_USER, NEO4J_PASSWORD: Neo4j 的凭据。
  - OPENAI_API_KEY: OpenAI 密钥。
  - MODEL_NAME: (可选) OpenAI 模型。
  - 如果需要，调整其他设置（端口、内存）。
  - MCP_GRAPHITI_REPO_PATH: 虽然从活动的 venv 和仓库根目录运行的 CLI 可能会自动找到根目录，但现在建议依赖自动提示或首次使用时生成的配置文件 (~/.config/graphiti/repo_path.txt)（即使在 venv 中）。如果需要，您仍然可以将环境变量设置为手动覆盖。

设置 Python 虚拟环境：

# 创建虚拟环境
python3 -m venv .venv
# 激活它（macOS/Linux 示例）
source .venv/bin/activate
# 您应该在提示符中看到 (.venv)

安装依赖项：
- 使用 uv 将锁定文件中的依赖项安装到活动的 venv 中。
```
# 确保 (.venv) 已激活
uv pip sync uv.lock
```
以可编辑模式安装 CLI：
- 以可编辑模式 (-e) 安装包本身。这会将 venv 中的 graphiti 命令直接链接到您的源代码。
```
# 确保 (.venv) 已激活
pip install -e .
# ('uv pip install -e .' 应该也可以工作)
```

验证安装：

# 验证它是否使用 venv 路径
which graphiti
# 应该输出 .venv/bin/ 中的路径

# 验证 CLI 运行（确保 venv 已激活）
graphiti --help
graphiti check-setup # 从仓库根目录运行

开发者摘要： 克隆，复制/编辑 .env，设置 .venv，激活它，uv pip sync，pip install -e .。从仓库根目录运行命令，并激活 venv。仓库路径将被自动检测或提示并保存在首次使用时。

了解您正在使用的哪个 `graphiti`

全局 (pipx): 如果您的提示符中没有 (.venv)，您可能正在使用 pipx 版本。它依赖于存储在 ~/.config/graphiti/repo_path.txt 中的路径（或在首次使用时提示）。更新需要 pipx upgrade。
本地 (venv): 如果在 source .venv/bin/activate 之后，您的提示符中出现 (.venv)，则您正在使用可编辑的开发版本。代码更改是实时的。理想情况下，从仓库根目录运行。使用 deactivate 停用。

验证您的设置

无论使用哪种安装方法，都使用 check-setup。

如果使用 pipx： 从任何目录运行 graphiti check-setup。它依赖于 ~/.config/graphiti/repo_path.txt 中配置的路径（或提示）。
如果使用 venv： 激活 venv (source .venv/bin/activate) 并从仓库根目录运行 graphiti check-setup。

# pipx 用户示例（从任何地方运行）：
graphiti check-setup

# 开发者示例（首先激活 venv，从仓库根目录运行）：
# source .venv/bin/activate
# graphiti check-setup

此命令检查：

仓库根目录： 查找根目录（通过配置文件 ~/.config/graphiti/repo_path.txt、环境变量覆盖或 venv 的相对路径）。
.env 文件： 检查 .env 文件是否存在于已识别的仓库根目录，以及是否加载了必要的变量。
Docker 状态： 验证 docker 命令在您的 PATH 中是否可用，以及 Docker 守护程序是否正在运行并响应。

如果所有检查都通过，您就可以继续了。

运行服务 (Docker)

MCP 服务器及其 Neo4j 数据库作为 Docker 容器运行，由 Docker Compose 管理。这些命令 (compose、up、down 等) 必须从 rawr-mcp-graphiti 仓库的根目录运行。 确保您的 CLI（pipx 或 venv）已正确设置并且可以找到仓库根目录。

生成 Docker Compose 配置：
- graphiti CLI 从 base-compose.yaml（在仓库中）和 mcp-projects.yaml（也在仓库中）中的项目定义生成最终的 docker-compose.yml。
- 导航到仓库根目录并运行：
```
# cd /path/to/your/rawr-mcp-graphiti
graphiti compose
```
- 此命令读取 mcp-projects.yaml。如果您使用 graphiti init 初始化新项目，则此文件将自动更新为您的项目的绝对路径。确保这些路径对于您的系统是正确的，因为它们用于 Docker 卷挂载。
- 它还会更新每个启用的项目根目录中的 .cursor/mcp.json 文件。
启动服务：
- 构建并启动容器（Neo4j、根 MCP 服务器以及 mcp-projects.yaml 中定义的任何特定于项目的服务器）：
```
graphiti up
```
- 要在分离模式下运行（在后台）：
```
graphiti up -d
```
- 首次运行此命令时，Docker 可能会构建 graphiti-mcp-server 镜像。后续启动速度更快。
- 根 MCP 服务器通常在 http://localhost:8000 上可用（或 .env 中 MCP_ROOT_HOST_PORT 指定的端口）。特定于项目的服务器将在从 8001 开始顺序分配的端口上可用（或在其各自的 mcp-config.yaml 文件中配置的端口上）。检查 graphiti compose 的输出以获取端口分配。
- 您通常可以在 Web 浏览器中通过 http://localhost:7474 访问 Neo4j Browser UI，以直接与数据库交互（使用 .env 文件中的凭据）。
检查状态：
- 查看正在运行的容器：docker ps
- 查看日志：graphiti logs 或 docker compose logs -f [service_name]（例如，docker compose logs -f graphiti-mcp-root）
停止服务：
- 停止并删除容器：
```
graphiti down
```
其他 Docker 命令：
- 重启服务：graphiti restart [-d]（运行 down 然后 up）
- 重新加载（重启）特定服务：graphiti reload <service_name>（例如，graphiti reload graphiti-mcp-root）

使用 `graphiti` CLI

graphiti CLI 帮助管理项目和 Docker 环境。运行 graphiti --help 查看所有命令。

关键命令位置：

从仓库根目录运行 (rawr-mcp-graphiti/)：
- graphiti compose: 生成 docker-compose.yml。
- graphiti up|down|restart|reload|logs: 管理 Docker 服务。
- graphiti check-setup: 验证设置（对于 venv 用户尤其有用）。
从项目父目录运行：
- graphiti init <project_name> [target_dir]: 在指定目录中初始化新的项目结构。
从现有项目根目录运行：
- graphiti entity <set_name>: 在此项目的 entities 目录中创建新的实体定义模板。
- graphiti rules <project_name>: 为此项目设置/更新 Cursor 规则符号链接。

示例工作流程：

安装 CLI（推荐用户使用 pipx）。
cd /path/to/your/rawr-mcp-graphiti
graphiti compose
graphiti up -d (启动服务)
cd /path/to/where/you/keep/projects
graphiti init my-new-ai-project
cd my-new-ai-project
graphiti entity user-profiles (在 ./ai/graph/entities/ 中创建实体定义)
编辑 user-profiles.yaml...
my-new-ai-project 现在已在 mcp-projects.yaml（在仓库根目录中）中注册。如果您重新运行 graphiti compose 和 graphiti up -d（从仓库根目录），则可能会启动此项目的专用 MCP 服务器实例（取决于基本配置）。

开发说明

生成 uv.lock： 如果 uv.lock 文件丢失或已过期，您可以使用以下命令从 pyproject.toml 重新生成它：

# 激活 venv
uv pip compile pyproject.toml --output-file uv.lock
# 或者可能只是：uv pip lock
# 将更新的 uv.lock 文件提交到仓库。

本地 graphiti-core 开发： 如果您正在本地开发 graphiti-core 以及此服务器：
1. 在 graphiti-core 仓库中构建 graphiti-core wheel 文件（例如，python3 -m build）。这将在其 dist/ 目录中创建文件。
2. 确保包含 .whl 文件的 dist/ 目录存在于主 Graphiti 仓库的根目录（rawr-mcp-graphiti 上一级）。路径可能需要根据提取后的确切结构进行调整。
3. 在 rawr-mcp-graphiti/pyproject.toml 中，确保取消注释行 graphiti-core = {path = "../dist/graphiti_core-...-py3-none-any.whl"}（调整路径/文件名）。注释掉版本化的行 graphiti-core>=...。
4. 在您的 venv 中重新运行 uv pip sync uv.lock 或 pip install -e .。
5. 如果 Docker 构建过程没有自动从 venv 中获取本地 wheel 安装，则可能还需要进行调整。如果需要，考虑在 Dockerfile 的构建器阶段添加 COPY ../dist /dist 和 RUN uv pip install /dist/*.whl。

在没有 Docker 的情况下运行服务器： 您可以直接运行服务器进行调试：

# 确保 .env 已加载或变量已导出
# 激活 venv: source .venv/bin/activate
# 示例：
python3 graphiti_mcp_server.py --transport sse --group-id my-test-group --log-level debug
# 根据需要添加其他标志，如 --use-custom-entities, --entity-type-dir

⚠️ 危险区域：清除数据库 ⚠️

.env 文件中的环境变量 NEO4J_DESTROY_ENTIRE_GRAPH 极其危险。

将 NEO4J_DESTROY_ENTIRE_GRAPH=true 设置为 true 将在容器启动时永久删除 Neo4j 数据库中的所有数据。
这会影响所有知识图谱，而不仅仅是特定的 group_id。
此操作无法撤消。
仅当您绝对确定要擦除整个数据库时，才将其设置为 true。
使用后立即将其注释掉或将其设置回 false，以防止在后续重启时意外丢失数据。