Metadata-Version: 2.4
Name: mcp-blueprint
Version: 0.3.0
Summary: Build domain-oriented MCP servers from configuration files, SQL queries and metadata.
Author: MCP Blueprint Contributors
License: Apache-2.0
License-File: LICENSE
Keywords: fastmcp,framework,mcp,mysql,postgresql,sql
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: asyncmy>=0.2.11
Requires-Dist: cachetools>=5.3
Requires-Dist: jinja2>=3.1
Requires-Dist: mcp<2,>=1.27
Requires-Dist: psycopg-pool>=3.2
Requires-Dist: psycopg[binary]>=3.1
Requires-Dist: pydantic>=2.5
Requires-Dist: pyyaml>=6.0
Requires-Dist: structlog>=24.0
Provides-Extra: clickhouse
Requires-Dist: clickhouse-driver>=0.2.7; extra == 'clickhouse'
Provides-Extra: databases
Requires-Dist: clickhouse-driver>=0.2.7; extra == 'databases'
Requires-Dist: oracledb>=3.3; extra == 'databases'
Requires-Dist: pyodbc>=5.0; extra == 'databases'
Provides-Extra: dev
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: prometheus-client>=0.20; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: duckdb
Requires-Dist: duckdb>=1.0; extra == 'duckdb'
Provides-Extra: metrics
Requires-Dist: prometheus-client>=0.20; extra == 'metrics'
Provides-Extra: oracle
Requires-Dist: oracledb>=3.3; extra == 'oracle'
Provides-Extra: sqlserver
Requires-Dist: pyodbc>=5.0; extra == 'sqlserver'
Description-Content-Type: text/markdown

# MCP Blueprint

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![CI](https://github.com/meob/mcp-blueprint/actions/workflows/ci.yml/badge.svg)](https://github.com/meob/mcp-blueprint/actions/workflows/ci.yml)

**Build domain-oriented MCP servers without writing Python code for every project.**

MCP Blueprint is a lightweight framework for creating Model Context Protocol (MCP) servers from configuration files, SQL queries and metadata instead of custom application code. Instead of exposing a generic SQL interface, it exposes a curated set of business-oriented tools that are easier for LLMs to understand, safer to use and simpler to maintain.

---

## Why?

Many existing MCP database servers expose generic tools such as `execute_sql()` or `query_database()`. Although powerful, they require the LLM to understand the schema, write efficient SQL, know relationships between tables and respect business rules — a risky approach for production environments.

MCP Blueprint follows a different philosophy:

> Don't expose the database. Expose the domain.

The LLM should ask for information, not write SQL.

---

## Key features

- **Domain-oriented** — expose curated business tools, not a generic SQL interface.
- **Configuration-driven** — build MCP servers from YAML and SQL, without writing Python code for every project.
- **Multi-engine** — one framework for PostgreSQL, MySQL, MariaDB, Oracle, ClickHouse, SQL Server, SQLite and DuckDB, with reference DBA packs already available.
- **Safe by default** — read-only SQL, injection-proof parameters, writes only behind an explicit opt-in.
- **Built-in observability** — structured JSON logging, an audit trail with `trace_id`, optional Prometheus metrics.
- **Per-tool caching** — optional in-memory cache with a TTL configurable per tool (`cache.ttl`) and a server-wide default (`server.default_ttl`).
- **Production-ready** — connection pooling, caching, parameter validation and error handling; Docker and Streamable HTTP support.
- **Reusable packs** — independent, versionable tool collections.

---

## Getting started

Install the framework and run the reference server:

```bash
uv sync --all-extras --dev
uv run blueprint serve --config config --transport stdio
```

Or run it in Docker with a bundled PostgreSQL over Streamable HTTP:

```bash
docker compose up --build
```

The server is then available at `http://localhost:8000/mcp`.

See [docs/installation.md](docs/installation.md), [docs/quickstart.md](docs/quickstart.md) and [docs/docker.md](docs/docker.md) for the full walkthrough.

---

## Architecture

```
                 +----------------+
                 |    LLM Agent   |
                 +--------+-------+
                          |
                     MCP Protocol
                          |
                  +-------+-------+
                  | MCP Blueprint |
                  +-------+--------+
                          |
          +---------------+----------------+
          |               |                |
      Tool Metadata     SQL Loader     Logging
          |               |
          +-------+-------+
                  |
            Target database
```

The framework is responsible for creating MCP tools, parameter validation, database connections, logging, error handling and optional caching. Application developers only provide configuration files.

---

## Reference packs

This repository ships ready-to-use administration packs and one canonical domain pack.

The **six server DBA packs** — `packs/pg-dba` (PostgreSQL 14+), `packs/mysql-dba` (MySQL 8+), `packs/oracle-dba` (Oracle 12c+), `packs/clickhouse-dba` (ClickHouse 23+), `packs/sqlserver-dba` (SQL Server 2016+) and `packs/mariadb-dba` (MariaDB 10.4+) — expose the **same 13 tools**: three KPI dashboards (operational, performance and security, each returning `ok`/`warning`/`error` rows) plus ten detail tools (version, users, connections, sizes, largest objects, replication, tuning, slow queries, maintenance, index health).

Two **embedded packs** target file databases that need no server:

- `packs/sqlite-dba` (SQLite 3, standard library, 6 tools) — its largest-objects tool reads the `dbstat` virtual table and falls back to a pure `sqlite_schema` query when the module is unavailable (via per-tool `fallback_sql`/`fallback_on`).
- `packs/duckdb-dba` (DuckDB, optional `duckdb` extra, 4 tools).

`packs/sakila` is the recommended first example of a domain pack: a DVD rental store chatbot that recommends films, checks stock and reviews customer accounts by name, without ever writing SQL. In an internal "model demotion" experiment this verticalized design reached 98% fully-correct answers across four small local models versus 0.711 for a generic read-only SQL agent; see [docs/sakila.md](docs/sakila.md).

Engine selection happens once in config: `database.engine` picks both the adapter and the packs that load (e.g. `postgresql` loads `pg-dba` and `sakila`, `sqlite` loads `sqlite-dba`). The aliases `postgres`, `mssql` and `sql_server` are also accepted.

The four server engines are optional: install their drivers with `uv sync --extra oracle --extra clickhouse --extra sqlserver` (or `--extra databases` for all three); MariaDB reuses the MySQL driver and needs no extra; DuckDB needs `--extra duckdb`; SQLite needs nothing. Bring the server databases up with `docker compose -f docker-compose.databases.yaml up -d`.

The packs do not expose SQL execution — only curated DBA operations, usable with least-privilege monitoring users (e.g. `pg_monitor` on PostgreSQL).

`template/pack` is the minimal skeleton for authoring a new pack, and `examples/customers` is a small customer pack; see [docs/pack_development.md](docs/pack_development.md) and [template/README.md](template/README.md).

---

## Tool design

An MCP server should look like a REST API, not like a SQL console: each tool represents a meaningful operation and hides all SQL complexity.

```
# Instead of
execute_sql(...)

# expose
get_customer()
search_customer()
get_database_sizes()
get_performance_kpis()
```

Beyond the tool API, MCP Blueprint owns the operational concerns — SQL safety (read-only by default, explicit opt-in for writes, injection-proof parameters), structured logging and telemetry — so pack authors never have to implement them; see the [security model](docs/pack_development.md#security-model), [logging, audit and tracing](docs/logging.md) and [Prometheus metrics](docs/metrics.md).

---

## Project structure

```
mcp-blueprint/
    blueprint/     # the framework
    config/        # server, database, logging, metrics YAML
    packs/         # the reference packs (8 DBA + sakila)
    examples/      # small example packs and client configs
    template/      # skeleton for authoring new packs
    docs/
    tests/
```

Each pack is self-contained: tools, SQL and metadata only, with the engine declared once in `pack.yaml`. No Python code is required to create a new tool.

---

## Documentation

- [Quick start](docs/quickstart.md)
- [Installation](docs/installation.md)
- [Pack development guide](docs/pack_development.md)
- [Sakila pack](docs/sakila.md)
- [Docker](docs/docker.md)
- [Tutorial](docs/tutorial.md)
- [Logging, audit and tracing](docs/logging.md)
- [Prometheus metrics](docs/metrics.md)
- [Best practices](docs/best_practices.md)
- [FAQ](docs/faq.md)

---

## Long-term vision

MCP Blueprint aims to become for MCP what REST frameworks became for HTTP APIs: developers describe their domain, and an MCP server is assembled from reusable packs rather than developed from scratch.

---

## License

Released under the [Apache License 2.0](LICENSE).
