【Graphiti MCP Server 配置与使用教程 (优化版)】

提示：文章写完后，目录可以自动生成，如何生成可参考右边的帮助文档

---

Graphiti MCP Server 配置与使用教程 (优化版)

简介

Graphiti MCP 是一个强大的工具，它利用知识图谱来记录项目开发过程中的关键信息（如 Bug 修复、技术选型、编码规范等）。这使得 AI IDE 在辅助开发时能够始终遵循项目的规范标准，从而显著提升开发效率。

本教程将引导您完成 Graphiti MCP Server 的部署与配置，示例将使用硅基流动的 API（兼容类 OpenAI 接口）。

一、前置准备

在开始部署前，请确保您的环境满足以下要求：

• Python: 3.10 或更高版本（需支持 uv 包管理器）
• Neo4j: 5.26 或更高版本（推荐使用 Neo4j Desktop 以简化管理）
• uv: 高性能 Python 包管理器（替代 pip）

二、部署详细步骤

1. 安装 uv 包管理器

uv 是一款高效的 Python 包管理器。安装命令如下：

curl -LsSf https://astral.sh/uv/install.sh | sh

注意: 如果遇到网络问题，可以考虑使用国内镜像源，例如 Gitee 提供的相关项目。

2. 部署 Neo4j 数据库

Neo4j 是 Graphiti 的核心存储组件。

• 推荐方式: 使用 Neo4j Desktop 进行安装和管理。
  • 下载地址: Neo4j Desktop 官方下载
  • 安装后，创建一个新项目并启动数据库实例。
  • 记录关键信息: 记下数据库的连接 URI (通常是 bolt://localhost:7687)、用户名和密码。
  • 重要: 首次启动时，系统会提示您修改默认密码。请务必修改，并在后续配置中使用新密码。

3. 部署 Graphiti MCP Server

3.1 克隆代码库

git clone https://github.com/getzep/graphiti.git
cd graphiti/mcp_server

3.2 (可选) 配置国内 PyPI 源加速依赖安装

为加速依赖下载，可以修改 pyproject.toml 文件，添加清华源：

# 在 pyproject.toml 文件中添加或修改以下部分
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

3.3 安装依赖

使用 uv 安装项目所需依赖：

uv sync

3.4 配置环境变量

复制示例配置文件并根据您的环境进行修改：

cp .env.example .env

编辑 .env 文件，关键配置项说明如下（以硅基流动为例）：

# Graphiti MCP Server Environment Configuration# Neo4j 数据库配置 (必填)
NEO4J_URI=bolt://localhost:7687        # Neo4j 数据库地址
NEO4J_USER=your_neo4j_username         # 您设置的 Neo4j 用户名
NEO4J_PASSWORD=your_neo4j_password     # 您设置的 Neo4j 密码# 大模型 API 配置 (必填)
OPENAI_API_KEY=your_siliconflow_api_key # 从硅基流动平台获取的 API 密钥
MODEL_NAME=Qwen/Qwen3-30B-A3B-Instruct-2507       # 主对话模型
SMALL_MODEL_NAME=Qwen/Qwen3-30B-A3B-Instruct-2507 # 辅助分析模型 (注意：此项为隐藏必填)
EMBEDDER_MODEL_NAME=Qwen/Qwen3-Embedding-4B       # 嵌入模型 (注意：此项为隐藏必填)# API 端点配置 (非 OpenAI 官方接口时必填)
OPENAI_BASE_URL=https://api.siliconflow.cn/v1     # 硅基流动 API 地址# 可选配置
# GROUP_ID=my_project                             # 项目命名空间，用于多项目隔离
# PATH=/root/.local/bin:${PATH}                   # Docker 环境下的路径配置 (示例)

重要注意事项:

• SMALL_MODEL_NAME 和 EMBEDDER_MODEL_NAME 是隐藏必填项，原配置文件可能未明确标注，缺失会导致服务启动失败。
• 官方推荐使用具有较大上下文窗口的模型（如 Qwen3 系列）。
• 对于其他类 OpenAI 接口，只需替换 OPENAI_BASE_URL 和对应的模型名称即可。

三、配置 MCP 服务 (以 Augment Code 为例)

为了让您的 AI IDE (如 Cursor, Cline, 或其他支持 MCP 的客户端) 能够连接到 Graphiti 服务，需要在 IDE 的 MCP 配置文件中添加 Graphiti 服务的定义。

以下是一个典型的配置示例 (mcp/config.json 或类似位置)：

{"mcpServers": {"Graphiti": {"command": "uv", // 如果 uv 不是全局命令，请指定完整路径，例如 "/path/to/uv""args": ["run","--isolated","--directory","/path/to/your/graphiti/mcp_server", // 请替换为您的实际本地路径"--project",".","graphiti_mcp_server.py","--transport","stdio"],"env": {"NEO4J_URI": "bolt://localhost:7687","NEO4J_USER": "your_neo4j_username","NEO4J_PASSWORD": "your_neo4j_password"// 如果 .env 文件中的环境变量未生效，可以在这里显式添加 OPENAI_API_KEY 等}}}
}

四、启动与使用

1. 确保 Neo4j 数据库正在运行。
2. 在 IDE 中启用或重启 MCP 服务，使其加载新的配置。
3. 在支持的 AI IDE 中开始编码，Graphiti 将开始记录和利用您的项目知识。

五、参考资料

• Graphiti GitHub Repository
• Neo4j Desktop
• uv Package Manager
• 硅基流动平台 (示例 API 提供方)
• MCP (Model Context Protocol) Specification

六、优化提示词分享

你是一名经验丰富的[专业领域，例如：软件开发工程师/系统设计师/代码架构师]，专注于构建[核心特长，例如：高性能/可维护/健壮/领域驱动]的解决方案。你的任务是：**审查、理解并迭代式地改进/推进一个[项目类型，例如：现有代码库/软件项目/技术流程]。**在整个工作流程中，你必须内化并严格遵循以下**核心编码原则（由 LD/AR 推动，AI 编码时必须全程遵守）**，确保你的每次输出和建议都体现这些理念：- **简单至上 (KISS)：** 追求代码和设计的极致简洁与直观，避免不必要的复杂性。
- **精益求精 (YAGNI)：** 仅实现当前明确所需的功能，抵制过度设计和不必要的未来特性预留。
- **坚实基础 (SOLID)：**- **S (单一职责)：** 各组件、类、函数只承担一项明确职责。- **O (开放/封闭)：** 功能扩展无需修改现有代码。- **L (里氏替换)：** 子类型可无缝替换其基类型。- **I (接口隔离)：** 接口应专一，避免“胖接口”。- **D (依赖倒置)：** 依赖抽象而非具体实现。
- **杜绝重复 (DRY)：** 识别并消除代码或逻辑中的重复模式，提升复用性。
- **高内聚低耦合：** 模块内部组件紧密关联（高内聚），模块间依赖最小化（低耦合），降低系统复杂度。
- **代码可读性：** 通过清晰命名、合理注释、规范格式，确保代码易于理解和维护。
- **可测试性：** 设计时考虑测试需求，使代码易于编写单元测试、集成测试，提升质量保障效率。
- **安全编码：** 遵循安全最佳实践，防范注入攻击、权限漏洞、数据泄露等潜在风险。**请严格遵循以下工作流程和输出要求：**## 1. 深入理解与初步分析（理解阶段）- **结合 Graphiti MCP 工具预处理：**- 开始任务前，使用`search_nodes`工具查找与当前项目相关的偏好设置（指定"Preference"实体类型）和程序规范（指定"Procedure"实体类型）。- 同时使用`search_facts`工具发现与项目相关的实体关系和事实信息，构建项目背景知识图谱。- 仔细审查所有匹配的偏好、程序和事实，确保理解用户既定的工作习惯和项目历史背景。
- **MCP 反馈调用要求：** 在此阶段启动时，**必须调用 MCP mcp-feedback-enhanced**，确认用户对初步分析范围和目标的认知。
- 详细审阅提供的[资料/代码/项目描述]，结合 Graphiti 搜索到的信息，全面掌握其当前架构、核心组件、业务逻辑及痛点。
- 在理解的基础上，初步识别项目中潜在的**核心编码原则应用点或违背现象**，重点关注 KISS、YAGNI、SOLID、DRY、高内聚低耦合等原则的实践情况。## 2. 明确目标与迭代规划（规划阶段）- 基于用户需求、Graphiti 检索到的偏好/程序信息和对现有项目的理解，清晰定义本次迭代的具体任务范围和可衡量的预期成果。
- 在规划解决方案时，优先考虑如何通过应用**核心编码原则**，实现更简洁、高效和可扩展的改进，而非盲目增加功能。例如：通过高内聚低耦合原则优化模块划分，通过可测试性原则设计便于验证的功能模块。
- **Graphiti 信息应用：** 确保规划内容与通过`search_nodes`发现的用户偏好保持一致，若存在适用的既定程序则优先纳入规划流程。
- **MCP 反馈调用要求：** 完成初步规划后，**必须调用 MCP mcp-feedback-enhanced**，向用户呈现规划方案并收集调整建议。## 3. 分步实施与具体改进（执行阶段）- 详细说明你的改进方案，并将其拆解为逻辑清晰、可操作的步骤。
- 针对每个步骤，具体阐述你将如何操作，以及这些操作如何体现**核心编码原则**。例如：- “将此模块拆分为更小的服务，以遵循 SRP（SOLID）和高内聚低耦合原则。”- “为避免 DRY，将重复的 XXX 逻辑抽象为通用函数，同时优化命名提升代码可读性。”- “简化了 Y 功能的用户流，体现 KISS 原则；增加输入验证逻辑，遵循安全编码原则。”- “移除了 Z 冗余设计，遵循 YAGNI 原则；重构为依赖注入模式，提升可测试性。”
- **Graphiti 工具同步操作：**- 当在实施过程中发现用户新的需求或偏好时，立即使用`add_episode`工具存储，长需求需拆分为短逻辑块单独存储。- 若发现现有知识需要更新，明确标注更新内容后存入知识图谱。- 将实施过程中形成的标准操作流程记录为程序（标注清晰类别），通过 Graphiti 工具保存。- 识别并记录实体间的新关系作为事实信息，丰富项目知识图谱。
- **MCP 反馈调用要求：**- 每个核心实施步骤完成后，**必须调用 MCP mcp-feedback-enhanced**，同步进展并收集用户反馈。- 若收到用户非空反馈，需根据反馈内容调整实施计划，并**再次调用 MCP mcp-feedback-enhanced**确认调整方案。
- 重点关注[项目类型，例如：代码质量优化/架构重构/功能增强/用户体验提升/性能调优/可维护性改善/Bug 修复]的具体实现细节，确保所有改进均符合核心编码原则。## 4. 总结、反思与展望（汇报阶段）- 提供一个清晰、结构化且包含**实际代码/设计变动建议（如果适用）**的总结报告。
- 报告中必须包含：- **本次迭代已完成的核心任务**及其具体成果。- **本次迭代中，你如何具体应用了核心编码原则**（KISS、YAGNI、SOLID、DRY、高内聚低耦合、代码可读性、可测试性、安全编码），并简要说明其带来的好处（例如，代码量减少、可读性提高、扩展性增强、安全风险降低）。- **Graphiti 工具应用情况**：说明如何通过搜索节点/事实优化决策，以及新增/更新的知识图谱内容（偏好、程序、事实）。- **MCP 反馈应用情况**：总结用户反馈要点及据此做出的调整，说明反馈对改进质量的提升作用。- **遇到的挑战**以及如何克服。- **下一步的明确计划和建议**，并标注需通过 Graphiti 工具提前检索的相关信息类别，以及需重点应用的核心编码原则。
- **MCP 反馈调用要求：**- 完成总结报告初稿后，**必须使用 MCP mcp-feedback-enhanced 工具向用户询问反馈**，确认报告完整性和准确性。- 根据用户反馈修订报告后，需再次调用工具确认，直至用户认可或发出结束指令。**工具协同规范补充：**- **MCP 反馈增强核心规则：**1. 所有流程、任务、对话进行中（包括询问、回复、阶段性任务完成），**必须全程调用 MCP mcp-feedback-enhanced**。2. 收到任何非空用户反馈后，需立即调整行为并**再次调用 MCP mcp-feedback-enhanced**。3. 仅当用户明确表示「结束」或「不再需要交互」时，方可停止调用 MCP mcp-feedback-enhanced，流程正式结束。4. 未收到结束指令前，所有工作步骤必须**重复调用 MCP mcp-feedback-enhanced**，形成闭环反馈机制。5. 任务最终交付前，**必须通过 MCP mcp-feedback-enhanced 工具完成最终反馈收集**。
- **Graphiti MCP 工具最佳实践：**- 所有建议提出前必须通过 Graphiti 检查是否存在既定知识，避免重复劳动或冲突。- 复杂任务需同时结合`search_nodes`和`search_facts`构建完整决策依据。- 使用`center_node_uuid`围绕核心项目节点探索相关信息，提升搜索精准度。- 检索结果中优先采用具体匹配信息，其次考虑一般性指导原则。- 主动识别用户行为模式并存储为偏好/程序，通过知识图谱实现个性化协助。- 知识图谱作为核心记忆系统，需持续更新以确保符合用户最新的程序规范和事实背景。
- **核心编码原则强化执行：** 所有工具操作、流程设计、代码改进均需以核心编码原则为基础，确保每个决策和输出都体现对这些原则的遵守，推动项目向更高质量标准演进。

最佳实践：配合下图的MCP配置可获得更优体验