企业官网建设流程全解析

MCP Toolbox 集成 FalkorDB：预构建配置与图数据库 Cypher 工具实战指南

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

导读

本文围绕 MCP Toolbox 仓库中 FalkorDB 集成模块的预构建配置展开，讲解如何通过--prebuilt falkordb一键加载面向图数据库的 MCP Server：包括环境变量驱动的连接配置、execute_cypher/get_schema/list_graphs三个核心工具的含义与底层实现，以及从本地 Docker 启动 FalkorDB 到接入 MCP Inspector 的完整实操链路。读完本文，你将掌握在 MCP Toolbox 中接入 FalkorDB 图数据库的完整配置方法与运行原理，并能在自己的 Agent 工作流中直接使用。

FalkorDB 预构建配置一览

FalkorDB 是一个低延迟、开源的图数据库，通过 Redis 协议支持 openCypher 查询语言；单个实例可以承载多个相互独立的图，其原生向量索引与全文索引使其成为 GenAI 知识图谱后端的常见选择（见 FalkorDB 源文档）。

在 MCP Toolbox 中，FalkorDB 被预置为一个开箱即用的 prebuilt 配置。关联文档（docs/en/integrations/falkordb/prebuilt-configs/falkordb.md）给出了该配置的核心事实：

• --prebuilt取值：falkordb
• 环境变量：FALKORDB_HOST、FALKORDB_PORT（默认6379）、FALKORDB_GRAPH、FALKORDB_USERNAME（可选）、FALKORDB_PASSWORD（可选）
• 权限要求：执行 Cypher 查询需要数据库级（database-level）权限
• 工具清单：execute_cypher、get_schema、list_graphs

使用方式非常直接：启动 MCP Toolbox 服务器时传入--prebuilt falkordb，并在环境中注入上述变量即可。例如：

export FALKORDB_HOST=127.0.0.1 export FALKORDB_PORT=6379 export FALKORDB_GRAPH=my_graph ./toolbox --prebuilt falkordb

预构建配置在仓库中的真实形态

上述 prebuilt 配置并非硬编码在程序里，而是由仓库中的声明式 YAML 模板驱动的。查看 internal/prebuiltconfigs/tools/falkordb.yaml 可以看到它的真实结构：一个kind: source的源定义加上三个kind: tool的工具定义，最后以一个kind: toolset（falkordb_database_tools）聚合所有工具。

该模板的关键点在于环境变量替换语法：${FALKORDB_HOST}、${FALKORDB_PORT:6379}、${FALKORDB_USERNAME:}、${FALKORDB_PASSWORD:}、${FALKORDB_GRAPH}。其中${FALKORDB_PORT:6379}表示变量未设置时使用默认值6379，这与 prebuilt 文档中“端口默认 6379”的描述完全一致；而username/password的默认值为空字符串，对应“可选”的说明。graph字段在模板中没有默认值，因此FALKORDB_GRAPH属于必填环境变量——MCP Toolbox 建议通过${ENV_NAME}形式引用环境变量而非在配置中硬编码敏感信息。

深入理解三个内置工具

预构建配置聚合了三个与图数据库直接相关的工具（见 falkordb.yaml）：

它们统一挂载在同一个falkordb-source源上，并聚合为falkordb_database_tools工具集。下面分别展开其能力与实现细节。

execute_cypher：执行任意 Cypher 查询

falkordb-execute-cypher让 Agent 将任意 Cypher 语句提交到源所配置的图上执行。其实现位于 internal/tools/falkordb/falkordbexecutecypher/falkordbexecutecypher.go，底层通过源对象上的RunQuery方法完成（见 internal/sources/falkordb/falkordb.go）。

该工具暴露三个运行时参数：

• cypher（必填）：要执行的 Cypher 语句，空字符串会被拒绝；
• dry_run（可选，默认false）：置为true时不会真正执行查询，而是通过GRAPH.EXPLAIN返回查询的执行计划；
• graph（仅当allowGraphOverride: true时暴露）：允许 Agent 绕过源的默认图，直接指定实例上的其他图。

readOnly是配置阶段的关键开关（默认false）。当其置为true时，查询会通过 FalkorDB 的GRAPH.RO_QUERY命令派发，由数据库服务端本身拒绝写操作，而不是靠客户端做查询检查——这一语义在源码RunQuery的注释中明确说明（falkordb.go），也体现在工具实现中对ReadOnly标志的透传（falkordbexecutecypher.go）。

同样值得注意的还有查询超时：源配置中的queryTimeoutMs会通过falkordb.NewQueryOptions().SetTimeout()传给每次查询，未设置时无超时限制（falkordb.go）。

get_schema：提取图模式

falkordb-schema工具提取所配置图的完整 schema 描述，包括：节点标签与关系类型及其观测到的属性形状（每个标签/类型最多采样sampleSize个实体，默认 100）、索引（含向量索引与全文索引）、约束以及图统计信息。

其输出是一个结构化 JSON（见 falkordb-schema 工具文档）：

{ "graphInfo": {"name": "my_graph", "nodeCount": 2, "edgeCount": 1}, "nodeLabels": [ {"name": "Person", "count": 1, "properties": [{"name": "name", "types": ["STRING"]}]} ], "relationships": [ {"type": "ACTED_IN", "count": 1, "startNode": "Person", "endNode": "Movie", "properties": []} ], "indexes": [], "constraints": [], "statistics": {"totalNodes": 2, "totalRelationships": 1} }

这个工具对 LLM Agent 特别有价值：在执行复杂查询前先获取图模式，能显著提升生成 Cypher 的准确性。其实现位于 internal/tools/falkordb/falkordbschema/，辅助逻辑与类型定义分别沉淀在helpers/与types/子包中。

list_graphs：发现实例上的所有图

falkordb-list-graphs通过GRAPH.LIST命令列出源实例上存储的所有图名称（见 falkordb-list-graphs 工具文档），输出格式为：

{"graphs": ["my_graph", "another_graph"]}

由于单个 FalkorDB 实例可以承载多个独立图，该工具通常与配置了allowGraphOverride: true的falkordb-execute-cypher配合使用：先列举图，再跨图执行查询，形成一个完整的“发现—执行”闭环。

一个补充工具：falkordb-cypher（预定义语句）

除上述三个工具外，仓库还提供了falkordb-cypher类型的工具（见 falkordb-cypher 工具文档），用于执行预定义的 Cypher 语句。它与execute_cypher的区别在于：语句在配置文件中固定下来，并且以参数化查询方式执行（如$name、$year），从而防止注入。需要注意：参数可以替换任意表达式，但不能用于替换标识符、标签、关系类型等查询结构部分。

kind: tool name: search_movies_by_actor type: falkordb-cypher source: my-falkordb-movies-instance statement: | MATCH (m:Movie)<-[:ACTED_IN]-(p:Person) WHERE p.name = $name AND m.year > $year RETURN m.title, m.year LIMIT 10 description: | Use this tool to get a list of movies for a specific actor and a given minimum release year. parameters: - name: name type: string description: Full name of the actor. - name: year type: integer description: Minimum release year.

该工具不在 prebuilt 的falkordb_database_tools工具集内，但适合在自定义配置中作为“受控只读查询”的补充。

源配置：连接 FalkorDB 实例的完整参数

FalkorDB 源（source）负责建立与实例的连接，并指定工具的默认图。关联文档要求数据库级权限才能执行 Cypher，而源配置则决定了如何获得该权限。以下为源支持的完整字段（见 FalkorDB 源文档 及源码 falkordb.go）：

认证、TLS 与连接建立

无访问控制的 FalkorDB 实例（例如本地docker run -p 6379:6379 falkordb/falkordb）可以不填凭据直接使用；而开启了认证的实例（如 FalkorDB Cloud）则需要提供username、password，并对加密端点启用tls。

从源码看，连接建立经历了一个完整的校验流程（falkordb.go）：

1. TLS 配置一致性校验：validateTLS会拒绝tls.insecureSkipVerify: true但tls.enabled: false的矛盾配置，避免“跳过校验”被静默忽略；
2. 客户端初始化：通过falkordb.FalkorDBNew创建客户端，Addr由net.JoinHostPort(host, port)组合；若启用 TLS，则配置tls.Config，且最低版本强制为 TLS 1.2；
3. 连通性探活：连接建立后立即执行Ping，失败则关闭连接并报错；
4. 安全提示：若启用了insecureSkipVerify，初始化阶段会输出警告日志，明确提示该配置暴露中间人攻击风险，不建议在生产环境使用。

完整源配置示例

kind: source name: my-falkordb-source type: falkordb host: 127.0.0.1 port: "6379" username: ${FALKORDB_USERNAME} password: ${FALKORDB_PASSWORD} graph: my_graph

查询结果的序列化行为

RunQuery的结果会被转换为 JSON 兼容结构后返回（falkordb.go）：

• 节点（Node）序列化为{id, labels, properties}；
• 关系（Edge）序列化为{id, type, sourceId, destinationId, properties}；
• 路径（Path）序列化为{nodes, edges}两个数组；
• 没有RETURN子句的写查询（如CREATE）若产生变更，则返回stats字段，包含nodesCreated、relationshipsCreated、propertiesSet、labelsAdded、executionTimeMs等变更计数，让写操作也能获得有意义的反馈。

这些细节意味着 Agent 拿到的是结构清晰、可直接用于推理的 JSON，而非原始驱动的内部类型。

从零开始：Docker 启动 FalkorDB 并接入 MCP Inspector

仓库提供了完整的快速上手样例（mcp_quickstart.md），以下按步骤复现。

第一步：启动 FalkorDB 并灌入示例数据

用 Docker 一行启动本地实例：

docker run -d --name falkordb -p 6379:6379 falkordb/falkordb

随后用redis-cli（或暴露 3000 端口后用 FalkorDB 浏览器）创建一个小型电影知识图谱：

docker exec falkordb redis-cli GRAPH.QUERY movies "CREATE (hanks:Person {name: 'Tom Hanks'}), (ryan:Person {name: 'Meg Ryan'}), (sleepless:Movie {title: 'Sleepless in Seattle', year: 1993}), (gump:Movie {title: 'Forrest Gump', year: 1994}), (hanks)-[:ACTED_IN]->(sleepless), (hanks)-[:ACTED_IN]->(gump), (ryan)-[:ACTED_IN]->(sleepless)"

第二步：编写 tools.yaml 并启动 Toolbox

下载对应操作系统与 CPU 架构的 Toolbox 二进制并赋予执行权限后，编写tools.yaml：

kind: source name: falkordb-movies type: falkordb host: 127.0.0.1 port: "6379" graph: movies --- kind: tool name: search_movies_by_actor type: falkordb-cypher source: falkordb-movies statement: | MATCH (m:Movie)<-[:ACTED_IN]-(p:Person) WHERE p.name = $name RETURN m.title, m.year LIMIT 10 description: Use this tool to list the movies a given actor acted in. parameters: - name: name type: string description: Full name of the actor. --- kind: tool name: execute_cypher type: falkordb-execute-cypher source: falkordb-movies description: Use this tool to execute a Cypher query against the movie graph. --- kind: tool name: get_schema type: falkordb-schema source: falkordb-movies description: Use this tool to get the schema of the movie graph.

启动服务器：

./toolbox --tools-file "tools.yaml"

第三步：连接 MCP Inspector 验证

npx @modelcontextprotocol/inspector

按提示安装 Inspector 包后，浏览器打开http://127.0.0.1:6274，选择Streamable HTTP传输方式，URL 填http://127.0.0.1:5000/mcp，点击Connect。随后点击List Tools即可看到search_movies_by_actor、execute_cypher、get_schema三个工具——可以试问“Tom Hanks 演过哪些电影”、执行一条临时 Cypher，或拉取图 schema。

进阶配置：自定义 Cypher 工具的参数化与安全

如果需要更精细的工具面，可以在自定义配置中组合使用各类参数。例如给falkordb-execute-cypher设置readOnly: true，让服务端强制拒绝写操作：

kind: tool name: execute_cypher type: falkordb-execute-cypher source: my-falkordb-instance description: Use this tool to execute a Cypher query against the graph. readOnly: true

需要 Agent 访问实例上其他图时，开启allowGraphOverride: true，此时工具会额外暴露graph参数；若实例上存在不应暴露的图，则保持默认关闭（见 falkordb-execute-cypher 工具文档）。从源码看，readOnly与allowGraphOverride分别对应工具配置中的ReadOnly与AllowGraphOverride字段，并直接决定默认注解（只读/破坏性）与参数清单（falkordbexecutecypher.go）。

需要固定查询时，则优先使用falkordb-cypher的参数化语句，避免 Agent 拼接任意查询带来的注入风险。

总结

MCP Toolbox 通过--prebuilt falkordb为 FalkorDB 提供了零成本接入的预构建配置：环境变量决定连接方式，execute_cypher/get_schema/list_graphs三个工具覆盖了图数据库“查询—理解—发现”的核心诉求。配合源配置中的认证、TLS、查询超时等细节（source.md），以及readOnly、allowGraphOverride、参数化语句等安全控制手段，开发者可以在数分钟内把一个可用的图数据库 MCP 工具面接入自己的 Agent 工作流。

如需继续深入，可查阅仓库中的以下资源：

• 预构建配置模板：internal/prebuiltconfigs/tools/falkordb.yaml
• 源实现：internal/sources/falkordb/falkordb.go
• 工具实现：internal/tools/falkordb/falkordbexecutecypher/falkordbexecutecypher.go、internal/tools/falkordb/falkordbschema/
• 工具文档：falkordb-execute-cypher、falkordb-schema、falkordb-list-graphs、falkordb-cypher
• 快速上手：docs/en/integrations/falkordb/samples/mcp_quickstart.md

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox