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.
• 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:

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:

docker compose up --build

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

See docs/installation.md, docs/quickstart.md and 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.

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 and 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, logging, audit and tracing and Prometheus metrics.

---

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
• Installation
• Pack development guide
• Sakila pack
• Docker
• Tutorial
• Logging, audit and tracing
• Prometheus metrics
• Best practices
• FAQ

---

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.