基于Neo4j与MCP协议，为AI智能体构建动态知识图谱大脑

1. 项目概述为AI智能体构建一个动态知识大脑如果你正在使用Cursor、Claude Desktop这类AI编程助手并且对它们能记住上下文、理解项目结构的能力感到惊喜那么Graphiti MCP Server可能会让你对AI智能体的认知再上一个台阶。简单来说它不是一个普通的工具而是一个专为AI智能体设计的“外挂大脑”——一个基于Neo4j图数据库的动态知识图谱服务器。想象一下你的AI助手不再仅仅依赖当前对话的短暂记忆而是可以随时查询、更新一个结构化的、互联的知识网络这个网络里存储着你项目的所有实体、概念、依赖关系和历史决策。这就是Graphiti MCP Server的核心价值。它通过Model Context ProtocolMCP与你的AI客户端如Cursor无缝集成。MCP你可以理解为AI世界的“USB协议”它定义了一套标准让不同的工具服务器能以一种统一的方式向AI模型客户端提供额外的上下文和能力。Graphiti作为MCP服务器主要干两件事一是利用大语言模型如GPT-4的智能从非结构化的文本如你的代码注释、文档、对话记录中自动提取实体如函数名、类、技术栈、业务概念和它们之间的关系二是将这些结构化的知识存入Neo4j图数据库并提供强大的语义搜索和图遍历能力。当你的AI助手需要回答一个复杂问题时它可以通过MCP向Graphiti服务器发起查询快速从知识图谱中找到相关的实体和路径从而给出更精准、更有上下文的回答。这个项目特别适合开发者、技术团队和知识密集型工作者。对于个人开发者你可以用它来管理个人项目的技术债、梳理复杂的代码依赖。对于团队它可以作为团队知识库的核心将设计文档、会议纪要、API文档和代码本身关联起来新成员 onboarding 时AI助手能基于这个图谱给出极其精准的引导。接下来我将从设计思路、部署实操、核心功能使用到深度定制为你完整拆解这个项目。2. 核心架构与设计思路拆解2.1 为什么选择“图数据库LLMMCP”的技术栈要理解Graphiti的价值得先明白它解决的痛点。传统的AI助手在复杂项目中的局限性很明显上下文窗口有限无法持久化记忆对项目内部复杂的关联关系比如A模块调用了B服务的哪个API又依赖了C库的哪个版本缺乏结构化理解。Graphiti的解决方案是一个“铁三角”组合。Neo4j图数据库是基石。为什么是图数据库而不是传统的关系型数据库如MySQL或文档数据库如MongoDB因为知识本质上是关联的网络。一个“用户”实体通过“创建”关系连接到一个“订单”实体“订单”又通过“包含”关系连接到多个“商品”实体。用SQL的多表JOIN来查询这种多跳关系随着数据量和关联深度的增加会变得异常复杂和低效。而Neo4j的图查询语言Cypher其语法近乎于用自然语言描述关系路径例如MATCH (u:User)-[:CREATED]-(o:Order)-[:CONTAINS]-(p:Product)非常直观且在查询深度关联数据时性能上有天然优势。这对于需要频繁进行“顺藤摸瓜”式查询的知识图谱场景是再合适不过的选择。大语言模型LLM是智能提取器。光有存储结构不够我们还需要把非结构化的文本你的代码、文档、笔记变成结构化的图数据。这就是LLM大显身手的地方。Graphiti利用OpenAI的API或兼容的Azure OpenAI将文本发送给LLM通过精心设计的提示词Prompt引导模型识别文本中的实体类型如Person,Class,APIEndpoint、实体属性以及实体间的关系如CALLS,DEPENDS_ON,MENTIONS。这个过程称为“实体关系联合抽取”。LLM的强大语义理解能力使得它能够从模糊的描述中准确识别出技术概念和它们之间的逻辑联系这是基于规则或传统NLP模型很难做到的。Model Context Protocol是连接桥梁。MCP是Anthropic提出的一种开放协议旨在标准化AI应用与工具之间的通信。在Graphiti的语境下你的Cursor IDE作为MCP客户端Graphiti服务器作为MCP服务端。客户端通过MCP协议向服务器声明自己需要哪些“工具”Tools和“资源”Resources。服务器则暴露一系列能力比如“搜索知识图谱”、“添加新知识”、“推荐相关概念”。当你在Cursor里向AI提问时AI模型会判断是否需要调用Graphiti提供的工具如果需要则通过MCP协议发送请求Graphiti执行操作如查询图谱并将结果通过协议返回AI再整合结果生成最终回答给你。这一切对用户是无感的你只觉得AI突然变得特别“懂”你的项目。2.2 Graphiti MCP Server的核心工作流理解了技术栈我们来看一个典型的工作流这能帮你更好地把握后续的配置和使用。初始化与知识注入你启动Graphiti服务器和Neo4j数据库。最初图谱是空的。你可以通过几种方式注入初始知识a) 让AI助手分析你当前打开的代码文件自动提取实体和关系b) 直接上传项目文档或技术规格书c) 通过对话手动告诉AI“请记住我们的用户服务依赖于MySQL和Redis”。动态交互与学习在日常开发对话中当你提到一个概念比如“修改UserController的登录逻辑”AI助手会通过MCP调用Graphiti的搜索工具。Graphiti在图谱中查找与“UserController”、“登录”相关的节点和路径将找到的上下文比如UserController调用了AuthServiceAuthService又使用了JWT库返回给AI。AI在拥有这些精准上下文后给出的代码修改建议会避开破坏现有依赖甚至能提醒你“修改这里可能影响到下游的SessionManager”。图谱的持续演化这是一个学习型系统。当AI根据图谱上下文给出了优秀建议而你采纳了这个交互本身可以被视为一种确认。更高级的用法是你可以让AI将本次对话中有价值的新信息比如你决定弃用某个旧库总结出来并调用Graphiti的“添加知识”工具更新到图谱中。这样图谱就像项目的“集体记忆”随着项目发展而不断生长、修正。这个设计巧妙地将LLM的泛化理解能力、图数据库的结构化存储与查询能力、以及MCP的标准化互操作能力结合在一起创造了一个能够“理解”复杂项目上下文的、可进化的AI辅助系统。3. 从零开始的部署与配置实操纸上谈兵终觉浅我们直接上手把环境跑起来。项目推荐使用Docker Compose部署这是最省心、环境最一致的方式。3.1 前期准备与环境检查首先确保你的开发机满足以下条件操作系统Linux, macOS 或 Windows需安装WSL2以获得最佳体验。Docker与Docker Compose这是必须的。在终端运行docker --version和docker compose version检查是否安装。建议使用Docker Desktop它通常两者都包含。硬件资源至少4GB空闲内存8GB或以上为佳。Neo4j和LLM推理虽然推理在云端但本地服务处理需要内存都是内存消耗大户。预留2GB以上的磁盘空间。网络能够稳定访问OpenAI API或你配置的Azure OpenAI端点。如果网络环境特殊后续配置环节会讲到代理设置。OpenAI API Key这是驱动LLM提取能力的“燃料”。前往OpenAI平台创建并获取一个API Key。请妥善保管我们下一步会用到。3.2 一步一步启动你的知识图谱服务器第一步获取项目代码。打开终端克隆项目仓库并进入目录。git clone https://github.com/gifflet/graphiti-mcp-server.git cd graphiti-mcp-server这个操作会把服务器源代码、Docker配置等文件下载到本地。第二步配置关键环境变量。项目提供了一个环境变量模板文件.env.sample。我们复制它并创建自己的.env文件。cp .env.sample .env现在用你喜欢的文本编辑器如VSCode, Vim, Nano打开.env文件。你会看到类似下面的内容# Required for LLM operations OPENAI_API_KEYyour_openai_api_key_here MODEL_NAMEgpt-4.1-mini # Optional: Custom OpenAI endpoint (e.g., for proxies) # OPENAI_BASE_URLhttps://api.openai.com/v1 # Neo4j Configuration (defaults work with Docker) NEO4J_URIbolt://neo4j:7687 NEO4J_USERneo4j NEO4J_PASSWORDdemodemo你需要做以下修改将your_openai_api_key_here替换成你真实的OpenAI API Key。这是最关键的一步。MODEL_NAME可以根据需要调整。gpt-4.1-mini是性价比不错的选择。如果你有更高预算和需求可以换成gpt-4o或gpt-4-turbo以获得更强的推理能力。Neo4j的配置URI, 用户名密码在Docker Compose网络内使用默认值即可除非你有特殊需求。demodemo是默认密码在生产环境中务必修改为强密码注意.env文件包含你的敏感密钥千万不要将其提交到版本控制系统如Git。项目通常已在.gitignore中排除了.env文件但请再次确认。第三步一键启动所有服务。在项目根目录下运行以下命令docker compose up -d-d参数代表“detached”让服务在后台运行。Docker Compose会读取当前目录下的docker-compose.yml文件依次拉取Neo4j和Graphiti MCP Server的镜像如果本地没有创建容器和内部网络并启动它们。第四步验证服务状态。启动完成后运行以下命令检查容器是否正常运行docker compose ps你应该看到两个服务neo4j和graphiti-mcp的状态都是Up。如果状态异常可以查看日志排查docker compose logs -f graphiti-mcp按CtrlC可以退出日志跟随模式。3.3 关键配置项深度解析环境变量是控制服务器行为的核心。除了基础的API Key理解其他配置能让你更好地驾驭这个系统。OpenAI相关配置OPENAI_BASE_URL这是一个非常实用的配置。如果你的网络需要通过代理访问OpenAI或者你使用的是兼容OpenAI API格式的第三方模型服务如某些本地部署的模型网关可以在这里设置完整的API端点URL。例如如果你使用一个代理服务可以设置为https://your-proxy-domain.com/v1。OpenAI Python SDK会直接使用这个地址。LLM_TEMPERATURE控制LLM输出的随机性。值越低如0.0输出越确定、一致值越高如0.8输出越有创造性、不可预测。对于知识提取这种需要高准确度的任务建议保持为0.0或一个很低的值如0.1。EMBEDDER_MODEL_NAME指定用于生成文本嵌入向量的模型。嵌入向量用于语义搜索。text-embedding-3-small是当前性价比很高的选择。如果你需要更高的检索精度可以考虑text-embedding-3-large但会消耗更多tokens。服务器性能与资源限制SEMAPHORE_LIMIT这个参数至关重要它控制着向OpenAI API发起并发请求的最大数量。设置得太高可能会迅速触发OpenAI的速率限制Rate Limit导致请求失败设置得太低则无法充分利用资源在处理大量文档时速度会慢。默认值10是一个相对保守的起点。实操心得如果你在批量导入文档时频繁收到“429 Too Many Requests”错误请尝试将这个值降低到5或3。反之如果你的API配额很高且网络稳定可以适当提高到15或20以加速处理。关于Azure OpenAI的配置如果你所在的组织使用Azure OpenAI服务配置方式有所不同。你不能同时设置标准OpenAI和Azure的变量。你需要注释掉或删除OPENAI_API_KEY和MODEL_NAME转而设置以下Azure专用变量AZURE_OPENAI_ENDPOINThttps://your-resource.openai.azure.com/ AZURE_OPENAI_API_VERSION2024-02-01 AZURE_OPENAI_DEPLOYMENT_NAMEyour-gpt-4-deployment-name OPENAI_API_KEYyour_azure_openai_api_key_here # 注意这里仍然使用 OPENAI_API_KEY 这个变量名但值是你的Azure密钥。确保你的Azure部署名称与变量中的AZURE_OPENAI_DEPLOYMENT_NAME完全一致。3.4 验证安装与初步访问服务启动后可以通过几个方式验证一切正常健康检查Graphiti服务器提供了一个简单的健康检查端点。curl http://localhost:8000/health如果返回{status:healthy}或类似信息说明Graphiti服务本身运行正常。访问Neo4j浏览器在本地浏览器中打开http://localhost:7474。这是Neo4j自带的图形化管理界面。首次登录使用你在.env中设置的用户名默认neo4j和密码默认demodemo。登录后你会看到一个可以输入Cypher查询命令的界面。目前数据库是空的但能成功登录说明Neo4j服务运行正常。测试MCP SSE端点MCP服务器通常通过Server-Sent Events (SSE) 或 WebSocket 提供连接。你可以测试SSE端点是否能连接。curl -N http://localhost:8000/sse这个命令会发起一个长连接如果服务器响应你会看到一些初始化的事件流数据。按CtrlC中断即可。这证明MCP传输层工作正常。至此你的Graphiti MCP Server后端已经就绪。接下来我们要让它和你的AI助手以Cursor为例对话。4. 与AI客户端集成以Cursor IDE为例服务器跑起来了但它还是个“孤岛”。我们需要通过MCP协议让它成为Cursor AI助手的一部分。下面以Cursor IDE为例演示完整的集成流程。4.1 配置Cursor的MCP设置Cursor内置了对MCP的支持。我们需要编辑Cursor的配置文件告诉它Graphiti服务器的位置。打开Cursor的MCP设置文件。这个文件通常位于macOS/Linux:~/.cursor/mcp.jsonWindows:%USERPROFILE%\.cursor\mcp.json如果文件或目录不存在手动创建即可。编辑mcp.json文件。根据你的Graphiti运行方式选择一种配置如果你按照上述Docker方式运行Graphiti服务器在localhost:8000提供SSE服务。配置如下{ mcpServers: { Graphiti: { url: http://localhost:8000/sse } } }这种配置最简单Cursor会直接通过HTTP连接到这个SSE端点。如果你希望通过命令行直接启动Graphiti进程例如在本地开发时可以使用“stdio”传输模式配置如下{ mcpServers: { Graphiti: { command: uv, args: [ run, graphiti_mcp_server.py ], env: { OPENAI_API_KEY: sk-your-key-here, NEO4J_URI: bolt://localhost:7687 } } } }这种模式下Cursor会启动一个子进程来运行Graphiti服务器进程间通过标准输入输出通信。你需要确保uv和项目依赖已在你的Python环境中安装好。保存配置文件并完全重启Cursor IDE。MCP配置通常在Cursor启动时加载修改后必须重启才能生效。4.2 导入Graphiti专属规则增强体验为了让Cursor的AI助手更好地利用Graphiti的能力项目提供了一个规则文件graphiti_cursor_rules.mdc。这个文件包含了提示词指导AI何时以及如何调用Graphiti的工具。在Graphiti项目根目录找到graphiti_cursor_rules.mdc文件。打开Cursor IDE进入设置Settings。找到“User Rules”或“规则”设置项。将graphiti_cursor_rules.mdc文件的内容全部复制粘贴到User Rules中。保存设置。这个规则的作用是“教育”Cursor的AI当用户的问题涉及项目理解、代码关系、架构探索时你应该主动去查询Graphiti知识图谱来获取上下文。没有这个规则AI可能不会主动使用Graphiti需要你手动触发。4.3 开始你的第一次“增强对话”配置完成后打开一个已有的代码项目比如一个Python Web后端或React前端项目。在Cursor中启动一个新的Agent会话通常通过快捷键CmdK或CtrlK呼出命令面板选择“New Agent”。在聊天框中尝试问一个关于项目结构的问题。例如“这个Django项目里models.py中定义的User模型都被哪些视图views使用了”“帮我找一下所有处理用户认证authentication的代码文件。”“解释一下OrderService和PaymentService之间是怎么交互的。”如果一切配置正确你应该能在AI的回复中看到它调用了Graphiti工具的痕迹有时Cursor会在消息旁显示一个小工具图标。AI的回答会基于从知识图谱中查询到的实体关系变得更加具体和准确。实操心得首次运行的常见情况第一次使用时图谱是空的所以AI查询不到东西。你需要先“喂”一些知识进去。一个简单的方法是让AI分析当前打开的文件。你可以说“请分析当前打开的services/auth.py文件并将其中的主要实体和关系提取到知识图谱中。” AI会调用Graphiti的提取工具LLM会解析文件内容并将识别出的类、函数、依赖等存入Neo4j。多分析几个核心文件后图谱就有了内容后续的查询就会变得有意义。5. 核心功能使用与高级技巧5.1 知识注入多种方式构建你的图谱一个强大的知识图谱需要高质量的数据。Graphiti提供了几种知识注入途径对话式注入最自然的方式。直接告诉AI“请记住我们这个微服务项目包含user-service、order-service和payment-service它们通过RabbitMQ通信。” AI会理解你的话并调用工具将这些信息结构化后存入图谱。文件分析注入这是最常用、最高效的方式。将你的项目目录在Cursor中打开然后让AI助手遍历分析关键文件。针对性分析“请分析src/controllers/目录下的所有文件提取其中的控制器类和它们路由的API端点。”批量分析你可以写一个简单的脚本但通过AI更简单“你能帮我写一个简单的Python脚本吗用来遍历项目中的.py文件并调用Graphiti的提取功能” AI可能会给你一个使用os.walk和requests调用本地MCP服务器端点的脚本示例。文档导入将设计文档Markdown、PDF需提取文本、API文档如Swagger/OpenAPI JSON的内容复制粘贴给AI并指示它提取关键信息。例如将OpenAPI规范粘贴进去然后说“请从这份OpenAPI文档中提取所有的API路径paths、请求方法、参数和响应模型并存入知识图谱。”注意事项知识提取的质量高度依赖LLM的能力和你的提示清晰度。对于代码文件效果通常很好。对于非结构化的自然语言文档LLM可能会提取出一些模糊或错误的关系。最佳实践是先从核心的、结构良好的代码文件开始构建图谱主干再逐步补充文档信息。5.2 图谱查询与探索向你的“项目大脑”提问当图谱有了一定数据后你可以通过AI进行复杂的查询。关键在于学会如何“提问”。查找实体及其关联“找出所有与‘Redis’相关的组件。” AI会查询标签为Technology或Component且名称为Redis的节点并返回与之相连的其他节点如哪些服务使用了它。追溯依赖链“如果我要修改EmailService的send方法哪些地方的代码可能会受到影响” 这本质上是一个“反向依赖”查询AI会寻找所有指向EmailService.send的CALLS或DEPENDS_ON关系。理解数据流“从用户提交订单到生成物流单中间经历了哪些主要的服务和数据转换” 这需要AI在图谱中寻找一条或多条连接“订单提交”事件和“物流单生成”事件的路径。语义搜索“帮我找找项目中所有关于‘缓存失效策略’的讨论或代码。” 这利用了嵌入向量的语义搜索能力即使没有直接的“缓存失效”节点也能找到相关概念的代码注释或文档片段。高级技巧直接使用Neo4j浏览器进行探索。对于想深度挖掘数据的开发者直接访问http://localhost:7474使用Neo4j浏览器是绝佳选择。你可以运行Cypher查询例如MATCH (n:Class {name: UserController})-[r]-(m) RETURN n, r, m这个查询会可视化展示所有从UserController节点出发的关系。通过图形化界面你能直观地看到知识的网络结构这是纯文本交互无法比拟的。5.3 自定义实体与关系类型默认的实体和关系类型如Class,Function,CALLS,DEPENDS_ON可能不完全符合你的项目领域。Graphiti支持一定程度的自定义。查看项目源代码特别是与提示词prompt和LLM调用相关的部分你会发现实体和关系的类型定义。你可以修改这些定义以提取更适合你领域的知识。例如在一个电商项目中你可能想定义Product,SKU,Inventory等实体类型以及HAS_VARIANT,LOCATED_IN等关系类型。操作流程通常涉及找到项目中负责构造提取提示词的模块例如prompts.py或类似文件。修改其中定义实体和关系类型的系统提示词部分。如果你以开发模式运行服务器uv run graphiti_mcp_server.py修改会生效。如果是Docker运行则需要重新构建镜像。这是一个相对高级的功能需要对项目代码结构有一定了解。但对于垂直领域知识的构建这能极大提升图谱的精确度和实用性。6. 生产环境考量与故障排查6.1 安全与性能优化当你打算长期使用或与团队共享时需要考虑以下几点Neo4j密码务必修改默认的NEO4J_PASSWORD使用一个强密码并在.env文件中更新。API密钥管理不要在代码或配置文件中硬编码API Key。使用.env文件并确保其被.gitignore保护。在服务器环境中可以考虑使用Docker secrets或云服务商提供的密钥管理服务如AWS Secrets Manager, Azure Key Vault。网络暴露默认配置下Neo4j浏览器7474端口和Graphiti服务器8000端口都暴露在本地主机。如果部署在云服务器上务必配置防火墙如AWS安全组、Azure NSG或使用反向代理如Nginx来限制访问源IP避免公网直接暴露。强烈建议为Neo4j浏览器设置密码并考虑将Graphiti服务器置于需要身份验证的反向代理之后。数据持久化查看docker-compose.yml确认Neo4j的数据卷volume配置是否已经映射到宿主机。默认配置通常包含一个名为neo4j_data的卷确保你的图谱数据在容器重启后不会丢失。资源限制在docker-compose.yml中可以为neo4j和graphiti-mcp服务添加资源限制防止单个服务耗尽主机资源。services: neo4j: # ... 其他配置 deploy: resources: limits: memory: 2G reservations: memory: 1G graphiti-mcp: # ... 其他配置 deploy: resources: limits: memory: 1G reservations: memory: 512M6.2 常见问题与解决方案实录在实际部署和使用中你可能会遇到以下问题问题一Docker Compose启动失败提示端口被占用。表现Error starting userland proxy: listen tcp4 0.0.0.0:7474: bind: address already in use原因本地机器的7474Neo4j浏览器、7687Neo4j Bolt或8000Graphiti端口已被其他程序占用。解决使用lsof -i :7474macOS/Linux或netstat -ano | findstr :7474Windows查找占用端口的进程。停止该进程或修改docker-compose.yml中服务的端口映射例如将7474:7474改为7475:7474然后通过localhost:7475访问。问题二Graphiti服务日志显示OpenAI API连接错误。表现日志中大量出现APIConnectionError或RateLimitError。原因OPENAI_API_KEY未设置或错误。网络问题无法访问api.openai.com。请求速率超过限制Rate Limit。解决检查.env文件中的OPENAI_API_KEY是否正确确保没有多余空格。尝试在终端执行curl https://api.openai.com/v1/models需在请求头带上API Key测试网络连通性。如果失败可能需要配置网络代理并通过设置OPENAI_BASE_URL指向代理地址。如果确定是速率限制请降低SEMAPHORE_LIMIT环境变量的值例如从10降到3并考虑在OpenAI平台查看你的用量和限制。问题三Cursor AI无法连接Graphiti服务器或提示“MCP server error”。表现Cursor中AI助手没有调用Graphiti的迹象或在调用时报错。原因Cursor的mcp.json配置文件路径错误或格式不对。Graphiti服务器没有正常运行。Cursor未重启配置未生效。解决确认mcp.json文件路径正确且JSON格式无误可以使用在线JSON校验工具。运行docker compose ps和docker compose logs graphiti-mcp确认Graphiti服务状态正常无报错。务必完全关闭Cursor IDE并重新打开。在Cursor中尝试打开开发者工具Developer Tools通常可在帮助菜单找到查看控制台Console是否有关于MCP连接的报错信息。问题四知识提取结果不准确或遗漏。表现AI提取的实体关系与代码实际不符或漏掉了重要部分。原因使用的LLM模型如gpt-4.1-mini能力有限对复杂代码理解不足。提示词Prompt对于特定代码范式如函数式编程、装饰器大量使用可能不够优化。文件太大超出模型上下文窗口。解决尝试升级到更强的模型如gpt-4o在.env中修改MODEL_NAME。考虑将大文件分块处理。可以指示AI“请先分析这个文件的前200行提取主要类结构再分析后续部分。”提供更明确的指令。例如“在提取时请特别关注被api.route装饰的函数它们都是API端点。”问题五Neo4j数据库数据混乱或想清空重来。表现图谱中积累了测试数据或错误数据想重置。解决最彻底的方式是删除Neo4j的数据卷并重启。docker compose down -v # -v 参数会删除所有关联的卷 docker compose up -d警告这将永久删除所有图谱数据请谨慎操作。 2. 更精细的方式是进入Neo4j浏览器 (http://localhost:7474)执行Cypher命令删除所有节点和关系MATCH (n) DETACH DELETE n这个项目将前沿的LLM、图数据库和智能体协议结合为开发者提供了一个可编程、可扩展的“项目记忆体”。从我个人的使用体验来看初期投入一些时间构建图谱是值得的尤其是在参与大型或历史悠久的项目时它能显著降低认知负荷让AI助手从一个“临时工”变成真正理解项目脉络的“资深协作者”。你可以从一个小型个人项目开始尝试逐步摸索出最适合自己工作流的图谱构建和查询方式。