Metadata-Version: 2.5
Name: mcp-blueprint
Version: 0.5.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
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 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.
- **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 (see [docs/smoke.md](docs/smoke.md)).

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 agent just asks. In an internal "model demotion" experiment this design reached **98% fully-correct answers** across four small local models, versus 0.711 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)
- [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).
