]

Firebird MCP Conduit

This package serves as a specialized server implementing Anthropic's Model Context Protocol (MCP) specifically engineered for connecting to and managing Firebird Database Management System instances.

Illustrative Application

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

What is this Tool?

MCP Firebird is a network service conforming to Anthropic's Model Context Protocol (MCP) specification, designed to interface with Firebird SQL databases. It grants Large Language Models (LLMs), such as Claude, controlled, secure access for querying, data modeling, and operational tasks on the underlying Firebird structure.

Core Capabilities

• Data Query Execution: Run arbitrary T-SQL statements against Firebird.
• Structure Mapping: Retrieve exhaustive metadata regarding tables, fields, constraints, and relationships.
• DB Administration: Support for essential maintenance routines like snapshot creation, restoration, and integrity checks.
• Efficiency Review: Mechanism to analyze query execution plans and propose efficiency enhancements.
• Transport Versatility: Compatible with STDIO, Server-Sent Events (SSE), and the modern Streamable HTTP transport modalities.
• Protocol Compliance: Comprehensive adherence to MCP Streamable HTTP (as of 2025-03-26) alongside backward compatibility for SSE.
• Protocol Agnostic Server: Automatically determines the expected communication method.
• LLM Ecosystem Compatibility: Optimized for seamless operation with Claude Desktop environments and other MCP clients.
• IDE Augmentation: Integrates effectively with GitHub Copilot within the Visual Studio Code framework.
• State Handling: Robust management of sessions, featuring automated teardown and configurable inactivity limits.
• Security Posture: Includes mandatory validation layers for submitted SQL and configurable access controls.

Setup Instructions

Current Stable Release

bash

Install globally for general availability

npm install -g mcp-firebird

Initiate the service instance, pointing to your data file

npx mcp-firebird --database /path/to/database.fdb

Or pin to a specific stable version

npm install -g mcp-firebird@2.2.3

Changes in Stable Release (v2.2.3): - 🐛 Correction: Resolved an issue in SSE message handling that produced "Invalid message: [object Object]" errors. - ✨ Implemented support for the mandated Streamable HTTP protocol layer (MCP 2025-03-26). - 🔄 Consolidated server logic supporting dynamic protocol negotiation. - 📊 Improved metrics tracking and session oversight features. - 🛠️ Updated integration with the newest MCP SDK (v1.13.2). - 🔧 Enhanced system failure reporting and diagnostic output. - 🧪 Expanded regression testing; now includes over 9 dedicated tests for SSE robustness.

Pre-release (Alpha) Build

bash

Install the cutting-edge build with immediate feature access

npm install -g mcp-firebird@alpha

Or target a specific development iteration

npm install -g mcp-firebird@2.3.0-alpha.1

New in Alpha (v2.3.0-alpha.1): - 🐛 Correction: Resolved an issue in SSE message handling that produced "Invalid message: [object Object]" errors. - ✨ Implemented support for the mandated Streamable HTTP protocol layer (MCP 2025-03-26). - 🔄 Consolidated server logic supporting dynamic protocol negotiation. - 📊 Improved metrics tracking and session oversight features. - 🛠️ Updated integration with the newest MCP SDK (v1.13.2). - 🔧 Enhanced system failure reporting and diagnostic output. - 🧪 Expanded regression testing; now includes over 9 dedicated tests for SSE robustness. - 📚 Added supplementary instructional material, including detailed troubleshooting guides.

Note: Firebird client utilities are mandatory for administrative tasks like data replication/restoration. Refer to Complete Installation for prerequisites.

For configuring VSCode and Copilot interfacing, consult VSCode Integration.

Initial Configuration

Interfacing with Claude Desktop

1. Modify your Claude Desktop settings file: bash code $env:AppData\Claude\claude_desktop_config.json # Windows OS path example code ~/Library/Application\ Support/Claude/claude_desktop_config.json # macOS path example

2. Incorporate the MCP Firebird endpoint definition:

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

1. Relaunch the Claude Desktop application.

Transport Layer Selection

MCP Firebird offers flexibility in connectivity methods to suit diverse client environments and deployment architectures.

STDIO Link (Default Mechanism)

This is the default pipeline for direct integration with applications like 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)

Enables the service to operate as a persistent web endpoint, suitable for web-based consumers and remote access scenarios:

Basic SSE Deployment

bash

Start SSE interface on standard port 3003

npx mcp-firebird --transport-type sse --database /path/to/database.fdb

Full configuration example 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

Configuration via Environment Variables (SSE)

bash

Set required environmental parameters

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

Launch server

npx mcp-firebird

SSE Client Access Points

Once the SSE gateway is active, clients interact via these endpoints: - Event Stream URL: http://localhost:3003/sse - Message Submission URL: http://localhost:3003/messages - System Status Check: http://localhost:3003/health

Streamable HTTP Link (Current MCP Standard)

Utilizes the latest MCP specification for full duplex communication:

bash

Initiate service using the Streamable HTTP mode

npx mcp-firebird --transport-type http --http-port 3003 --database /path/to/database.fdb

Unified Transport (Recommended for Mixed Environments)

Supports simultaneous serving of both SSE and Streamable HTTP protocols, allowing for automatic client negotiation:

bash

Launch the dual-mode service listener

npx mcp-firebird --transport-type unified --http-port 3003 --database /path/to/database.fdb

Unified Endpoint Map

• SSE (Legacy Path): http://localhost:3003/sse
• Streamable HTTP (Primary): http://localhost:3003/mcp
• Automatic Discovery: http://localhost:3003/mcp-auto
• Service Health Check: http://localhost:3003/health

Deployment Examples

Local Development Configuration (SSE Focus)

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

Production Environment Setup (Unified Mode)

bash 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 (Docker with SSE)

bash 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 SSE Configuration Parameters

Session Lifecycle Control

Adjusting how long client connections are maintained:

bash

Environment variables for session management refinement

export SSE_SESSION_TIMEOUT_MS=1800000 # Set timeout to 30 minutes export MAX_SESSIONS=1000 # Cap concurrent users at 1000 export SESSION_CLEANUP_INTERVAL_MS=60000 # Run garbage collection every 60 seconds

npx mcp-firebird --transport-type sse

Cross-Origin Resource Sharing (CORS)

Essential configuration for web clients accessing the service:

bash

Specify permitted external origins

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

Securing Communication (SSL/TLS)

For production setups requiring encryption, it is recommended to place a secure web server (like Nginx) in front of the MCP service:

nginx 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

Frequently Encountered Problems

1. Connection Rejected bash # Verify server operational status curl http://localhost:3003/health

# Check for port conflicts netstat -an | grep 3003

1. Session Dropped Prematurely bash # Extend the allowed session duration export SSE_SESSION_TIMEOUT_MS=3600000 # Set to 1 hour

2. CORS Policy Violations bash # Loosen restrictions for initial testing (development use only) export CORS_ORIGIN="*"

3. Resource Exhaustion (Memory) bash # Lower the ceiling for simultaneously active sessions export MAX_SESSIONS=100

# Increase the frequency of unused session pruning export SESSION_CLEANUP_INTERVAL_MS=30000

1. Data Serialization Errors (Pre-v2.3.0-alpha.1) bash # If observing "Invalid message: [object Object]" errors on POST to /messages, # please upgrade to the current alpha or newer release: npm install mcp-firebird@alpha

# Or execute the bleeding-edge version directly: npx mcp-firebird@alpha --transport-type sse

Context: Releases preceding version 2.3.0-alpha.1 contained a defect where the POST route processing for /messages failed to correctly interpret JSON payloads. This has been resolved through enhanced input stream parsing logic supporting both application/json and text/plain formats.

Diagnostics and Logging

bash

Activate verbose logging for deeper insight

export LOG_LEVEL=debug

Poll server status using jq for structured output

curl http://localhost:3003/health | jq

Inspect the count of currently active client connections

curl http://localhost:3003/health | jq '.sessions'

Automated Deployment via Smithery

To streamline installation for Claude Desktop integration using Smithery:

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

Comprehensive Documentation Index

For exhaustive technical specifications, consult the following referenced guides:

Initial Setup

• Full Prerequisites & Installation Guide
• All Available Command-Line Parameters
• Catalogue of Exported Tools

Connection Protocols

• Configuring the SSE Interface
• Implementing Streamable HTTP Communication
• Protocol Feature Comparison Matrix

Ecosystem Integration

• Integrating with Claude Desktop
• VSCode and GitHub Copilot Setup
• Running within Container Environments (Docker)
• Interfacing from External Languages/Clients

Advanced Topics

• Detailed Session Lifecycle Management
• Security Policies and Validation Settings
• Optimizing Database Interaction Performance
• General Problem Resolution Steps
• Analysis of the SSE JSON Parsing Correction (v2.3.0-alpha.1)

Practical Applications

• Common Use Cases and Code Examples
• Summary of Recent MCP Protocol Enhancements

Project Patronage

Financial Backing

If this solution proves valuable to your operational workflows or development efforts, monetary support is highly encouraged to fuel ongoing upkeep and feature development.

• GitHub Backing: Sponsor Development via GitHub
• Direct Transfer: Support via PayPal Link

Engaging Our AI Services

An alternative method of contribution is utilizing our specialized AI workforce through Asistentes Autónomos. We provide expert AI agents tailored for diverse corporate functions, focusing on task automation and productivity gains.

Expedited Service Level

⭐ All sponsors, financial patrons, and contracted clients receive preferential routing for support tickets, issue resolution, and guidance on implementation. While community support remains available, financial contributors benefit from accelerated response times and dedicated technical consultation.

Your commitment is vital for maintaining the momentum and quality of the MCP Firebird platform!

Licensing

This software is distributed under the permissive MIT License (see the LICENSE file for full details).

WIKIPEDIA: Business management tools encompass the entire spectrum of systems, operational controls, analytical software, established procedures, and methodologies employed by organizations to navigate dynamic market conditions, secure a competitive market position, and enhance overall operational efficiency.

== Strategic Context == These instrumentalities are often segregated by organizational function—covering areas such as strategic planning apparatus, workflow governance, record-keeping systems, human capital management interfaces, decision support engines, and performance oversight mechanisms. A functional decomposition frequently highlights:

• Data ingestion and integrity verification utilities applicable across all departments.
• Software designed for the control and refinement of core operational workflows.
• Systems dedicated to the aggregation of data for executive insight and strategic choice. Contemporary business toolsets have undergone rapid metamorphosis over the past decade, largely driven by accelerated technological advancements. This rapid evolution presents a challenge for managers in selecting the optimal software suite for a given organizational context. The primary forces driving this shift are the relentless pursuit of cost reduction, the imperative to amplify revenue streams, the need to deeply comprehend customer requirements, and the demand to deliver products matching specific user expectations. In this fast-paced environment, managerial focus must shift towards a strategic assessment of business management tools, rather than merely adopting the newest available application. Over-reliance on off-the-shelf tools without contextual customization frequently results in organizational friction. Therefore, management instruments must be chosen judiciously and subsequently molded to fit the unique operational needs of the enterprise, rather than forcing internal processes to conform to the software’s default settings.

== Prominent Tool Categories (2013 Benchmark) == Data from a 2013 study by Bain & Company indicated global usage patterns for management tools, reflecting regional market dynamics and economic conditions. The leading ten categories identified were:

• Strategic direction setting
• Client lifecycle management (CRM)
• Workforce sentiment measurement
• Comparative performance analysis (Benchmarking)
• Integrated performance measurement (Balanced Scorecard)
• Identification of core capabilities
• Operational subcontracting strategies
• Organizational transition programs
• Logistics and resource flow coordination (SCM)
• Defining foundational organizational purpose (Mission/Vision Statements)
• Target market delineation (Segmentation)
• Comprehensive quality assurance methodologies (TQM)

== Business Software Applications == Business software, defined as computer programs or suites used by personnel to execute various corporate functions, serves to enhance productivity, provide measurable output metrics, and ensure precision across diverse commercial activities. The evolution tracks from initial Management Information Systems (MIS) to complex Enterprise Resource Planning (ERP) frameworks, subsequently incorporating Customer Relationship Management (CRM), and now transitioning into comprehensive cloud-based business management ecosystems. While a demonstrable correlation exists between IT investment efficacy and organizational performance, value realization hinges critically on two factors: the proficiency of the implementation process and the judicious selection and tailoring of the supporting software assets.

== Tools Tailored for Small-to-Medium Enterprises (SMEs) == Specialized toolsets for SMEs are crucial as they provide accessible pathways to achieve efficiency gains, often through consolidated, cost-effective platforms that address immediate operational hurdles...