Synopsis

The Universal Data Access Mediator establishes a standardized conduit for cognitive entities (AI models) to engage with multiple relational database systems concurrently. Architected upon the foundational [FreePeak/cortex] framework, this service empowers AI assistants to issue arbitrary SQL instructions, orchestrate data manipulation sequences (transactions), introspect structural metadata, and generate performance metrics across various backend database technologies, all through a singular, abstracted interface.

Fundamental Principles

Parallel Backend Connectivity

In contrast to single-instance database adapters, this mediator maintains active associations with numerous distinct data stores simultaneously:

{ "connections": [ { "id": "mysql1", "type": "mysql", "host": "localhost", "port": 3306, "name": "db1", "user": "user1", "password": "password1" }, { "id": "postgres1", "type": "postgres", "host": "localhost", "port": 5432, "name": "db2", "user": "user2", "password": "password2" } ] }

Contextual Function Generation

For every established data source connection, the server dynamically fabricates a set of highly specific operational functions:

go // For the connection designated 'mysql1', the following functions are surfaced: query_mysql1 // For retrieval operations (SELECT) execute_mysql1 // For data definition/manipulation (DML/DDL) transaction_mysql1 // For managing atomic operation blocks schema_mysql1 // For metadata inspection performance_mysql1 // For runtime query analysis

Architectural Design

The platform adheres strictly to Clean Architecture methodologies, segmenting responsibilities into distinct operational layers:

1. Domain Layer: Houses the fundamental business rules and abstract interface definitions.
2. Repository Layer: Contains the concrete implementations for persistent data interaction.
3. Use Case Layer: Encapsulates the orchestration logic of the application.
4. Delivery Layer: Manages external communication protocols (i.e., the MCP tool definitions).

Capabilities

• Concurrent Multi-Source Access: Ability to maintain live connections to disparate MySQL and PostgreSQL instances.
• Automated Tool Provisioning: Instantaneous creation of context-aware functions based on the active connection pool.
• Modular Structure: Implementation utilizing Clean Architecture ensuring high separation of concerns.
• Agent SDK Compliant: Seamless integration compatibility with established OpenAI Agents SDK toolsets.
• Dynamic Data Operations: Support for arbitrary query execution, data modification, transaction control, schema discovery, and performance profiling.
• Standardized Interaction Model: Uniform method signatures applied across all connected database vendors.
• Connection Abstraction: Simplified provisioning and management of multiple backend endpoints.

Supported Backends

Deployment Schemas

The mediator supports several deployment modalities to fit diverse operational environments:

Docker Containerization

bash

Obtain the latest binary image

docker pull freepeak/db-mcp-server:latest

Execute, mapping configuration volume and setting transport mode

docker run -p 9092:9092 \ -v $(pwd)/config.json:/app/my-config.json \ -e TRANSPORT_MODE=sse \ -e CONFIG_PATH=/app/my-config.json \ freepeak/db-mcp-server

Note: Ensure the configuration file is mapped to /app/my-config.json as the container binary defaults to checking /app/config.json.

Inter-Process Communication (STDIO Mode)

bash

Launch server using STDIO for IDE integration

./bin/server -t stdio -c config.json

For integration within Cursor IDE, configure .cursor/mcp.json as follows:

{ "mcpServers": { "stdio-db-mcp-server": { "command": "/path/to/db-mcp-server/server", "args": ["-t", "stdio", "-c", "/path/to/config.json"] } } }

Server-Sent Events (SSE Protocol)

bash

Default endpoint binding (localhost:9092)

./bin/server -t sse -c config.json

Override networking parameters

./bin/server -t sse -host 0.0.0.0 -port 8080 -c config.json

Client connection listener address: http://localhost:9092/sse

From Source Compilation

bash

Obtain source code

git clone https://github.com/FreePeak/db-mcp-server.git cd db-mcp-server

Compile executable

make build

Execute via SSE transport, referencing local config

./bin/server -t sse -c config.json

Configuration Guide

Connection Definition File (config.json)

Define your connection parameters within the configuration structure:

{ "connections": [ { "id": "mysql1", "type": "mysql", "host": "mysql1", "port": 3306, "name": "db1", "user": "user1", "password": "password1", "query_timeout": 60, "max_open_conns": 20, "max_idle_conns": 5, "conn_max_lifetime_seconds": 300, "conn_max_idle_time_seconds": 60 }, { "id": "postgres1", "type": "postgres", "host": "postgres1", "port": 5432, "name": "db1", "user": "user1", "password": "password1" } ] }

Runtime Parameter Overrides

bash

Standard execution template

./bin/server -t -c

Customizing SSE network interface

./bin/server -t sse -host -port -c

Injecting configuration inline via string argument

./bin/server -t stdio -db-config '{"connections":[...]}'

Utilizing environment variable for configuration load

export DB_CONFIG='{"connections":[...]}' ./bin/server -t stdio

Exposed Functions

For every logical database source specified, the mediator exposes these functional interfaces:

Data Operation Tools

Metadata Inspection Tools

Performance Profiling Tools

TimescaleDB Extensions

When interfacing with TimescaleDB-enabled PostgreSQL instances, these specialized functions become accessible:

Refer to TIMESCALEDB_TOOLS.md for exhaustive documentation on these time-series specific operations.

Usage Samples

Interrogating Disparate Stores

sql -- Access data in the MySQL source query_mysql1("SELECT user_id, username FROM users WHERE status = 'active' LIMIT 10")

-- Access data in the PostgreSQL source within the same context query_postgres1("SELECT item_name, inventory_count FROM inventory WHERE price > $1", 100.00)

Transaction Orchestration

sql -- Initiate an atomic sequence on MySQL transaction_mysql1("BEGIN")

-- Sequence of modifications execute_mysql1("INSERT INTO audit_log (action, details) VALUES ('OrderCreated', 'ID: 9001')") execute_mysql1("UPDATE stock SET quantity = quantity - 1 WHERE sku = 'XYZ-123'")

-- Finalize the sequence transaction_mysql1("COMMIT") -- Alternatively, discard changes: transaction_mysql1("ROLLBACK")

Schema Discovery

sql -- Enumerate all defined relations (tables/views) in the MySQL instance schema_mysql1("relations")

-- Fetch structural details for a specific relation schema_mysql1("attributes", "customer_profiles")

-- Inspect relational integrity constraints schema_mysql1("integrity_rules", "transactions")

Issue Resolution

Frequent Problems

• Connection Refusal: Validate network paths and confirm database accessibility and credential accuracy.
• Authorization Failures: Ensure the configured database principal possesses the necessary rights for requested operations.
• Latency Issues: Adjust the query_timeout setting within your connection definitions to allow for longer running operations.

Diagnostic Logging

Activate high-verbosity logging output to aid in diagnosing complex interactions:

bash ./bin/server -t sse -c config.json -v

Community Involvement

We strongly encourage external contributions to enhance the DB MCP Server project! To participate:

1. Fork the repository source.
2. Establish a new development branch (git checkout -b feature/new-enhancement).
3. Commit your modifications (git commit -m 'feat: implement requested feature X').
4. Push your branch upstream (git push origin feature/new-enhancement).
5. Submit a formal Pull Request for review.

Please consult our CONTRIBUTING.md document for comprehensive contribution policies and standards.

Legal Notice

This software is distributed under the terms of the MIT License - refer to the LICENSE file for the complete legal text.

WIKIPEDIA: Cloud computing is "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand," as formally defined by ISO. This abstract concept is widely known as "the cloud".

== Characteristics == In the year 2011, the U.S. National Institute of Standards and Technology (NIST) formalized five "essential characteristics" defining cloud systems. These stipulations, as per NIST documentation, include:

On-demand self-service: "A consumer can unilaterally provision computing capabilities, such as server time and network storage, as needed automatically without requiring human interaction with each service provider." Broad network access: "Capabilities are available over the network and accessed through standard mechanisms that promote use by heterogeneous thin or thick client platforms (e.g., mobile phones, tablets, laptops, and workstations)." Resource pooling: " The provider's computing resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand." Rapid elasticity: "Capabilities can be elastically provisioned and released, in some cases automatically, to scale rapidly outward and inward commensurate with demand. To the consumer, the capabilities available for provisioning often appear unlimited and can be appropriated in any quantity at any time." Measured service: "Cloud systems automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., storage, processing, bandwidth, and active user accounts). Resource usage can be monitored, controlled, and reported, providing transparency for both the provider and consumer of the utilized service. By the year 2023, the International Organization for Standardization (ISO) had subsequently refined and extended this definitive list.

== History ==

The lineage of cloud computing traces back to the 1960s, marked by the early popularization of time-sharing concepts via remote job entry (RJE) mechanisms. During this period, the dominant operational model was the "data center" paradigm, where users submitted batch jobs to dedicated operators for execution on large mainframe systems. This era was characterized by intense investigation and practical experimentation focused on democratizing access to high-capacity computational resources through time-sharing, thereby optimizing the underlying infrastructure, software platforms, and end-user application efficiency. The actual adoption of the "cloud" symbolic representation for abstracted, virtualized services originated in 1994. It was employed by General Magic to describe the abstract sphere of "locations" accessible to mobile agents operating within their Telescript framework. This metaphor is attributed to David Hoffman, a communications specialist at General Magic, who based it on its long-established usage within telecommunications and network diagrams. The phrase "cloud computing" gained broader public currency in 1996 following a strategic business plan drafted by Compaq Computer Corporation outlining their vision for future computation and internet services. The company's primary objective was to supercharge th