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、CLI ツールです。

---

🎯 主な特長

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. プロジェクトごとに複数のデータベースをサポート：
   • 1 つのプロジェクトのワークスペースで複数のデータベース（例：main、audit_logs、staging）を宣言して管理でき、チャットのプロンプトやツールの引数から動的に切り替えられます。
3. ワークスペースの自動検出（.firebird-mcp.json）：
   • プロジェクトまたはリポジトリのルートに配置されたデータベース設定ファイルを自動的に検出します。
4. 実行計画とパフォーマンス分析（PLAN）：
   • データセット全体をスキャンせずにクエリをコンパイルし、Firebird オプティマイザーの実行計画（PLAN）を抽出します。インデックスのない全表スキャン（NATURAL SCAN）や、メモリ／ディスクのソートによるボトルネック（SORT）を検出します。
5. 厳格なクエリ安全性と MVCC のベストプラクティス：
   • fb_query は読み取り専用操作（SELECT）を強制し、誤ったデータ変更を防ぎます。
   • 読み取りトランザクションは完了後すぐにコミットされ、**OAT（Oldest Active Transaction）**の停滞、ガベージコレクションの停滞、.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 では、柔軟な構成パターンを 2 つ用意しています。

オプション 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 は最初にローカルプロジェクトファイルを確認し、ファイルが存在する場合は、グローバルカタログよりも絶対的に優先されます。

---

エージェントとデータベースの連携方法：

1. ワークスペースコンテキストの自動取得（CWD）：
   • ワークスペース（例：/home/lucas/web_projects）を開くと、MCP はアクティブなプロジェクトを自動的に特定し、そのプロジェクトに一致するデータベースを絞り込みます。
   • プロジェクト内のデータベースが 1 つの場合： MCP は不要な質問をせずにデータベースを自動選択します。
   • プロジェクト内のデータベースが複数の場合（例：main と audit）： 一般的なコマンド（例：「orders に対して select を実行して」）では、MCP は処理を一時停止し、使用するデータベースを確認します。
2. 調査対象の直接指定（手間なし）：
   • プロンプトでデータベースを指定した場合（例：「audit データベースのバグを調査して」、または 「pos のテーブル X を確認して」）、エージェント／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：疑似 TTY を割り当てずに JSON-RPC 用の stdin/stdout を開いたままにします（バイト破損を防ぐため -t は指定しません）。
• --rm：IDE を閉じると、コンテナを自動的にクリーンアップします。
• -v "${workspaceFolder}:/workspace"：現在のプロジェクトをマウントし、.firebird-mcp.json を自動検出できるようにします。
• --add-host host.docker.internal:host-gateway：host.docker.internal を使用して、ホストマシンの IP（例：Windows、macOS、Linux でポート 3050 を使用して実行中の Firebird）を解決します。

---

🚀 オプション 2：Docker Compose（バックグラウンドサービスとテスト用 DB を含む環境）

A. HTTP/SSE バックグラウンドサービスとして実行

ポート 8000 で MCP サーバーを常時稼働するバックグラウンドサービスとして実行する場合：

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 を使用する場合（ラッパースクリプトまたはシェル経由）：

💡 注： 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 標準に準拠した独立した実装です。
• **責任の制限：**このソフトウェアはデータベースサーバーに直接接続し、ユーザーまたはエージェントの指示に従ってクエリやコマンドを実行します。データベースの定期的なバックアップを必ず維持し、本番環境で実行する前にクエリを確認してください。MIT License の条件に基づき、このソフトウェアは「現状有姿」で提供され、いかなる種類の保証もありません。また、著者は損害やデータ損失について一切責任を負いません。

---

📄 ライセンス

MIT License の下で配布されています。