OpenClaw + MCP + Neo4j 实战：为 AI 智能体接入 YouTube GraphRAG 知识库
- Xuebin Wei
- 3天前
- 讀畢需時 8 分鐘
在之前的 LBSocial 教程中，我们已经成功搭建了底层的数据提取管道：使用 n8n 工作流自动收集 YouTube 视频元数据，利用 Gemini 嵌入模型 (embeddings) 将视频内容转化为数学向量，并将其存储在 Neo4j 图数据库中，从而构建起一个强大的视频知识图谱。
本期教程，我们将实现一个终极里程碑——通过自定义的 MCP (Model Context Protocol) 服务器，将这个现有的知识图谱与我们的 OpenClaw AI 智能体连接起来。这一实现赋予了我们的 AI 智能体无缝查询图数据库、解析复杂关系、执行语义向量检索的能力，并能直接通过 Telegram 为学生推送量身定制的结构化学习路径。
您可以通过下方视频观看完整的分步操作，并查看最终的实机演示：
1. 系统架构与 MCP 的作用
在深入代码部署之前，了解各个组件如何在我们的 GraphRAG 生态系统中交互是至关重要的。整个工作流运行在一个单独的谷歌云虚拟机 (Google Cloud VM) 上，该虚拟机同时托管了 OpenClaw、n8n 以及我们的自定义 MCP 服务器应用。
如上方系统架构图所示，当用户在 Telegram 上提问或请求学习路径时，请求会进入 OpenClaw 的运行环境。OpenClaw 充当核心的推理引擎 (Reasoning Engine) 和 MCP 客户端，负责判断哪个工具最符合用户的意图。一旦选定，它就会向下方向我们注册好的 lbsocial-youtube-graphrag stdio MCP 服务器发送一个 MCP 工具调用指令。
为了帮助您完全可视化这个底层的转换过程，我们在下方构建了一个交互式模拟器。您可以点击“Step Forward (下一步)”，直观地看到自然语言请求是如何转化为 JSON-RPC 工具调用、编译成实时的 Neo4j Cypher 查询，并最终解析为对学生友好的回答的。
这个自定义 MCP 服务器扮演着智能翻译层的角色。它将来自 AI 智能体的 JSON-RPC 工具调用，转化为经过优化的 Cypher 图数据库查询或向量检索请求。例如，一个搜索指令会触发对 Gemini Embedding API 的请求，生成一个代表用户问题的 768 维向量。随后，该向量将通过向量索引搜索推送到 Neo4j，并辅以传统的 Cypher 图遍历 (Graph Traversal) 来收集相关的频道 (Channel) 和主题 (Topic) 上下文。检索到的结构化记录会返回给 MCP 服务器，打包成格式化的 ToolResult 交还给 OpenClaw，最后在 Telegram 中渲染为通俗易懂的自然语言回复。
需要强调的是，stdio MCP 服务器并不是一个持续监听 HTTP 端口的常驻 Web API 服务器。相反，它是一个高度便携的 Python 工具集，由 OpenClaw 网关通过标准输入/输出流 (stdio) 按需启动和管理。
2. 前提条件与代码仓库隔离
要继续进行部署，请使用 VS Code Remote-SSH 连接到您的谷歌云虚拟机 (Google Cloud VM)。我们将利用包含所有自定义工作流和 MCP 配置的专属仓库，以保持环境的干净整洁。
首先，克隆 LBSocial 的官方仓库；如果您之前已经克隆过，请拉取最新的更改：
cd /home/info
# If cloning for the first time
git clone https://github.com/lbsocial/openclaw-n8n-neo4j-workflows.git
# If updating an existing repository
cd /home/info/openclaw-n8n-neo4j-workflows
git pull更新完成后，进入专门为我们的 YouTube GraphRAG 设置构建的自定义 MCP 文件夹：
cd /home/info/openclaw-n8n-neo4j-workflows/mcp/youtube-graphrag在此文件夹中，您将找到核心的项目文件，包括 server.py（定义了我们专属的工具菜单）、配置模板以及测试脚本。
3. 使用 UV 进行 Python 环境管理
为了确保可复现性和干净的依赖隔离，我们使用 uv，这是一个速度极快的 Python 包安装程序和工作流管理器。
检查您的云端机器上是否已安装 uv：
uv --version
which uv如果缺少 uv，请运行独立的安装脚本并刷新您的终端配置：
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc现在，同步您的虚拟环境，并安装 pyproject.toml 和 uv.lock 中指定的所有必要依赖项：
uv --directory /home/info/openclaw-n8n-neo4j-workflows/mcp/youtube-graphrag sync这将建立一个隔离的 .venv 文件夹，其中包含服务器运行所需的 FastMCP 框架、Neo4j 驱动程序和 Google GenAI 包。
4. 安全环境配置
我们的自定义 MCP 服务器需要访问 Neo4j AuraDB 和 Gemini API 的凭证。打开 VS Code 的文件资源管理器，定位到项目文件夹，并根据提供的模板创建一个用于生产环境的 .env 文件：
# Rename the example template to activate it
cp .env.example .env在 VS Code 编辑器中打开新创建的 .env 文件并配置您的密钥。确保删掉任何未使用的配置（例如 OpenAI 设置），因为我们在本系列教程中严格统一使用 Gemini：
NEO4J_URI=neo4j+s://xxxxxx.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_secure_neo4j_password
GEMINI_API_KEY=your_gemini_api_key
YOUTUBE_VIDEO_VECTOR_INDEX=video_embeddings
YOUTUBE_VIDEO_LABEL=Video
YOUTUBE_CHANNEL_LABEL=Channel
YOUTUBE_TOPIC_LABEL=Topic
YOUTUBE_CHANNEL_TO_VIDEO_REL=PUBLISHED
YOUTUBE_VIDEO_TO_TOPIC_REL=HAS_TOPIC
YOUTUBE_VIDEO_EMBEDDING_PROPERTY=embedding
YOUTUBE_VIDEO_ID_PROPERTY=video_id
YOUTUBE_VIDEO_TITLE_PROPERTY=title
YOUTUBE_VIDEO_URL_PROPERTY=url
YOUTUBE_VIDEO_DOCUMENT_TEXT_PROPERTY=document_text
YOUTUBE_VIDEO_PUBLISHED_AT_PROPERTY=published_at
YOUTUBE_CHANNEL_TITLE_PROPERTY=channel_title
YOUTUBE_TOPIC_NAME_PROPERTY=name
NEO4J_SCHEMA_SAMPLE_SIZE=100
为了锁定凭证并保护敏感的 API 密钥，请直接通过终端强制设置严格的读/写权限：
chmod 600 /home/info/openclaw-n8n-neo4j-workflows/mcp/youtube-graphrag/.env
提示：请始终将密钥存放在本地的 .env 文件中，而不是将它们作为明文的内联参数写进 OpenClaw 配置注册表中。这样可以防止您的密钥在运行管理 CLI 检查命令时被意外泄露。
5. 初始化 Neo4j 向量索引
虽然我们之前的 n8n 数据提取管道负责了将结构化的视频节点、元数据以及原始的 Video.embedding 属性写入 AuraDB 的工作，但它并不会自动构建数据库级别的索引。如果没有处于活动状态的索引，智能体在尝试执行语义搜索时将会抛出模式异常错误，提示 video_embeddings 不存在。
登录到您的 Neo4j Browser 控制台，并执行以下 Cypher 查询，以在视频节点的嵌入向量上建立余弦相似度 (cosine similarity) 向量索引：
CREATE VECTOR INDEX video_embeddings IF NOT EXISTS
FOR (v:Video)
ON (v.embedding)
OPTIONS {
indexConfig: {
`vector.dimensions`: 768,
`vector.similarity_function`: 'cosine'
}
};验证该索引是否已成功构建，并从数据填充状态 (POPULATING) 切换为运行状态 (ONLINE)：
SHOW INDEXES
YIELD name, type, state, labelsOrTypes, properties
WHERE name = 'video_embeddings';请确保返回的配置表明这是一个 VECTOR (向量) 类型，目标指向 ["Video"] 标签和 ["embedding"] 属性，并且其状态为 ONLINE。
6. 通过交互式菜单进行本地冒烟测试 (Local Smoke Test)
在将 OpenClaw 引入工作流之前，请先验证自定义 MCP 服务器是否能够成功进行身份验证并从您的后端拉取记录。我们不运行单一的自动查询，而是使用交互式工具菜单逐步测试各个 MCP 功能，这与视频教程中的演示完全一致。
通过终端运行本地工具菜单脚本：
uv --directory /home/info/openclaw-n8n-neo4j-workflows/mcp/youtube-graphrag run python local_tool_menu.py
这将以 stdio 模式启动 MCP 服务器，并显示一个包含我们 8 个预定义 GraphRAG 工具的交互式终端菜单。让我们执行一个快速的验证流程，以确保数据管道的可靠性：
输入 1 (get_neo4j_schema_and_indexes)： 这将确认您的数据库连接。它应该成功返回您的节点标签（Video、Channel、Topic）和关系，并确认向量嵌入索引处于活动状态。
输入 2 (search_youtube_videos)： 测试 Gemini 嵌入 API 和 Neo4j 向量搜索。出现提示时，输入类似于 "n8n" 的查询并请求 2 条结果。服务器将生成一个嵌入向量、查询图数据库，并返回匹配的视频标题（例如“Deploying n8n on Google Cloud via Docker”）及其描述和 URL。
输入 4 (get_recent_youtube_videos)： 请求 1 个最新视频，以确保服务器能够针对最新摄取的元数据执行标准的 Cypher 图遍历。
在验证返回的视频记录后，输入 quit 退出菜单。在此处成功通过验证，即可保证在我们把工具控制权移交给 OpenClaw 智能体之前，所有底层的凭证、Neo4j 连接和 Gemini API 都处于完美运行状态。
7. 将自定义 MCP 服务器注册到 OpenClaw
既然服务器已经在本地正常工作，现在将其作为官方的 stdio 工具集注册到 OpenClaw 注册表中。建议提供 uv 可执行文件的绝对路径，以防止在运行时执行期间发生环境变量 PATH 解析冲突：
openclaw mcp set lbsocial-youtube-graphrag '{
"command": "/home/info/.local/bin/uv",
"args": ["run", "python", "server.py"],
"cwd": "/home/info/openclaw-n8n-neo4j-workflows/mcp/youtube-graphrag"
}'
通过检查全局 OpenClaw 配置文件来验证注册是否已被正确记录：
openclaw mcp list
openclaw mcp show lbsocial-youtube-graphrag --json
8. 通过 Telegram 进行实战测试
集成完成后，切换到 Telegram 与您的 AI 助手机器人进行对话。我们可以明确指令 OpenClaw 利用新注册的服务器进行验证测试。
数据库模式审计 (Database Schema Audit)：为了验证完整的结构可见性，发送：
Use the lbsocial-youtube-graphrag MCP server to inspect the Neo4j schema and available indexes. 智能体将返回一个完整的布局，详细说明 Video、Channel 和 Topic 的节点结构，以及您的向量搜索系统所处的 ONLINE 状态。
9. 部署 OpenClaw Skill 实现工具自动路由
在日常对话中强迫用户显式输入 MCP 服务器的名称，会造成不自然的用户体验。为了简化路由，在 Telegram 中输入 skill creator 来激活 skill-creator 工具。粘贴以下结构化的 Markdown 提示词模板，以构建自动化的工作区路由引擎：
# LBSocial YouTube GraphRAG Assistant
## Purpose
Use this skill when the user asks about LBSocial YouTube tutorials, OpenClaw tutorials, n8n workflows, Neo4j graph databases, Gemini embeddings, MCP servers, GraphRAG, AI agents, or learning paths based on LBSocial video content.
## MCP Server
Use the `lbsocial-youtube-graphrag` MCP server when answering these questions.
## Tool Selection
- Use `search_youtube_videos` when the user asks for relevant videos, tutorials, examples, or resources.
- Use `recommend_learning_path` when the user asks how to learn a topic step by step.
- Use `get_related_videos` when the user starts from a known video and asks what to watch next.
- Use `get_video_context` when the user asks about one specific video or title phrase.
- Use `get_neo4j_schema_and_indexes` for debugging graph schema or vector indexes.
- Use `run_readonly_cypher` only for safe analytical questions, such as counts by topic. Do not use for write or admin operations.
## Response Formatting
Do not expose raw JSON. Format video search results as a clean list containing Title, Topic, Short Explanation, and Watch URL. Format learning paths as step-by-step progressions. Always include clean YouTube URLs to allow Telegram to generate automatic previews.
保存后，OpenClaw 会将此指令配置文件编译到您的本地工作区文件夹中： /home/info/.openclaw/workspace/skills/lbsocial-youtube-graphrag/SKILL.md
现在，通过询问一个标准的自然语言查询（不提及底层工具）来测试路由：
I want to learn OpenClaw and also n8n. Okay, recommend some videos.OpenClaw 将自动激活该 Skill，选择正确的工具，查询您的 Neo4j GraphRAG 索引，并输出一个包含清晰的分步说明和干净的视频 URL 的高逻辑性学习课程。
总结
这个分步教程涵盖了配置 Gemini API 凭证、使用交互式菜单在本地测试服务器，以及将 MCP 服务器注册到 OpenClaw。探索如何使用 Skill Creator，以便您的 AI 智能体能够利用您自己的 YouTube 视频内容，直接在 Telegram 中生成结构化的学习路径并回答概念性问题。
源码与资源：
请注意，下方链接的 GitHub 仓库专门包含了为本期节目构建的自定义 MCP 服务器 Python 代码 (mcp/youtube-graphrag)。
留言