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类型 SourceMCP 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.mdarcadedb-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 配置声明如下 Sourcekind: source name: my-arcadedb-source type: arcadedb uri: bolt://localhost:7687 user: root password: ${PASSWORD} database: mydb4.1 使用环境变量替换敏感信息官方文档特别提示请使用${ENV_NAME}格式的环境变量替换而不是把密钥硬编码进配置文件。上面的password: ${PASSWORD}即会在运行时从环境变量PASSWORD中读取真实密码避免密钥泄露到版本库中。同一模式也适用于user等其它敏感字段。4.2 带 HTTP 覆盖项的完整示例当 ArcadeDB HTTP API 与 Bolt 端点不在同一主机/端口或需要强制使用 HTTPS 时可补充三个可选字段。该示例同样得到单元测试的覆盖见 arcadedb_test.gokind: 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: 24815. 参数参考表含源码佐证关联文档的 Reference 表如下字段与 arcadedb.go 中Config结构体的 YAML 标签一一对应fieldtyperequireddescriptiontypestringtrue必须为arcadedb。uristringtrueBolt URI例如bolt://localhost:7687。userstringtrueArcadeDB 用户例如root。passwordstringtrueArcadeDB 用户的密码。databasestringtrue要连接的数据库名称。httpUristringfalse可选覆盖 ArcadeDB HTTP API 的基础 URL例如http://localhost:2480。httpSchemestringfalse可选覆盖 ArcadeDB HTTP API 的 scheme默认http。httpPortintegerfalse可选覆盖 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否则从uriBolt URI中提取主机名hostnamehttpScheme为空时默认httphttpPort为 0 时默认2480最终拼出{scheme}://{host}:{port}。因此当你的 Bolt 与 HTTP 服务部署在同一主机时只需写uri: bolt://my-host:7687SQL 通道会自动推导为http://my-host:2480当二者分离或需要 HTTPS 时再用可选字段覆盖。6. 源码级原理双协议通道设计这是 ArcadeDB Source 最有特色的设计Cypher 走 BoltSQL 走 HTTP二者共享同一份 Source 配置与认证凭据。6.1 Cypher 通道Bolt Neo4j 驱动RunCypher 的实现要点使用Neo4j Go 驱动 v6github.com/neo4j/neo4j-go-driver/v6创建驱动因为 ArcadeDB 的 Bolt 端点兼容 Neo4j 驱动协议通过EXPLAIN前缀实现 dry-rundryRun为 true 时把语句改写为EXPLAIN cypher执行后从summary.Plan()递归构建执行计划树buildPlanNode返回包含queryType、statementType、operator、arguments、identifiers等字段的执行计划结果集通过helpers.ConvertValue复用自 Neo4j 工具链的 helpers 包转换为纯 map 结构返回。6.2 SQL 通道HTTP APIRunSQL 直接调用 ArcadeDB 的 REST API只读路由readOnly为 true 时请求query端点ArcadeDB 会阻止写语句否则请求command端点请求路径为{base}/api/v1/{query|command}/{database}请求体为{language: sql, command: sql, params: {...}}携带 Basic AuthEXPLAIN 支持若 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-cypherkind: 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对应fieldtyperequireddescriptiontypestringtrue必须为arcadedb-execute-cypher。sourcestringtrue要执行 Cypher 的 ArcadeDB Source 名称。descriptionstringtrue传给 LLM 的工具描述。源码要求该字段非空否则初始化报错description is required。readOnlybooleanfalse为true时拒绝 Cypher 中的写操作。默认false。调用参数在 Agent 调用时提供参数类型说明cypherstring要执行的 Cypher 语句必须为非空字符串源码校验见 arcadedbexecutecypher.go。paramsmap可选的 Cypher 参数默认为空 map。dry_runboolean为true时仅校验并返回执行计划信息而不真正执行。默认false。7.2 arcadedb-execute-sqlkind: 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 对应fieldtyperequireddescriptiontypestringtrue必须为arcadedb-execute-sql。sourcestringtrue要执行 SQL 的 ArcadeDB Source 名称。descriptionstringtrue传给 LLM 的工具描述。readOnlybooleanfalse为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_URIBolt 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），仅供参考