DB2TOON MCP server

db2toon

A CLI tool that converts database schemas into the Toon schema definition format.

Overview

db2toon connects to a database and extracts schema information (tables, columns, types, constraints, indexes, routines, triggers, and examples), then converts it into the human-readable Toon format for database design documentation and visualization. PostgreSQL, SQLite, DuckDB, MySQL/MariaDB, CockroachDB, Microsoft SQL Server, and Oracle are supported. pg2toon remains a PostgreSQL compatibility command.

Features

triggers, routines, extensions, materialized views, packages, and other vendor-specific objects in explicit TOON sections

• Schema Extraction: Automatically extracts tables, columns, and metadata from PostgreSQL, SQLite, DuckDB, MySQL/MariaDB, CockroachDB, Microsoft SQL Server, and Oracle
• Type Normalization: Simplifies PostgreSQL types (e.g., character varying → varchar)
• Relationship Mapping: Converts foreign key constraints to inline references or multi-column references
• Comment Preservation: Includes comments where the database exposes them; SQLite does not have catalog comments
• Index Documentation: Extracts and documents database indexes
• Database Objects: Preserves supported enums, types, sequences, synonyms,

• Cross-Platform: Builds without CGO for Linux, macOS, and Windows (amd64 and arm64)
• DBML Adapter: Converts DBML files (or standard input) into the same TOON format

Installation

From Source

git clone https://github.com/kamil5b/db2toon.git
cd db2toon
CGO_ENABLED=0 go build -o output/db2toon ./cmd/db2toon
CGO_ENABLED=0 go build -o output/pg2toon ./cmd/pg2toon
CGO_ENABLED=0 go build -o output/dbml2toon ./cmd/dbml2toon

From Releases

Download pre-built binaries from the releases page for your platform.

Go package

The module also exposes a public Go API for callers that want the canonical schema model instead of invoking a command:

import (
    "context"
    "os"

    "github.com/kamil5b/db2toon"
)

func extract() error {
    db, err := db2toon.Extract(context.Background(), db2toon.Request{
        Dialect: "postgres",
        Dump:    "./schema.sql",
        Options: db2toon.Options{ExampleSample: 2},
    })
    if err != nil {
        return err
    }
    return db2toon.Encode(os.Stdout, db)
}

Set exactly one of Request.DB or Request.Dump. Dump contents are parsed offline and never executed. The public API returns *schema.Database, so callers may inspect or transform the model before encoding it.

Usage

LLM tool integration

Build and run the MCP-compatible stdio server:

CGO_ENABLED=0 go build -o output/db2toon-mcp ./cmd/db2toon-mcp
./output/db2toon-mcp

The server exposes db2toon.extractschema. Its required argument is dialect (postgres, sqlite, duckdb, mysql, mariadb, cockroachdb, mssql, sqlserver, or oracle). Provide exactly one of db or dump; optional extraction settings are supplied in an options object. Dump files are parsed offline and never executed. The tool is read-only, uses a 30-second default timeout, and limits responses to 4 MiB. Set options.timeout and options.maxoutput_bytes to lower limits when needed. Connection strings are never included in tool errors or results.

Basic Usage

./db2toon postgres -db "postgresql://user:password@localhost/dbname"

# SQLite database file
./db2toon sqlite -db ./schema.db

# Plain-text SQL dump
./db2toon postgres -dump ./schema.sql
./db2toon sqlite -dump ./schema.sql
./db2toon mysql -dump ./schema.sql
./db2toon mssql -dump ./schema.sql
./db2toon oracle -dump ./schema.sql

# DuckDB database file (requires libduckdb at runtime)
./db2toon duckdb -db ./analytics.duckdb

# Microsoft SQL Server (defaults to dbo)
./db2toon mssql -db 'sqlserver://sa:password@localhost:1433?database=app&encrypt=disable'

Shortened. The full README is on GitHub.