MCP Toolbox 的 firebird-execute-sql 工具：在 Firebird 数据库上执行任意 SQL 的完整指南

MCP Toolbox 的 firebird-execute-sql 工具：在 Firebird 数据库上执行任意 SQL 的完整指南

【免费下载链接】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 中firebird-execute-sql工具的定义与使用：它接受单个sql参数，将该语句在指定的 Firebird 数据源上直接执行，适用于带人工介入（human-in-the-loop）的开发者辅助工作流。读完本文，你将掌握该工具在 YAML 配置中的完整字段说明、与firebird-sql预定义语句工具的差异、底层执行原理（实现源码），以及配套 Firebird source 的连接配置方式。

About：什么是 firebird-execute-sql

firebird-execute-sql是 MCP Toolbox 为 Firebird 数据库集成提供的工具之一，其核心行为是执行一条针对 Firebird 数据库的 SQL 语句。与firebird-sql工具不同，firebird-execute-sql不预定义 SQL 语句，而是只接收一个名为sql的输入参数，并在配置指定的source数据源上运行该语句。

该工具的定位非常明确：面向带人工介入的开发者辅助工作流（例如开发者在 IDE 或 MCP 客户端中让助手查询、修改数据库），官方文档明确提示不应将其用于生产环境的自动化 Agent。这意味着使用方应当自行控制其暴露范围与鉴权策略。

Note:从源码看，该工具默认携带破坏性（destructive）注解。在 Initialize 方法 中，当未显式提供annotations时，工具会通过tools.NewDestructiveAnnotations生成默认注解，表明该工具默认被标记为可能修改数据，客户端（如 Claude、Gemini CLI 等 MCP 宿主）会据此对模型施加更严格的使用约束。

与其他 Firebird 工具的分工

在 Firebird 集成文档 下，MCP Toolbox 共提供两个 SQL 相关工具，理解二者差异有助于选择正确的工具：

firebird-sql会将语句作为预编译语句（prepared statement）执行，并明确警告模板参数可直接改写标识符、列名、表名，因此更易受 SQL 注入影响；而firebird-execute-sql连参数化机制都不提供，安全性完全依赖调用方。因此，凡是能固化为模板的查询，应优先选用firebird-sql。

配置示例

在 MCP Toolbox 的 YAML 配置中，firebird-execute-sql按kind: tool声明。以下是官方文档给出的最小可用示例：

kind: tool name: execute_sql_tool type: firebird-execute-sql source: my_firebird_db description: Use this tool to execute a SQL statement against the Firebird database.

• name是工具在 MCP 会话中的唯一标识（如execute_sql_tool）；
• source必须指向一个已定义且类型兼容的 Firebird 数据源（如示例中的my_firebird_db）；
• description会原样传递给 LLM，用于帮助模型判断何时调用该工具，建议写清楚适用边界，例如"仅当用户明确给出完整 SQL 时才使用"。

在解析层，工具配置还支持可选的authRequired字段。相关单元测试 firebirdexecutesql_test.go 验证了带authRequired: [my-google-auth-service, other-auth-service]的配置可以被正确解析到Config.AuthRequired，从而将该工具与指定的认证服务绑定。同时测试也证明type必须严格等于firebird-execute-sql，source为必填项。

Reference：字段速查

其中description的必填约束在源码中得到了印证：在Initialize中，如果cfg.Description == ""，会直接返回"description is required for tool"错误（见 firebirdexecutesql.go）。

底层执行原理：从 Invoke 到 RunSQL

理解该工具的执行链路有助于评估其行为边界。整个调用过程如下：

1. 参数提取：Invoke方法从parameters.ParamValues中取出sql参数，并断言其类型为string；若类型不符会返回 Agent 错误。该sql参数由parameters.NewStringParameter("sql", "The sql to execute.")在初始化时注册（见 firebirdexecutesql.go）。
2. 兼容性校验：工具要求source实现compatibleSource接口（含FirebirdDB()与RunSQL(...)两个方法），不兼容的数据源会被拒绝。
3. 日志记录：执行前会通过logger.DebugContext记录实际执行的 SQL，便于调试审计。
4. 语句执行：以nil参数调用source.RunSQL(ctx, sqlStr, nil)，即不携带任何绑定参数，用户传入的 SQL 原样交给数据源。

在 Firebird source 实现 中，RunSQL通过FirebirdDB().QueryContext(ctx, statement, params...)执行查询，然后读取列信息并将每行扫描为map[string]any（字节切片类型的值会被转换为字符串）。对于 INSERT、UPDATE、CREATE 等 DML/DDL 语句，结果集通常为空，此时返回空列表——从源码注释看，空结果与"查询本应返回数据但未返回"两种情况无法在工具层区分，调用方需要结合 SQL 语义自行判断。

值得注意的实现细节：Firebird 驱动采用github.com/nakagami/firebirdsql，DSN 格式为user:password@host:port/path/to/database.fdb（见 initFirebirdConnectionPool）。连接池默认配置为SetMaxOpenConns(5)、SetMaxIdleConns(2)、连接最大存活 5 分钟、空闲 1 分钟，以避免死锁并控制资源占用。此外IsReadOnly()返回false，说明该数据源默认允许写操作，与工具的破坏性默认注解一致。

配套 Firebird Source 的声明

firebird-execute-sql依赖一个可用的 Firebird 数据源。按 Firebird source 文档，source 配置如下：

kind: source name: my_firebird_db type: firebird host: "localhost" port: 3050 database: "/path/to/your/database.fdb" user: ${FIREBIRD_USER} password: ${FIREBIRD_PASS}

强烈建议使用${ENV_NAME}环境变量替换机制存放密码等敏感信息，而不是把明文密钥写进配置文件。源码中的 解析测试 验证了必填字段校验与未知字段拒绝逻辑：缺少password会触发required校验失败，多余字段（如foo: bar）会导致 YAML 解析报错。

安全与使用建议

1. 保持人工介入：该工具专为开发者辅助工作流设计，文档明确警示不要用于生产 Agent；将工具绑定到需要人工确认的 MCP 宿主或加上authRequired认证约束，可显著降低误操作风险。
2. 优先使用参数化工具：对于可复用的查询，改用 firebird-sql 的位置参数（?）或命名参数（:param_name）形式，其预编译语句机制可防止 SQL 注入，性能也更好。
3. 审计 SQL：firebird-execute-sql不提供任何参数绑定，属于完全开放执行；建议在 description 中约束 LLM 只执行用户明确授权的语句，并结合调试日志对执行记录进行审计。
4. 限制连接资源：连接池默认上限为 5 个并发连接，若你的工作流并发度较高，可在源码层面按需调整（修改SetMaxOpenConns等参数后重新构建）。

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