MCP Toolbox for Databases 集成指南：以 ArcadeDB 多模型数据库作为数据源（Source）接入 MCP-创锋一号

MCP Toolbox for Databases 集成指南：以 ArcadeDB 多模型数据库作为数据源（Source）接入 MCP

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

本篇技术指南聚焦于开源项目 MCP Toolbox for Databases 中的 ArcadeDB 数据源（Source）集成：从 ArcadeDB 多模型数据库与 Bolt 协议的基本概念、前置的用户与连接要求，到完整的sourceYAML 配置示例、全部配置参数参考，再到源码级的双协议通道（Bolt/Cypher 与 HTTP/SQL）实现原理。读完本文，你将能够在自己的 MCP Toolbox 配置中正确声明一个 ArcadeDB 数据源，并通过arcadedb-execute-cypher与arcadedb-execute-sql两个工具让 LLM 以人机协作的方式查询图数据与文档数据。

1. ArcadeDB 数据源是什么

ArcadeDB 是一款多模型数据库，在同一个引擎中同时支持图（Cypher）、文档（SQL）、键值（Key-Value）与时间序列（Time-Series）等多种数据模型，并对外暴露一个与 Neo4j 驱动兼容的 Bolt 协议端点。这意味着既有的 Neo4j 生态工具与客户端连接方式，可以被直接复用到 ArcadeDB 上。

在 MCP Toolbox for Databases 中，数据源（Source）是连接目标数据库的连接器抽象。通过 source.md 定义的arcadedb类型 Source，MCP Toolbox 将：

通过Bolt 协议（默认bolt://localhost:7687）执行 Cypher 图查询；
通过ArcadeDB HTTP API（默认http://host:2480）执行 SQL 文档/多模型查询；
将上述能力包装成 MCP 工具，供 LLM Agent 在开发辅助（human-in-the-loop）场景下调用。

从源码结构看，该集成由两部分组成：数据源实现 internal/sources/arcadedb/arcadedb.go 与两个工具实现 arcadedbexecutecypher、arcadedbexecutesql。

2. 支持的 Tools 概览

关联文档通过{{< list-tools >}}占位符自动列举该 Source 关联的工具。当前仓库中，ArcadeDB Source 配套两个工具，其说明文档分别位于：

工具类型	用途	文档
`arcadedb-execute-cypher`	通过 Bolt 协议执行任意 Cypher 查询，支持`readOnly`拒绝写语句、`dry_run`只校验不执行	arcadedb-execute-cypher.md
`arcadedb-execute-sql`	通过 HTTP API 执行 ArcadeDB SQL 语句，支持文档与图数据的混合查询	arcadedb-execute-sql.md

两个工具的官方文档均注明：这些工具面向**开发者助手 + 人机协作（human-in-the-loop）**的工作流设计，不应直接用于生产环境的无人值守 Agent。

3. 前置条件：数据库用户

该 Source 使用标准认证（standard authentication）。

在使用前，需要在 ArcadeDB 中创建一个能够通过 Bolt 协议连接的用户，或者直接使用root用户。该用户凭据将被填入 Source 配置的user与password字段，并在两类通道中复用：

建立 Bolt 驱动时使用neo4j.BasicAuth(user, password, "")（见 arcadedb.go）；
调用 HTTP API 时通过 HTTP Basic Auth 携带同样的用户与密码（见 arcadedb.go）。

也就是说，user/password同时是 Bolt 与 HTTP API 两个通道的认证凭据，请确保该用户在 ArcadeDB 中具备相应的读写权限。

4. 完整配置示例

关联文档给出了一个最小可用示例。在仓库根目录下的 MCP Toolbox 配置文件中（例如 server.json 引用的 YAML 配置），声明如下 Source：

kind: source name: my-arcadedb-source type: arcadedb uri: bolt://localhost:7687 user: root password: ${PASSWORD} database: "mydb"

4.1 使用环境变量替换敏感信息

官方文档特别提示：请使用${ENV_NAME}格式的环境变量替换，而不是把密钥硬编码进配置文件。上面的password: ${PASSWORD}即会在运行时从环境变量PASSWORD中读取真实密码，避免密钥泄露到版本库中。同一模式也适用于user等其它敏感字段。

4.2 带 HTTP 覆盖项的完整示例

当 ArcadeDB HTTP API 与 Bolt 端点不在同一主机/端口，或需要强制使用 HTTPS 时，可补充三个可选字段。该示例同样得到单元测试的覆盖（见 arcadedb_test.go）：

kind: source name: my-arcadedb-source type: arcadedb uri: bolt://my-host:7687 database: my_db user: my_user password: ${PASSWORD} httpUri: https://my-http-host:2481 httpScheme: https httpPort: 2481

5. 参数参考表（含源码佐证）

关联文档的 Reference 表如下，字段与 arcadedb.go 中Config结构体的 YAML 标签一一对应：

field	type	required	description
type	string	true	必须为`"arcadedb"`。
uri	string	true	Bolt URI（例如`"bolt://localhost:7687"`）。
user	string	true	ArcadeDB 用户（例如`"root"`）。
password	string	true	ArcadeDB 用户的密码。
database	string	true	要连接的数据库名称。
httpUri	string	false	可选，覆盖 ArcadeDB HTTP API 的基础 URL（例如`"http://localhost:2480"`）。
httpScheme	string	false	可选，覆盖 ArcadeDB HTTP API 的 scheme，默认`"http"`。
httpPort	integer	false	可选，覆盖 ArcadeDB HTTP API 的端口，默认`2480`。

5.1 必填字段的校验行为

源码中，五个必填字段（uri、user、password、database、type）均带有validate:"required"标签。由单元测试 arcadedb_test.go 可以确认两类解析失败场景：

缺失必填字段：例如缺少password或database时，解析器返回类似Key: 'Config.Password' Error:Field validation for 'Password' failed on the 'required' tag的错误；
未知字段：配置中出现未定义字段（如foo: bar）时，解析器直接报错unknown field "foo"，保证配置的严谨性。

5.2 可选字段的默认值与作用

httpUri、httpScheme、httpPort三个可选字段共同决定了 SQL 通道所访问的 HTTP API 地址。它们的解析逻辑集中在 arcadeHTTPEndpointURL：

若显式配置了httpUri，则直接以它为 HTTP 基础 URL；
否则从uri（Bolt URI）中提取主机名（hostname）；
httpScheme为空时默认http；
httpPort为 0 时默认2480；
最终拼出{scheme}://{host}:{port}。

因此，当你的 Bolt 与 HTTP 服务部署在同一主机时，只需写uri: bolt://my-host:7687，SQL 通道会自动推导为http://my-host:2480；当二者分离或需要 HTTPS 时，再用可选字段覆盖。

6. 源码级原理：双协议通道设计

这是 ArcadeDB Source 最有特色的设计：Cypher 走 Bolt，SQL 走 HTTP，二者共享同一份 Source 配置与认证凭据。

6.1 Cypher 通道（Bolt + Neo4j 驱动）

RunCypher 的实现要点：

使用Neo4j Go 驱动 v6（github.com/neo4j/neo4j-go-driver/v6）创建驱动，因为 ArcadeDB 的 Bolt 端点兼容 Neo4j 驱动协议；
通过EXPLAIN前缀实现 dry-run：dryRun为 true 时把语句改写为EXPLAIN <cypher>，执行后从summary.Plan()递归构建执行计划树（buildPlanNode），返回包含queryType、statementType、operator、arguments、identifiers等字段的执行计划；
结果集通过helpers.ConvertValue（复用自 Neo4j 工具链的 helpers 包）转换为纯 map 结构返回。

6.2 SQL 通道（HTTP API）

RunSQL 直接调用 ArcadeDB 的 REST API：

只读路由：readOnly为 true 时请求query端点（ArcadeDB 会阻止写语句），否则请求command端点；
请求路径为{base}/api/v1/{query|command}/{database}，请求体为{"language": "sql", "command": <sql>, "params": {...}}，携带 Basic Auth；
EXPLAIN 支持：若 SQL 以EXPLAIN开头，响应中的explainPlan/explain字段会被提取为executionPlan/executionPlanAsString返回；
非 2xx 响应会连同状态码与响应体一起包装为错误返回。

6.3 连接建立与校验

Initialize 完成驱动的创建与连通性校验：

创建驱动（initArcadeDBDriver），设置BasicAuth与从上下文提取的 UserAgent；
调用driver.VerifyConnectivity(ctx)验证能否成功连接；
连接失败时关闭驱动并返回unable to connect successfully错误。

从 IsReadOnly 返回false可以看出，Source 本身是可读写的；readOnly约束是按工具配置的（见下文第 7 节），由各工具决定是否拒绝写操作。

6.4 查询分类器

Cypher 通道在执行前会调用classifier.NewQueryClassifier()（该分类器位于 internal/tools/neo4j/neo4jexecutecypher/classifier，由 arcadedb.go 引用）。分类器会把语句识别为读查询或写查询：

当工具配置了readOnly: true且语句被识别为写查询时，直接返回this tool is read-only and cannot execute write queries错误（arcadedb.go）；
分类结果同时会体现在 dry-run 返回的queryType字段中。

7. 配套工具的配置与调用

声明好 Source 后，即可配置工具。以下示例来自官方工具文档，并补充了源码中的参数说明。

7.1 arcadedb-execute-cypher

kind: tool name: query_arcadedb type: arcadedb-execute-cypher source: my-arcadedb-source readOnly: true description: | Execute Cypher against ArcadeDB in read-only mode. Example: {{ "cypher": "MATCH (n) RETURN count(n)" }}

字段参考（与 arcadedbexecutecypher.go 的Config对应）：

field	type	required	description
type	string	true	必须为`"arcadedb-execute-cypher"`。
source	string	true	要执行 Cypher 的 ArcadeDB Source 名称。
description	string	true	传给 LLM 的工具描述。源码要求该字段非空，否则初始化报错`description is required`。
readOnly	boolean	false	为`true`时拒绝 Cypher 中的写操作。默认`false`。

调用参数（在 Agent 调用时提供）：

参数	类型	说明
`cypher`	string	要执行的 Cypher 语句，必须为非空字符串（源码校验见 arcadedbexecutecypher.go）。
`params`	map	可选的 Cypher 参数，默认为空 map。
`dry_run`	boolean	为`true`时仅校验并返回执行计划信息而不真正执行。默认`false`。

7.2 arcadedb-execute-sql

kind: tool name: query_arcadedb_sql type: arcadedb-execute-sql source: my-arcadedb-source description: | Execute SQL against ArcadeDB. Example: {{ "sql": "SELECT FROM Person WHERE name = :name LIMIT 5", "params": { "name": "Ada" }, "dry_run": false }}

字段参考（与 arcadedbexecutesql.go 对应）：

field	type	required	description
type	string	true	必须为`"arcadedb-execute-sql"`。
source	string	true	要执行 SQL 的 ArcadeDB Source 名称。
description	string	true	传给 LLM 的工具描述。
readOnly	boolean	false	为`true`时语句被路由到只读端点，ArcadeDB 会阻止写语句。默认`false`。

调用参数：sql（必填，非空 SQL 语句）、params（可选 map 参数）、dry_run（可选，默认false）。注意，SQL 工具在dry_run时通过给语句加EXPLAIN前缀实现校验（arcadedbexecutesql.go），这与 Cypher 通道的实现方式一致。

7.3 工具的 Source 兼容性校验

两个工具都通过compatibleSource接口约束其可绑定的 Source（分别要求RunCypher与RunSQL方法），并在 ValidateSource 中校验：若绑定的 Source 不兼容，返回invalid source ... not a compatible type错误。这意味着这两个工具只会出现在 ArcadeDB（以及同样实现了这些接口的兼容 Source）上。

8. 集成测试与运行前提

仓库在 tests/arcadedb/arcadedb_integration_test.go 中提供了完整的集成测试，覆盖 YAML 解析、SQL 通道的数据播种/清理以及 Cypher/SQL 工具的真实执行。测试通过以下环境变量定位目标 ArcadeDB 实例：

环境变量	说明
`ARCADEDB_DATABASE`	目标数据库名（必填）
`ARCADEDB_URI`	Bolt URI，如`bolt://host:7687`（必填）
`ARCADEDB_USER`	用户名（必填）
`ARCADEDB_PASS`	密码（必填）
`ARCADEDB_HTTP_URL`	可选；不设置时测试会从 Bolt URI 推导 HTTP 地址（Bolt 端口替换为默认 HTTP 端口 2480）

从测试代码看，集成测试默认通过 Testcontainers 拉起 ArcadeDB 容器，并借助 HTTP API 完成测试数据的播种与清理，从而独立验证被测工具本身。该行为也从侧面印证了第 5.2 节描述的 HTTP 地址推导规则。

9. 总结

将 ArcadeDB 接入 MCP Toolbox for Databases 只需三步：

在 ArcadeDB 中准备好可经 Bolt 连接的用户（如root）；
在配置文件中声明type: arcadedb的 Source，填好uri、user、password、database，并用${ENV_NAME}保护密钥；
按需配置arcadedb-execute-cypher（图查询）与arcadedb-execute-sql（文档/多模型查询）两个工具，通过readOnly与dry_run控制安全边界。

双协议通道的设计让图查询（Bolt/Cypher）与文档查询（HTTP/SQL）各用其长：前者复用成熟的 Neo4j 驱动生态，后者直连 ArcadeDB 原生 SQL 能力。若需继续深入，可参阅配套工具文档 arcadedb-execute-cypher.md 与 arcadedb-execute-sql.md，以及集成索引 arcadedb/_index.md。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析