Firebird MCP Server

Firebird MCP 服务 🔥

🌐 语言 / Idioma： 英语 | 葡萄牙语（巴西）

面向 Firebird 数据库的开源 **Model Context Protocol（MCP）**服务，供社区免费、独立使用，支持所有主要版本（Firebird 2.5、3.0、4.0 和 5.0）。

根据 MCP 服务开放行业标准（stdio / JSON-RPC 2.0）构建，确保与任何 AI 客户端或 IDE开箱即用兼容：Google Antigravity IDE、Cursor、Claude Desktop、VS Code（搭配 Cline / Roo Code / Copilot 扩展）、Windsurf、Zed和命令行工具。

---

🎯 主要亮点

1. 纯 Python 线协议（无需 DLL 依赖）：
   • 使用纯 Python（firebirdsql）通过 TCP 直接连接（默认端口 3050）。
   • 无需原生 C/C++ 编译，也无需在运行 AI 客户端或 IDE 的主机上安装 fbclient.dll（Windows）或 libfbclient.so（Linux）。
   • 完全兼容旧版身份验证（FB 2.5 中的 Legacy_Auth）以及 FB 3.0、4.0 和 5.0 中现代的可插拔 SRP 身份验证。
2. 每个项目支持多个数据库：
   • 允许单个项目工作区声明和管理多个数据库（例如 main、audit_logs、staging），并通过聊天提示词或工具参数动态切换。
3. 工作区自动发现（.firebird-mcp.json）：
   • 自动检测放置在项目或代码库根目录中的数据库配置文件。
4. 执行计划与性能分析（PLAN）：
   • 编译查询以提取 Firebird 优化器的执行计划（PLAN），无需扫描整个数据集，即可检测未建立索引的全表扫描（NATURAL SCAN）以及内存／磁盘排序瓶颈（SORT）。
5. 严格的查询安全与 MVCC 最佳实践：
   • fb_query 强制执行只读操作（SELECT），避免意外修改数据。
   • 读取事务完成后立即提交，避免 **OAT（最旧的活动事务）**停滞、垃圾回收受阻以及 .fdb 数据库文件失控增长。
6. 广泛的系统目录映射：
   • 全面检查 Firebird 系统目录表（RDB$），支持各版本中的类型：BOOLEAN（FB3+）、INT128、DECFLOAT(16/34)、TIMESTAMP WITH TIME ZONE（FB4+）、BLOB SUB_TYPE TEXT/BINARY，以及索引选择性（RDB$STATISTICS）。

---

🗄️ 多数据库与按项目配置

实际生产代码库（例如使用 Delphi、Laravel 或 Python 的企业 ERP）通常需要：

• 为不同项目／工作区配置不同的数据库。
• 在同一个项目中使用多个数据库（例如业务数据库 ERP_DATA.FDB 和审计日志数据库 AUDIT_LOGS.FDB）。

数据库的配置位置和方式：

Firebird MCP 提供两种灵活的组织模式：

选项 A（推荐默认）：中央全局目录（~/.firebird-mcp.json）

与其在每个仓库中分散放置 .firebird-mcp.json 文件，不如在用户主目录中维护一个中央目录（Linux/macOS 上为 ~/.firebird-mcp.json，Windows 上为 C:\Users\YourUser\.firebird-mcp.json）。

在此目录中，注册计算机上的所有数据库，并使用 "projects" 属性指定各数据库适用的项目/仓库：

{
  "default": "erp_main",
  "databases": {
    "erp_main": {
      "host": "localhost",
      "port": 3050,
      "database": "/var/data/ERP_DATA.FDB",
      "user": "SYSDBA",
      "password": "masterkey",
      "charset": "WIN1252",
      "description": "Primary ERP operational database",
      "projects": ["web_projects", "erp-desktop"],
      "tags": ["erp", "financial", "sales"]
    },
    "erp_audit": {
      "host": "localhost",
      "port": 3050,
      "database": "/var/data/AUDIT_LOGS.FDB",
      "user": "SYSDBA",
      "password": "masterkey",
      "charset": "WIN1252",
      "description": "Secondary database for audit trails and logs",
      "projects": ["web_projects", "erp-desktop"],
      "tags": ["audit", "logs", "security"]
    },
    "pos_store": {
      "host": "192.168.1.10",
      "port": 3050,
      "database": "C:\\POS\\STORE.FDB",
      "user": "SYSDBA",
      "password": "masterkey",
      "charset": "WIN1252",
      "description": "Store front checkout database",
      "projects": ["pos-vcl"],
      "tags": ["pos", "cashier"]
    },
    "shared_staging": {
      "host": "localhost",
      "port": 3050,
      "database": "/data/STAGING.FDB",
      "user": "SYSDBA",
      "password": "masterkey",
      "charset": "WIN1252",
      "description": "Shared staging/test database accessible across all projects",
      "projects": []
    }
  }
}

共享数据库提示："projects": [] 数组为空或值为 "*" 的数据库会被视为全局共享数据库，并在所有工作区中保持可见。

选项 B：本地项目配置（.firebird-mcp.json）

如果希望仓库隔离各自的凭据，请在项目根目录中放置 .firebird-mcp.json 文件。MCP 会优先检查本地项目文件；如果该文件存在，其优先级绝对高于全局目录。

---

Agent 如何与数据库交互：

1. 自动工作区上下文（CWD）：
   • 打开工作区时（例如 /home/lucas/web_projects），MCP 会自动解析当前项目，并筛选出与该项目匹配的数据库。
   • **项目中只有一个数据库：**MCP 会自动选择该数据库，不会提出不必要的问题。
   • **项目中有多个数据库（例如 main 和 audit）：**对于通用命令（例如 “对 orders 执行 select”），MCP 会暂停并询问要使用哪个数据库。
2. 直接指定调查目标（零阻碍）：
   • 如果你在提示词中提到数据库（例如 “调查 audit 数据库上的错误” 或 “检查 pos 上的 X 表”），Agent/MCP 会立即解析别名并连接，不会询问确认。
3. 智能模糊搜索：
   • 使用 fb_use_database("audit") 切换数据库；MCP 会匹配精确名称、部分名称（例如 erp_audit）和相关标签。
4. ⚠️ 严格安全规则：DDL 和数据操作（DML）必须进行双重确认：
   • 结构变更命令（CREATE、ALTER、DROP、RECREATE）和数据变更命令（INSERT、UPDATE、DELETE、EXECUTE PROCEDURE）绝不会在未事先获得用户明确同意的情况下直接执行。
   • 助手必须展示完整的 SQL/DDL 语句，说明其技术用途，详细说明影响（受影响的行/表、锁定风险、不可逆性），并请求确认。
   • 除非用户明确同意后传入 confirmed=True 参数，否则 MCP 服务会阻止执行并返回错误。

---

🛠️ 可用的 MCP 工具

数据库与连接管理

工具	参数	描述
fb_create_config	database、alias、host、port、user、password、charset、description、projects、tags、filepath	创建并保存中央全局目录（~/.firebird-mcp.json）或包含项目标签的本地文件。
fb_list_databases	project_filter （可选）	列出目录中的所有数据库，并突出显示与当前项目匹配的数据库。
fb_use_database	alias	为当前会话切换活动数据库（智能匹配名称、部分名称或标签）。
fb_configure_database	alias、database、host、port、user、password、charset、description、projects、tags、set_as_default、save_to_file	动态注册或更新连接及其项目/标签，并保存到文件。
fb_reload_config	config_path （可选）	从全局或本地文件重新加载目录。

架构与元数据检查

工具	参数	描述
fb_list_tables	db_alias (可选)	列出所有用户表（筛除 RDB$ 系统表）。
fb_list_views	db_alias (可选)	列出所有已注册的用户视图。
fb_list_procedures	db_alias (可选)	列出所有用户存储过程。
fb_list_generators	db_alias (可选)	列出所有用户生成器／序列。
fb_inspect_table	table_name、db_alias (可选)	返回列定义、精确数据类型、PK／FK 约束，以及包含实际选择性（RDB$STATISTICS）的索引。

性能分析与执行

工具	参数	描述
fb_explain_plan	sql、db_alias (可选)	在引擎中编译查询、提取 PLAN、突出显示 NATURAL SCAN 警告，并提供索引策略建议。
fb_query	sql、limit（默认 50，最大 1000）、db_alias (可选)	执行带安全防护和即时事务提交的只读 SELECT 查询。
fb_execute_dml	sql、db_alias (可选)、confirmed（默认 false）	执行明确指定的 INSERT、UPDATE、DELETE 或 EXECUTE PROCEDURE 语句。必须进行双重确认（confirmed=True）。
fb_execute_ddl	ddl、db_alias (可选)、confirmed（默认 false）	执行结构性 DDL 语句（CREATE INDEX、ALTER TABLE 等），并显式提交。必须进行双重确认（confirmed=True）。
fb_database_health	db_alias (可选)	通过 MON$ 表审计数据库健康状况（ODS 版本、页大小、活动连接，以及 OAT 与 Next-Transaction 之间的差距）。

---

💻 安装与运行

🐳 选项 1：Docker（黄金标准 — Windows、macOS 和 Linux 推荐）

使用 Docker 运行无需本地 Python 运行时和依赖项：

# Clone and build the image locally:
git clone https://github.com/lucasgabriel0802/firebird-mcp.git
cd firebird-mcp
docker build -t firebird-mcp:latest .

通过 Docker 进行通用 IDE 配置（Stdio 模式）：

配置 IDE 按需启动容器。此配置可在 Windows、macOS 和 Linux 上无缝运行：

{
  "mcpServers": {
    "firebird": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "${workspaceFolder}:/workspace",
        "-w", "/workspace",
        "--add-host", "host.docker.internal:host-gateway",
        "firebird-mcp:latest"
      ]
    }
  }
}

为何这是黄金标准：

• -i：保持 stdin/stdout 打开以支持 JSON-RPC，且不分配伪 TTY（不使用 -t，以免字节损坏）。
• --rm：IDE 关闭时自动清理容器。
• -v "${workspaceFolder}:/workspace"：挂载当前项目，以便自动发现 .firebird-mcp.json。
• --add-host host.docker.internal:host-gateway：使用 host.docker.internal 解析主机的 IP（例如 Firebird 在 Windows、macOS 或 Linux 上运行于端口 3050）。

---

🚀 选项 2：Docker Compose（后台服务与预置测试数据库）

A. 作为 HTTP/SSE 后台服务运行

如果你希望 MCP 服务作为永久后台服务运行在端口 8000 上：

docker compose up -d firebird-mcp

通过 SSE 端点连接：http://localhost:8000/sse。

B. 完整本地测试环境（含 Firebird 5.0 数据库）

启动 MCP 服务和一个可直接测试的 Firebird 5.0 数据库容器：

docker compose --profile test-db up -d

这会启动：

• 运行于 localhost:3050 的 Firebird 5.0（密码：masterkey，数据库：TESTE.FDB）。
• 运行于 http://localhost:8000/sse 的 Firebird MCP Server。

---

🐍 选项 3：本地 Python 虚拟环境

git clone https://github.com/lucasgabriel0802/firebird-mcp.git ~/firebird-mcp
cd ~/firebird-mcp
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e .

---

⚙️ 适用于任何 IDE 的通用配置

1. Google Antigravity IDE

在 ~/.gemini/config/mcp_config.json 中（或工作区配置中）：

使用 Docker（通过包装脚本或 shell）：

💡 注意： Antigravity IDE 会按原样传递参数，不会展开 ${workspaceFolder} 这类 VS Code 变量。请使用仓库中附带的 docker-mcp.sh 包装脚本：

docker-mcp.sh 的内容（包含在仓库根目录中）：

#!/usr/bin/env bash
set -e

exec docker run -i --rm \
  -v "${PWD}:/workspace" \
  -w /workspace \
  --add-host host.docker.internal:host-gateway \
  firebird-mcp:latest "$@"

确保该脚本可执行（chmod +x docker-mcp.sh），并在配置中引用它：

{
  "mcpServers": {
    "firebird": {
      "command": "/home/<userName>/firebird-mcp/docker-mcp.sh"
    }
  }
}

或使用 Python 虚拟环境：

{
  "mcpServers": {
    "firebird": {
      "command": "/home/<userName>/firebird-mcp/venv/bin/python",
      "args": ["-m", "firebird_mcp.server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

---

2. Cursor

在项目根目录的 .cursor/mcp.json 中，或在 Settings > Features > MCP 中：

{
  "mcpServers": {
    "firebird": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "${workspaceFolder}:/workspace",
        "-w", "/workspace",
        "--add-host", "host.docker.internal:host-gateway",
        "firebird-mcp:latest"
      ]
    }
  }
}

---

3. VS Code（Cline / Roo Code / Copilot MCP）

在 cline_mcp_settings.json 或 Roo Code 设置中：

{
  "mcpServers": {
    "firebird": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "${workspaceFolder}:/workspace",
        "-w", "/workspace",
        "--add-host", "host.docker.internal:host-gateway",
        "firebird-mcp:latest"
      ]
    }
  }
}

---

4. Claude Desktop

在 claude_desktop_config.json 中：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "firebird": {
      "command": "python",
      "args": ["-m", "firebird_mcp.server", "--config", "C:\\my_project\\.firebird-mcp.json"],
      "cwd": "C:\\my_project"
    }
  }
}

---

5. Windsurf

在 ~/.codeium/windsurf/mcp_config.json 中：

{
  "mcpServers": {
    "firebird": {
      "command": "python3",
      "args": ["-m", "firebird_mcp.server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

---

6. Zed Editor

在 Zed 的 settings.json 中：

{
  "context_servers": {
    "firebird": {
      "command": {
        "path": "python3",
        "args": ["-m", "firebird_mcp.server"]
      }
    }
  }
}

---

🧠 协同使用：firebird-master 技能 + firebird-mcp

此 MCP 服务与 firebird-master 技能协同工作：

┌────────────────────────────────────────────────────────┐
│                   AI AGENT / COPILOT                   │
├──────────────────────────┬─────────────────────────────┤
│  SKILL: firebird-master  │     MCP: firebird-mcp       │
│         (Brain)          │          (Muscle)           │
├──────────────────────────┼─────────────────────────────┤
│ • Cross-version syntax   │ • TCP socket wire protocol  │
│   (FB 2.5 vs 3 vs 4 vs 5)│ • Executes & fetches PLAN   │
│ • SQL anti-pattern rules │ • Introspects RDB$ schema   │
│ • Delphi FireDAC best    │ • Gathers MON$ telemetry    │
│   practices & index hints│ • Auto-discovers project DB │
└──────────────────────────┴─────────────────────────────┘

---

⚖️ 免责声明与商标

• Firebird：“Firebird”是 Firebird Foundation 的注册商标。这是一个依据 MIT License 许可的独立开源社区项目，与 Firebird Project 或 Firebird Foundation 没有关联，也未获得其资助、认可或官方支持。
• Model Context Protocol：“Model Context Protocol”和“MCP”是 Anthropic, PBC 的商标。本项目是一个符合开放 MCP 标准的独立实现。
• **责任限制：**本软件直接连接数据库服务器，并根据用户/Agent 的指示执行查询或命令。请始终定期备份数据库，并在生产环境执行查询前进行核验。根据 MIT License 的条款，本软件按“原样”提供，不提供任何形式的保证；作者不对任何损害或数据丢失承担责任。

---

📄 许可证

根据 MIT License 分发。