Firebird Context Protocol Adapter

This package provides an implementation adhering to Anthropic's Model Context Protocol (MCP) specifically engineered for secure interaction with Firebird SQL database systems.

Illustrative Execution

https://github.com/user-attachments/assets/e68e873f-f87b-4afd-874f-157086e223af

Overview of Firebird MCP Adapter

This utility operates as a dedicated server implementing the Model Context Protocol (MCP) standard, tailored for connecting to Firebird SQL systems. It grants Large Language Models (LLMs), such as Claude, controlled and secure mechanisms to probe, interpret, and alter data resident within Firebird.

Core Capabilities

SQL Execution: Run arbitrary Structured Query Language statements against the Firebird instance.
Schema Introspection: Retrieve comprehensive metadata concerning tables, attributes, and relational constraints.
Database Administration: Support for essential administrative functions including archival (backup), restoration, and integrity checks.
Optimization Analysis: Evaluate query execution plans and propose enhancements for improved throughput.
Transport Modalities: Compatible with STDIO for local use, Server-Sent Events (SSE), and the latest Streamable HTTP transport.
Protocol Adherence: Full interoperability with MCP Streamable HTTP (spec version 2025-03-26) alongside legacy SSE support.
Server Unification: Features automated protocol sensing and built-in backward compatibility layers.
LLM Synergy: Designed for native integration with Claude Desktop and other compliant MCP clients.
IDE Integration: Functional integration within Visual Studio Code environments, particularly with GitHub Copilot.
State Management: Robust handling of user sessions, encompassing automated resource deallocation and configurable inactivity timeouts.
Safeguards: Incorporates validation logic for submitted SQL and configurable security parameters.

Local Installation Guide

Current Stable Release

# Acquire globally (stable channel)
npm install -g mcp-firebird

# Initiate the server service
npx mcp-firebird --database /path/to/database.fdb

# Or pin to a precise stable version
npm install -g mcp-firebird@2.2.3

Stable Changelog (v2.2.3): - 🐛 Resolved: A parsing flaw in SSE JSON handling causing "Invalid message: [object Object]" failures. - ✨ Implemented support for Streamable HTTP transport (MCP 2025-03-26). - 🔄 Consolidated server architecture with automatic transport protocol discernment. - 📊 Refined session lifecycle oversight and monitoring metrics. - 🛠️ Updated to the current MCP SDK baseline (v1.13.2). - 🔧 Improved robustness in error reporting and internal logging mechanisms. - 🧪 Expanded verification suite, now including over 9 dedicated tests for SSE interaction.

Preview/Development Build (Alpha)

# Install the pre-release version encompassing the newest features
npm install -g mcp-firebird@alpha

# Or target a specific alpha iteration
npm install -g mcp-firebird@2.3.0-alpha.1

Alpha Changelog (v2.3.0-alpha.1): - 🐛 Resolved: A parsing flaw in SSE JSON handling causing "Invalid message: [object Object]" failures. - ✨ Implemented support for Streamable HTTP transport (MCP 2025-03-26). - 🔄 Consolidated server architecture with automatic transport protocol discernment. - 📊 Refined session lifecycle oversight and monitoring metrics. - 🛠️ Updated to the current MCP SDK baseline (v1.13.2). - 🔧 Improved robustness in error reporting and internal logging mechanisms. - 🧪 Expanded verification suite, now including over 9 dedicated tests for SSE functionality. - 📚 Augmented documentation with new guides focused on diagnostic procedures.

For necessary operations like data archiving or recovery, ensure Firebird client utilities are present. Refer to Complete Installation for prerequisites.

For guidance on setting up interactions with VSCode and GitHub Copilot, consult VSCode Integration.

Initial Execution Steps

Integration with Claude Desktop

Modify the Claude Desktop configuration file: bash code $env:AppData\Claude\claude_desktop_config.json # Windows paths code ~/Library/Application\ Support/Claude/claude_desktop_config.json # macOS paths
Inject the MCP Firebird server configuration block: json { "mcpServers": { "mcp-firebird": { "command": "npx", "args": [ "mcp-firebird", "--host", "localhost", "--port", "3050", "--database", "C:\\path\to\database.fdb", "--user", "SYSDBA", "--password", "masterkey" ], "type": "stdio" } } }
Relaunch the Claude Desktop application.

Transport Layer Configuration

MCP Firebird offers selection among various communication mechanisms to suit diverse client environments and deployment topologies.

STDIO Link (Default Behavior)

This transport method is the standard choice when integrating directly with Claude Desktop:

{
  "mcpServers": {
    "mcp-firebird": {
      "command": "npx",
      "args": [
        "mcp-firebird",
        "--database", "C:\\path\to\database.fdb",
        "--user", "SYSDBA",
        "--password", "masterkey"
      ],
      "type": "stdio"
    }
  }
}

SSE Link (Server-Sent Events)

SSE enables the adapter to function as a persistent web service, beneficial for browser-based applications and remote access scenarios:

Basic SSE Setup

# Launch SSE service on default listening port 3003
npx mcp-firebird --transport-type sse --database /path/to/database.fdb

# Detailed command with custom parameters
npx mcp-firebird \
  --transport-type sse \
  --sse-port 3003 \
  --database /path/to/database.fdb \
  --host localhost \
  --port 3050 \
  --user SYSDBA \
  --password masterkey

Environment Variable Configuration for SSE

# Define environment variables
export TRANSPORT_TYPE=sse
export SSE_PORT=3003
export DB_HOST=localhost
export DB_PORT=3050
export DB_DATABASE=/path/to/database.fdb
export DB_USER=SYSDBA
export DB_PASSWORD=masterkey

# Execute server
npx mcp-firebird

SSE Client Connectivity Points

When the SSE server is operational, clients should target the following URLs: - SSE Data Stream: http://localhost:3003/sse - Message Ingress: http://localhost:3003/messages - Service Status Check: http://localhost:3003/health

Streamable HTTP Link (Current MCP Standard)

This utilizes the most recent MCP specification that facilitates genuine bidirectional data flow:

# Initiate service using Streamable HTTP mode
npx mcp-firebird --transport-type http --http-port 3003 --database /path/to/database.fdb

Unified Transport (Recommended Approach)

This mode supports concurrent operation of both SSE and Streamable HTTP listeners, allowing for automatic protocol identification:

# Start server capable of handling both SSE and Streamable HTTP
npx mcp-firebird --transport-type unified --http-port 3003 --database /path/to/database.fdb

Unified Server Network Access Points

SSE (Legacy Path): http://localhost:3003/sse
Streamable HTTP (Modern Path): http://localhost:3003/mcp
Protocol Auto-Detect: http://localhost:3003/mcp-auto
Status Endpoint: http://localhost:3003/health

Configuration Blueprints

Sandbox/Development Setup (SSE Focused)

npx mcp-firebird \
  --transport-type sse \
  --sse-port 3003 \
  --database ./dev-database.fdb \
  --user SYSDBA \
  --password masterkey

Production Deployment (Unified Mode)

npx mcp-firebird \
  --transport-type unified \
  --http-port 3003 \
  --database /var/lib/firebird/production.fdb \
  --host db-server \
  --port 3050 \
  --user APP_USER \
  --password $DB_PASSWORD

Containerized Deployment via Docker (SSE Example)

docker run -d \
  --name mcp-firebird \
  -p 3003:3003 \
  -e TRANSPORT_TYPE=sse \
  -e SSE_PORT=3003 \
  -e DB_DATABASE=/data/database.fdb \
  -v /path/to/database:/data \
  purodelphi/mcp-firebird:latest

Advanced Settings for SSE

Session Configuration

Control session duration and concurrency limits:

# Environmental variables for session lifecycle control
export SSE_SESSION_TIMEOUT_MS=1800000    # 30 minutes idle limit
export MAX_SESSIONS=1000                 # Upper bound on concurrent connections
export SESSION_CLEANUP_INTERVAL_MS=60000 # Frequency of dormant session sweeps (1 minute)

npx mcp-firebird --transport-type sse

Necessary configurations for web-based client integration:

# Specify explicitly permitted client sources
export CORS_ORIGIN="https://myapp.com,https://localhost:3000"
export CORS_METHODS="GET,POST,OPTIONS"
export CORS_HEADERS="Content-Type,mcp-session-id"

npx mcp-firebird --transport-type sse

SSL/TLS Security Implementation

For securing external endpoints, deploying a reverse proxy (e.g., nginx) is the recommended practice:

server {
    listen 443 ssl;
    server_name mcp-firebird.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3003;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Troubleshooting SSE Connections

Pervasive Issues

Connection Refused Errors ```bash # Verify service responsiveness curl http://localhost:3003/health

# Check active listeners on the port netstat -an | grep 3003 ```

Session Expiry Too Rapid bash # Extend the allowed inactive duration export SSE_SESSION_TIMEOUT_MS=3600000 # Set to 1 hour
CORS Policy Violations bash # Temporary relaxation for development (USE WITH CAUTION) export CORS_ORIGIN="*"
Resource Exhaustion (Memory) ```bash # Lower the ceiling on concurrent client connections export MAX_SESSIONS=100

# Increase how often the system scans for and removes idle sessions export SESSION_CLEANUP_INTERVAL_MS=30000 ```

Data Serialization Errors (Specifically "Invalid message: [object Object]") ```bash # Update to the most recent preview release to obtain the fix: npm install mcp-firebird@alpha

# Or initiate directly from the latest alpha build: npx mcp-firebird@alpha --transport-type sse ```

Critical Note: Versions released before 2.3.0-alpha.1 contained a defect preventing correct JSON body interpretation on POST requests to the /messages endpoint. This has been rectified via improved request middleware handling for both application/json and text/plain message formats.

Monitoring and Diagnostic Logging

# Activate verbose internal logging
export LOG_LEVEL=debug

# Query the service status endpoint via jq
curl http://localhost:3003/health | jq

# Inspect current active session count from the health report
curl http://localhost:3003/health | jq '.sessions'

Installation via Smithery Service

For streamlined, automated deployment directly into Claude Desktop using Smithery:

npx -y @smithery/cli install @PuroDelphi/mcpFirebird --client claude

Comprehensive Reference Materials

For in-depth guidance, please consult the supporting documentation repository sections:

Initial Steps

Prerequisites and Full Setup Guide
Exhaustive List of Configuration Parameters
Inventory of Available External Functions

Transport Protocol Details

Configuring SSE Endpoints
Setting up Streamable HTTP
Protocol Feature Comparison Matrix

Integration Tutorials

Integrating with Claude Desktop
Setting up VSCode/Copilot Interaction
Running within Docker Containers
Accessing from External Programming Languages

Advanced Operation Topics

Deep Dive into Session Lifecycle Management
Security Measures and Hardening
Techniques for Performance Optimization
Diagnostic Procedures Handbook
Detailed Account of SSE JSON Fix - Specifics on the v2.3.0-alpha.1 resolution

Use Cases

Practical Examples and Scenarios
Summary of Recent MCP Feature Adoptions

Project Sponsorship and Support

Financial Contributions

If this utility proves valuable to your operations or personal projects, please consider offering financial support to facilitate ongoing maintenance and feature enhancement.

GitHub Sponsorships: Become a Sponsor for @PuroDelphi
PayPal Gateway: Make a PayPal Contribution

Engaging Our AI Services

An alternative method to bolster development is by contracting our specialized AI agents via Asistentes Autónomos. We deploy tailored AI assistants for diverse organizational requirements, aiming to streamline workflows and boost efficiency.

Preferred Support Channel

⭐ Individuals who sponsor, donate, or contract our services are automatically entitled to priority attention regarding issue resolution, feature requests, and implementation assistance. While all user queries are addressed, financial supporters benefit from expedited response times and dedicated technical engagement.

Your backing is crucial and ensures the continued evolution and stability of the Firebird MCP Adapter!

Licensing

This software is distributed under the terms of the MIT License; view the LICENSE file for comprehensive details.

Firebird-MCP-Bridge

Author

PuroDelphi

Quick Info

Actions

Tags