Metadata-Version: 2.5
Name: mcp-blueprint
Version: 0.6.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: framework,mcp,mcp-server,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
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: asyncmy>=0.2.11
Requires-Dist: cachetools>=5.3
Requires-Dist: jinja2>=3.1
Requires-Dist: mcp<3,>=2
Requires-Dist: psycopg-pool>=3.2
Requires-Dist: psycopg[binary]>=3.1
Requires-Dist: pydantic>=2.12
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)
[![PyPI version](https://img.shields.io/pypi/v/mcp-blueprint.svg)](https://pypi.org/project/mcp-blueprint/)
[![Python versions](https://img.shields.io/pypi/pyversions/mcp-blueprint.svg)](https://pypi.org/project/mcp-blueprint/)
[![Python](https://img.shields.io/github/languages/top/meob/mcp-blueprint.svg)](https://github.com/meob/mcp-blueprint)

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

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.

Supports PostgreSQL, MySQL, Oracle, ClickHouse, SQL Server, SQLite and DuckDB.

Exposes curated business tools, not a generic SQL interface.

---

## 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.
- **Production-ready** — connection pooling, caching, parameter validation and error handling; stdio and Streamable HTTP support, Docker support.
- **Configuration-driven** — build MCP servers from YAML and SQL, without writing Python code.
- **Multi-engine** — one framework for PostgreSQL, MySQL, MariaDB, Oracle, ClickHouse, SQL Server, SQLite and DuckDB, with reference DBA packs already available.
- **Safe by default** — injection-proof parameters, read-only SQL, writes only behind an explicit opt-in.
- **Built-in observability** — structured JSON logging, 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`).
- **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

MCP Blueprint ships ready-to-use packs for **every major database**:

- **six server DBA packs** — PostgreSQL, MySQL, MariaDB, Oracle, ClickHouse, SQL Server;
- **two embedded packs** — SQLite and DuckDB, for file databases that need no server;
- **a `smoke` pack** — zero-dependency, runs on an in-memory SQLite database to
  verify a deployment end to end.

The DBA packs expose the **same tools** whatever the engine, so a prompt written for one database also works against the others (see [docs/quickstart.md](docs/quickstart.md)).

But the real point is `packs/sakila`: it *synthesizes the domain* into five tools resolved by name — recommend films, check stock, review a customer's account — while business logic (standing flags, overdue status, popularity) lives in SQL. The AI Agent just asks. In a comprehensive ["model demotion" experiment](https://github.com/meob/mcp-blueprint-benchmark) this design reached **94% correct answers** across four small local models, versus 67% for a generic read-only SQL agent. That is what a well-synthesized domain looks like.

Engine selection, driver extras and pack authoring are covered in [docs/quickstart.md](docs/quickstart.md), [docs/installation.md](docs/installation.md) and [docs/pack_development.md](docs/pack_development.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
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 + smoke)
    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)
- [Smoke Test pack](docs/smoke.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 with SQL, and an MCP server is assembled from reusable packs rather than developed from scratch.

---

## License

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

<!-- mcp-name: io.github.meob/mcp-blueprint -->
