sql-mini-mcp 0.9.1__py3-none-any.whl

sql_mini_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Minimal, PII-safe MCP server for relational databases."""
+
+__version__ = "0.9.1"

sql_mini_mcp/__main__.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from sql_mini_mcp.config import load_config
+from sql_mini_mcp.errors import DomainError
+from sql_mini_mcp.mcp_server import create_server
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run the sql-mini-mcp stdio server.")
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=os.environ.get("SQL_MINI_MCP_CONFIG", "sql-mini-mcp.yaml"),
+        help="YAML configuration path (default: SQL_MINI_MCP_CONFIG or sql-mini-mcp.yaml)",
+    )
+    parser.add_argument(
+        "--check-config",
+        action="store_true",
+        help="Validate configuration and secrets without connecting to databases.",
+    )
+    return parser
+
+
+def main() -> None:
+    args = _parser().parse_args()
+    try:
+        config = load_config(args.config)
+    except DomainError as exc:
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(2) from None
+    if args.check_config:
+        print(f"Configuration valid: {len(config.servers)} server alias(es).")
+        return
+    create_server(config).run("stdio")
+
+
+if __name__ == "__main__":
+    main()

sql_mini_mcp/config.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import os
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Literal
+from urllib.parse import quote
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, ValidationError, model_validator
+from sqlalchemy.engine import make_url
+
+from sql_mini_mcp.errors import DomainError, ErrorCode
+
+_ENV_PATTERN = re.compile(r"\$\{([A-Z_][A-Z0-9_]*)\}")
+_FULL_ENV_PATTERN = re.compile(r"^\$\{([A-Z_][A-Z0-9_]*)\}$")
+
+
+class RuntimeConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    max_concurrent_db_operations: int = Field(default=8, ge=1, le=128)
+    engine_cache_size: int = Field(default=32, ge=1, le=1024)
+    pool_size: int = Field(default=2, ge=1, le=32)
+    max_overflow: int = Field(default=2, ge=0, le=64)
+    pool_timeout_seconds: int = Field(default=10, ge=1, le=300)
+    statement_timeout_seconds: int = Field(default=30, ge=1, le=3600)
+    max_definition_chars: int = Field(default=262_144, ge=1024, le=10_000_000)
+    default_max_rows: int = Field(default=200, ge=1, le=100_000)
+    hard_max_rows: int = Field(default=1000, ge=1, le=100_000)
+    max_sql_chars: int = Field(default=65_536, ge=256, le=1_000_000)
+    max_ast_nodes: int = Field(default=2000, ge=10, le=100_000)
+    max_joins: int = Field(default=8, ge=0, le=100)
+    max_in_list_items: int = Field(default=500, ge=1, le=100_000)
+
+    @model_validator(mode="after")
+    def validate_row_limits(self) -> RuntimeConfig:
+        if self.default_max_rows > self.hard_max_rows:
+            raise ValueError("default_max_rows cannot exceed hard_max_rows")
+        return self
+
+
+class PiiRule(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    database: str = Field(min_length=1)
+    schema_: str | None = Field(default=None, alias="schema")
+    table: str = Field(min_length=1)
+    columns: list[str] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def validate_wildcards(self) -> PiiRule:
+        if "*" in self.table or (self.schema_ and "*" in self.schema_):
+            raise ValueError("wildcards are allowed only in pii rule database")
+        if self.database != "*" and "*" in self.database:
+            raise ValueError("database must be an exact name or '*'")
+        folded = [column.casefold() for column in self.columns]
+        if len(folded) != len(set(folded)):
+            raise ValueError("pii rule columns must be unique")
+        return self
+
+
+class PiiConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    rules: list[PiiRule] = Field(min_length=1)
+
+
+class ServerConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    engine: Literal["sqlserver"]
+    access_level: Literal["metadata", "pii_safe"] = "metadata"
+    connection_url: SecretStr
+    pii_key_env: str | None = Field(default=None, pattern=r"^[A-Z_][A-Z0-9_]*$")
+    pii: PiiConfig | None = None
+    pii_key: SecretStr | None = Field(default=None, exclude=True)
+
+    @model_validator(mode="after")
+    def validate_security_shape(self) -> ServerConfig:
+        if self.access_level == "pii_safe":
+            if not self.pii_key_env or self.pii is None:
+                raise ValueError("pii_safe servers require pii_key_env and pii rules")
+        elif self.pii_key_env is not None or self.pii is not None:
+            raise ValueError("metadata servers cannot configure pii_key_env or pii rules")
+
+        driver = make_url(self.connection_url.get_secret_value()).drivername
+        expected = "mssql+pyodbc"
+        if driver != expected:
+            raise ValueError(f"engine {self.engine!r} requires SQLAlchemy dialect {expected!r}")
+        return self
+
+    def key_bytes(self) -> bytes | None:
+        if self.pii_key is None:
+            return None
+        return base64.b64decode(self.pii_key.get_secret_value(), validate=True)
+
+
+class AppConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    version: Literal[1]
+    runtime: RuntimeConfig = Field(default_factory=RuntimeConfig)
+    servers: dict[str, ServerConfig] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def validate_aliases_and_keys(self) -> AppConfig:
+        seen_keys: dict[bytes, str] = {}
+        for alias, server in self.servers.items():
+            if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", alias):
+                raise ValueError(f"invalid server alias {alias!r}")
+            key = server.key_bytes()
+            if key is None:
+                continue
+            if len(key) != 32:
+                raise ValueError(f"PII key for server {alias!r} must decode to 32 bytes")
+            if previous := seen_keys.get(key):
+                raise ValueError(
+                    f"PII keys must be unique per server alias; {alias!r} duplicates {previous!r}"
+                )
+            seen_keys[key] = alias
+        return self
+
+
+def _expand_connection_url(template: str, environ: Mapping[str, str]) -> str:
+    full_match = _FULL_ENV_PATTERN.fullmatch(template)
+    if full_match:
+        name = full_match.group(1)
+        if name not in environ:
+            raise ValueError(f"missing environment variable {name}")
+        return environ[name]
+
+    def replace(match: re.Match[str]) -> str:
+        name = match.group(1)
+        if name not in environ:
+            raise ValueError(f"missing environment variable {name}")
+        return quote(environ[name], safe="")
+
+    expanded = _ENV_PATTERN.sub(replace, template)
+    if "${" in expanded:
+        raise ValueError("invalid environment placeholder in connection_url")
+    return expanded
+
+
+def _validation_summary(error: ValidationError) -> str:
+    issues: list[str] = []
+    for issue in error.errors(include_url=False, include_context=False, include_input=False):
+        location = ".".join(str(part) for part in issue["loc"])
+        issues.append(f"{location}: {issue['msg']}" if location else str(issue["msg"]))
+    return "; ".join(issues)
+
+
+def load_config(path: str | Path, environ: Mapping[str, str] | None = None) -> AppConfig:
+    env = os.environ if environ is None else environ
+    try:
+        raw = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+        if not isinstance(raw, dict):
+            raise ValueError("configuration root must be a mapping")
+        servers = raw.get("servers")
+        if not isinstance(servers, dict):
+            raise ValueError("servers must be a mapping")
+        for alias, value in servers.items():
+            if not isinstance(value, dict):
+                raise ValueError(f"server {alias!r} must be a mapping")
+            url = value.get("connection_url")
+            if not isinstance(url, str):
+                raise ValueError(f"server {alias!r} requires connection_url")
+            value["connection_url"] = _expand_connection_url(url, env)
+            key_env = value.get("pii_key_env")
+            if key_env is not None:
+                if not isinstance(key_env, str) or key_env not in env:
+                    raise ValueError(f"missing PII key environment variable {key_env!r}")
+                try:
+                    decoded = base64.b64decode(env[key_env], validate=True)
+                except (binascii.Error, ValueError) as exc:
+                    raise ValueError(f"PII key for server {alias!r} is not valid base64") from exc
+                if len(decoded) != 32:
+                    raise ValueError(f"PII key for server {alias!r} must decode to 32 bytes")
+                value["pii_key"] = env[key_env]
+        return AppConfig.model_validate(raw)
+    except DomainError:
+        raise
+    except ValidationError as exc:
+        raise DomainError(
+            ErrorCode.CONFIG_ERROR,
+            f"Invalid configuration: {_validation_summary(exc)}",
+        ) from exc
+    except (OSError, yaml.YAMLError) as exc:
+        raise DomainError(ErrorCode.CONFIG_ERROR, "Invalid configuration file.") from exc
+    except ValueError as exc:
+        raise DomainError(ErrorCode.CONFIG_ERROR, f"Invalid configuration: {exc}") from exc

sql_mini_mcp/db/__init__.py

@@ -0,0 +1 @@
+"""Database integration layer."""

sql_mini_mcp/db/extras.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from sqlalchemy import Connection
+
+from sql_mini_mcp.models import StoredProcedureDefinition, StoredProcedureSummary
+
+
+class DatabaseExtras(Protocol):
+    def list_databases(self, connection: Connection) -> list[str]: ...
+
+    def list_stored_procedures(
+        self, connection: Connection, database: str
+    ) -> list[StoredProcedureSummary]: ...
+
+    def get_stored_procedure(
+        self,
+        connection: Connection,
+        database: str,
+        schema: str | None,
+        name: str,
+    ) -> StoredProcedureDefinition | None: ...
+
+
+def extras_for(engine: str) -> DatabaseExtras:
+    if engine == "sqlserver":
+        from sql_mini_mcp.db.sqlserver import SqlServerExtras
+
+        return SqlServerExtras()
+    raise ValueError(f"unsupported engine {engine!r}")

sql_mini_mcp/db/reflection.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from sqlalchemy import Connection, inspect
+
+from sql_mini_mcp.models import (
+    ColumnDefinition,
+    ForeignKeyDefinition,
+    IndexDefinition,
+    PrimaryKeyDefinition,
+    TableDefinition,
+    TableSummary,
+    UniqueConstraintDefinition,
+)
+
+_SQLSERVER_SYSTEM_SCHEMAS = {
+    "db_accessadmin",
+    "db_backupoperator",
+    "db_datareader",
+    "db_datawriter",
+    "db_ddladmin",
+    "db_denydatareader",
+    "db_denydatawriter",
+    "db_owner",
+    "db_securityadmin",
+    "guest",
+    "information_schema",
+    "sys",
+}
+
+
+def list_tables(connection: Connection) -> list[TableSummary]:
+    inspector = inspect(connection)
+    tables: list[TableSummary] = []
+    for schema in inspector.get_schema_names():
+        if schema.casefold() in _SQLSERVER_SYSTEM_SCHEMAS:
+            continue
+        tables.extend(
+            TableSummary(schema_=schema, name=name)
+            for name in inspector.get_table_names(schema=schema)
+        )
+    return tables
+
+
+def _dict_or_none(value: Any) -> dict[str, Any] | None:
+    return dict(value) if isinstance(value, dict) else None
+
+
+def _normalize_columns(
+    connection: Connection, columns: Iterable[Mapping[str, Any]]
+) -> list[ColumnDefinition]:
+    result: list[ColumnDefinition] = []
+    for column in columns:
+        type_ = column["type"]
+        native_type = str(type_.compile(dialect=connection.dialect))
+        result.append(
+            ColumnDefinition(
+                name=str(column["name"]),
+                native_type=native_type,
+                nullable=bool(column.get("nullable", True)),
+                length=getattr(type_, "length", None),
+                precision=getattr(type_, "precision", None),
+                scale=getattr(type_, "scale", None),
+                autoincrement=column.get("autoincrement"),
+                identity=_dict_or_none(column.get("identity")),
+                computed=_dict_or_none(column.get("computed")),
+                default=None if column.get("default") is None else str(column["default"]),
+            )
+        )
+    return result
+
+
+def get_table_definition(
+    connection: Connection,
+    schema: str | None,
+    table: str,
+) -> TableDefinition:
+    inspector = inspect(connection)
+    primary_key = inspector.get_pk_constraint(table, schema=schema)
+    foreign_keys = inspector.get_foreign_keys(table, schema=schema)
+    indexes = inspector.get_indexes(table, schema=schema)
+    try:
+        unique_constraints = inspector.get_unique_constraints(table, schema=schema)
+    except NotImplementedError:
+        unique_constraints = [
+            {"name": item.get("name"), "column_names": item.get("column_names")}
+            for item in indexes
+            if item.get("unique")
+        ]
+    return TableDefinition(
+        schema_=schema,
+        name=table,
+        columns=_normalize_columns(connection, inspector.get_columns(table, schema=schema)),
+        primary_key=PrimaryKeyDefinition(
+            name=primary_key.get("name"),
+            columns=[str(name) for name in primary_key.get("constrained_columns") or []],
+        ),
+        foreign_keys=[
+            ForeignKeyDefinition(
+                name=item.get("name"),
+                columns=[str(name) for name in item.get("constrained_columns") or []],
+                referred_schema=item.get("referred_schema"),
+                referred_table=str(item["referred_table"]),
+                referred_columns=[str(name) for name in item.get("referred_columns") or []],
+                options=dict(item.get("options") or {}),
+            )
+            for item in foreign_keys
+        ],
+        unique_constraints=[
+            UniqueConstraintDefinition(
+                name=None if item.get("name") is None else str(item["name"]),
+                columns=[str(name) for name in item.get("column_names") or []],
+            )
+            for item in unique_constraints
+        ],
+        indexes=[
+            IndexDefinition(
+                name=item.get("name"),
+                columns=list(item.get("column_names") or []),
+                unique=bool(item.get("unique", False)),
+                expressions=[str(value) for value in item.get("expressions") or []],
+            )
+            for item in indexes
+        ],
+    )

sql_mini_mcp/db/registry.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+from collections.abc import Callable
+from threading import RLock
+from typing import Any, TypeVar
+
+import anyio
+from sqlalchemy import Engine, create_engine, event
+
+from sql_mini_mcp.config import AppConfig
+from sql_mini_mcp.errors import DomainError, ErrorCode
+
+T = TypeVar("T")
+
+
+class EngineRegistry:
+    """Thread-safe lazy LRU of SQLAlchemy engines."""
+
+    def __init__(self, config: AppConfig) -> None:
+        self._config = config
+        self._engines: OrderedDict[tuple[str, str | None], Engine] = OrderedDict()
+        self._lock = RLock()
+        self._limiter = anyio.CapacityLimiter(config.runtime.max_concurrent_db_operations)
+
+    def _create_engine(self, alias: str, database: str | None) -> Engine:
+        server = self._config.servers[alias]
+        url = server.connection_url.get_secret_value()
+        if database is not None:
+            from sqlalchemy.engine import make_url
+
+            url = make_url(url).set(database=database)
+        engine = create_engine(
+            url,
+            pool_size=self._config.runtime.pool_size,
+            max_overflow=self._config.runtime.max_overflow,
+            pool_timeout=self._config.runtime.pool_timeout_seconds,
+            pool_pre_ping=True,
+            pool_use_lifo=True,
+        )
+        timeout = self._config.runtime.statement_timeout_seconds
+
+        @event.listens_for(engine, "connect")
+        def set_connection_timeout(dbapi_connection: Any, _record: Any) -> None:
+            if hasattr(dbapi_connection, "timeout"):
+                dbapi_connection.timeout = timeout
+
+        @event.listens_for(engine, "before_cursor_execute")
+        def set_statement_timeout(
+            _connection: Any,
+            cursor: Any,
+            _statement: str,
+            _parameters: Any,
+            _context: Any,
+            _executemany: bool,
+        ) -> None:
+            if hasattr(cursor, "timeout"):
+                cursor.timeout = timeout
+
+        return engine
+
+    def get(self, alias: str, database: str | None = None) -> Engine:
+        if alias not in self._config.servers:
+            raise DomainError(ErrorCode.UNKNOWN_SERVER, f"Unknown configured server {alias!r}.")
+        key = (alias, database)
+        evicted: Engine | None = None
+        with self._lock:
+            if engine := self._engines.get(key):
+                self._engines.move_to_end(key)
+                return engine
+            engine = self._create_engine(alias, database)
+            self._engines[key] = engine
+            if len(self._engines) > self._config.runtime.engine_cache_size:
+                _, evicted = self._engines.popitem(last=False)
+        if evicted is not None:
+            evicted.dispose()
+        return engine
+
+    async def run(
+        self,
+        alias: str,
+        database: str | None,
+        operation: Callable[[Engine], T],
+    ) -> T:
+        engine = self.get(alias, database)
+        return await anyio.to_thread.run_sync(operation, engine, limiter=self._limiter)
+
+    def dispose(self) -> None:
+        with self._lock:
+            engines = list(self._engines.values())
+            self._engines.clear()
+        for engine in engines:
+            engine.dispose()
+
+    @property
+    def cached_engine_count(self) -> int:
+        with self._lock:
+            return len(self._engines)

sql_mini_mcp/db/sqlserver.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from sqlalchemy import Connection, text
+
+from sql_mini_mcp.db.extras import DatabaseExtras
+from sql_mini_mcp.models import StoredProcedureDefinition, StoredProcedureSummary
+
+
+class SqlServerExtras(DatabaseExtras):
+    def list_databases(self, connection: Connection) -> list[str]:
+        rows = connection.execute(
+            text(
+                "SELECT name FROM sys.databases "
+                "WHERE state = 0 AND HAS_DBACCESS(name) = 1 ORDER BY name"
+            )
+        )
+        return [str(row.name) for row in rows]
+
+    def list_stored_procedures(
+        self, connection: Connection, database: str
+    ) -> list[StoredProcedureSummary]:
+        del database
+        rows = connection.execute(
+            text(
+                "SELECT s.name AS schema_name, p.name AS procedure_name "
+                "FROM sys.procedures AS p "
+                "JOIN sys.schemas AS s ON s.schema_id = p.schema_id "
+                "WHERE p.is_ms_shipped = 0 "
+                "ORDER BY s.name, p.name"
+            )
+        )
+        return [
+            StoredProcedureSummary(schema_=str(row.schema_name), name=str(row.procedure_name))
+            for row in rows
+        ]
+
+    def get_stored_procedure(
+        self,
+        connection: Connection,
+        database: str,
+        schema: str | None,
+        name: str,
+    ) -> StoredProcedureDefinition | None:
+        del database
+        if schema is None:
+            return None
+        row = connection.execute(
+            text(
+                "SELECT s.name AS schema_name, p.name AS procedure_name, "
+                "OBJECT_DEFINITION(p.object_id) AS definition "
+                "FROM sys.procedures AS p "
+                "JOIN sys.schemas AS s ON s.schema_id = p.schema_id "
+                "WHERE s.name = :schema AND p.name = :name AND p.is_ms_shipped = 0"
+            ),
+            {"schema": schema, "name": name},
+        ).first()
+        if row is None:
+            return None
+        definition = None if row.definition is None else str(row.definition)
+        return StoredProcedureDefinition(
+            schema_=str(row.schema_name),
+            name=str(row.procedure_name),
+            definition=definition,
+            definition_available=definition is not None,
+        )

sql_mini_mcp/errors.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from uuid import uuid4
+
+
+class ErrorCode(StrEnum):
+    INVALID_ARGUMENT = "INVALID_ARGUMENT"
+    UNKNOWN_SERVER = "UNKNOWN_SERVER"
+    NOT_FOUND = "NOT_FOUND"
+    AMBIGUOUS_OBJECT = "AMBIGUOUS_OBJECT"
+    ACCESS_LEVEL_DENIED = "ACCESS_LEVEL_DENIED"
+    CONFIG_ERROR = "CONFIG_ERROR"
+    CONNECTION_FAILED = "CONNECTION_FAILED"
+    ACCESS_DENIED = "ACCESS_DENIED"
+    TIMEOUT = "TIMEOUT"
+    METADATA_UNAVAILABLE = "METADATA_UNAVAILABLE"
+    DEFINITION_TOO_LARGE = "DEFINITION_TOO_LARGE"
+    QUERY_REJECTED = "QUERY_REJECTED"
+    INVALID_PII_TOKEN = "INVALID_PII_TOKEN"
+    RESULT_LIMIT_EXCEEDED = "RESULT_LIMIT_EXCEEDED"
+    DATABASE_ERROR = "DATABASE_ERROR"
+
+
+@dataclass(slots=True)
+class DomainError(Exception):
+    code: ErrorCode
+    public_message: str
+    hint: str | None = None
+    retryable: bool = False
+    correlation_id: str | None = None
+
+    def __str__(self) -> str:
+        parts = [f"[{self.code}] {self.public_message}"]
+        if self.hint:
+            parts.append(f"Hint: {self.hint}")
+        if self.correlation_id:
+            parts.append(f"Reference: {self.correlation_id}")
+        return " ".join(parts)
+
+    @classmethod
+    def unexpected(cls) -> DomainError:
+        return cls(
+            ErrorCode.DATABASE_ERROR,
+            "The database operation failed unexpectedly.",
+            retryable=False,
+            correlation_id=uuid4().hex,
+        )

sql_mini_mcp/mcp_server.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+from mcp.server.mcpserver import Context, MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp_types import ToolAnnotations
+
+from sql_mini_mcp.config import AppConfig
+from sql_mini_mcp.db.registry import EngineRegistry
+from sql_mini_mcp.errors import DomainError
+from sql_mini_mcp.models import (
+    DatabaseList,
+    ServerList,
+    StoredProcedureDefinition,
+    StoredProcedureList,
+    TableDefinition,
+    TableList,
+)
+from sql_mini_mcp.service import DatabaseService
+
+READ_ONLY = ToolAnnotations(read_only_hint=True, open_world_hint=False)
+
+
+@dataclass(slots=True)
+class AppContext:
+    service: DatabaseService
+    registry: EngineRegistry
+
+
+async def _domain_call[T](operation: Callable[[], Awaitable[T]]) -> T:
+    try:
+        return await operation()
+    except DomainError as exc:
+        raise ToolError(str(exc)) from exc
+
+
+def create_server(config: AppConfig) -> MCPServer[AppContext]:
+    @asynccontextmanager
+    async def lifespan(_server: MCPServer[AppContext]) -> AsyncIterator[AppContext]:
+        registry = EngineRegistry(config)
+        try:
+            yield AppContext(service=DatabaseService(config, registry), registry=registry)
+        finally:
+            registry.dispose()
+
+    server: MCPServer[AppContext] = MCPServer(
+        "sql-mini-mcp",
+        description="Minimal, read-only, PII-safe SQL database navigation.",
+        version="0.9.1",
+        lifespan=lifespan,
+    )
+
+    @server.tool(annotations=READ_ONLY)
+    async def list_servers(ctx: Context[AppContext]) -> ServerList:
+        """List explicitly configured database server aliases."""
+        return ctx.request_context.lifespan_context.service.list_servers()
+
+    @server.tool(annotations=READ_ONLY)
+    async def list_databases(
+        server: str,
+        ctx: Context[AppContext],
+        name_contains: str | None = None,
+    ) -> DatabaseList:
+        """List databases visible to the configured credentials."""
+        service = ctx.request_context.lifespan_context.service
+        return await _domain_call(lambda: service.list_databases(server, name_contains))
+
+    @server.tool(annotations=READ_ONLY)
+    async def list_tables(
+        server: str,
+        database: str,
+        ctx: Context[AppContext],
+        schema: str | None = None,
+        name_contains: str | None = None,
+    ) -> TableList:
+        """List base tables, optionally filtering by schema and a name substring."""
+        service = ctx.request_context.lifespan_context.service
+        return await _domain_call(
+            lambda: service.list_tables(server, database, schema, name_contains)
+        )
+
+    @server.tool(annotations=READ_ONLY)
+    async def get_table_definition(
+        server: str,
+        database: str,
+        table: str,
+        ctx: Context[AppContext],
+        schema: str | None = None,
+    ) -> TableDefinition:
+        """Get columns, keys, constraints, and indexes for one table."""
+        service = ctx.request_context.lifespan_context.service
+        return await _domain_call(
+            lambda: service.get_table_definition(server, database, table, schema)
+        )
+
+    @server.tool(annotations=READ_ONLY)
+    async def list_stored_procedures(
+        server: str,
+        database: str,
+        ctx: Context[AppContext],
+        schema: str | None = None,
+        name_contains: str | None = None,
+    ) -> StoredProcedureList:
+        """List stored procedures without expanding their definitions."""
+        service = ctx.request_context.lifespan_context.service
+        return await _domain_call(
+            lambda: service.list_stored_procedures(server, database, schema, name_contains)
+        )
+
+    @server.tool(annotations=READ_ONLY)
+    async def get_stored_procedure(
+        server: str,
+        database: str,
+        name: str,
+        ctx: Context[AppContext],
+        schema: str | None = None,
+    ) -> StoredProcedureDefinition:
+        """Get the original definition of one stored procedure when visible."""
+        service = ctx.request_context.lifespan_context.service
+        return await _domain_call(
+            lambda: service.get_stored_procedure(server, database, name, schema)
+        )
+
+    return server

sql_mini_mcp/models.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class OutputModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+class ServerSummary(OutputModel):
+    name: str
+    engine: Literal["sqlserver"]
+    access_level: Literal["metadata", "pii_safe"]
+
+
+class ServerList(OutputModel):
+    servers: list[ServerSummary]
+
+
+class DatabaseSummary(OutputModel):
+    name: str
+
+
+class DatabaseList(OutputModel):
+    databases: list[DatabaseSummary]
+
+
+class TableSummary(OutputModel):
+    schema_: str | None = Field(alias="schema")
+    name: str
+
+
+class TableList(OutputModel):
+    tables: list[TableSummary]
+
+
+class ColumnDefinition(OutputModel):
+    name: str
+    native_type: str
+    nullable: bool
+    length: int | None = None
+    precision: int | None = None
+    scale: int | None = None
+    autoincrement: bool | str | None = None
+    identity: dict[str, Any] | None = None
+    computed: dict[str, Any] | None = None
+    default: str | None = None
+
+
+class PrimaryKeyDefinition(OutputModel):
+    name: str | None = None
+    columns: list[str]
+
+
+class ForeignKeyDefinition(OutputModel):
+    name: str | None = None
+    columns: list[str]
+    referred_schema: str | None = None
+    referred_table: str
+    referred_columns: list[str]
+    options: dict[str, Any] = Field(default_factory=dict)
+
+
+class UniqueConstraintDefinition(OutputModel):
+    name: str | None = None
+    columns: list[str]
+
+
+class IndexDefinition(OutputModel):
+    name: str | None = None
+    columns: list[str | None]
+    unique: bool = False
+    expressions: list[str] = Field(default_factory=list)
+
+
+class TableDefinition(OutputModel):
+    schema_: str | None = Field(alias="schema")
+    name: str
+    columns: list[ColumnDefinition]
+    primary_key: PrimaryKeyDefinition
+    foreign_keys: list[ForeignKeyDefinition]
+    unique_constraints: list[UniqueConstraintDefinition]
+    indexes: list[IndexDefinition]
+
+
+class StoredProcedureSummary(OutputModel):
+    schema_: str | None = Field(alias="schema")
+    name: str
+
+
+class StoredProcedureList(OutputModel):
+    stored_procedures: list[StoredProcedureSummary]
+
+
+class StoredProcedureDefinition(OutputModel):
+    schema_: str | None = Field(alias="schema")
+    name: str
+    definition: str | None
+    definition_available: bool

sql_mini_mcp/service.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import TypeVar
+
+from sqlalchemy import Engine
+from sqlalchemy.exc import DBAPIError, OperationalError, SQLAlchemyError
+from sqlalchemy.exc import TimeoutError as SQLAlchemyTimeoutError
+
+from sql_mini_mcp.config import AppConfig, ServerConfig
+from sql_mini_mcp.db.extras import extras_for
+from sql_mini_mcp.db.reflection import get_table_definition as reflect_table_definition
+from sql_mini_mcp.db.reflection import list_tables as reflect_tables
+from sql_mini_mcp.db.registry import EngineRegistry
+from sql_mini_mcp.errors import DomainError, ErrorCode
+from sql_mini_mcp.models import (
+    DatabaseList,
+    DatabaseSummary,
+    ServerList,
+    ServerSummary,
+    StoredProcedureDefinition,
+    StoredProcedureList,
+    StoredProcedureSummary,
+    TableDefinition,
+    TableList,
+    TableSummary,
+)
+
+logger = logging.getLogger(__name__)
+T = TypeVar("T")
+
+
+def _contains(value: str, needle: str | None) -> bool:
+    return needle is None or needle.casefold() in value.casefold()
+
+
+class DatabaseService:
+    def __init__(self, config: AppConfig, registry: EngineRegistry) -> None:
+        self.config = config
+        self.registry = registry
+
+    def _server(self, alias: str) -> ServerConfig:
+        try:
+            return self.config.servers[alias]
+        except KeyError as exc:
+            raise DomainError(
+                ErrorCode.UNKNOWN_SERVER,
+                f"Unknown configured server {alias!r}.",
+                "Call list_servers to discover configured aliases.",
+            ) from exc
+
+    async def _run(self, alias: str, database: str | None, operation: Callable[[Engine], T]) -> T:
+        self._server(alias)
+        try:
+            return await self.registry.run(alias, database, operation)
+        except DomainError:
+            raise
+        except SQLAlchemyTimeoutError as exc:
+            raise DomainError(
+                ErrorCode.TIMEOUT,
+                "The database operation timed out.",
+                retryable=True,
+            ) from exc
+        except DBAPIError as exc:
+            message = str(exc.orig).casefold()
+            if "timeout" in message or "hyt00" in message or "hyt01" in message:
+                raise DomainError(
+                    ErrorCode.TIMEOUT, "The database operation timed out.", retryable=True
+                ) from exc
+            if any(value in message for value in ("permission", "denied", "not authorized")):
+                raise DomainError(
+                    ErrorCode.ACCESS_DENIED, "The database denied this operation."
+                ) from exc
+            if any(
+                value in message for value in ("cannot open database", "(4060)", "08001", "08004")
+            ):
+                raise DomainError(
+                    ErrorCode.CONNECTION_FAILED,
+                    "Could not connect to the configured database server.",
+                    retryable=True,
+                ) from exc
+            if isinstance(exc, OperationalError):
+                raise DomainError(
+                    ErrorCode.CONNECTION_FAILED,
+                    "Could not connect to the configured database server.",
+                    retryable=True,
+                ) from exc
+            error = DomainError.unexpected()
+            logger.error("Database operation failed; reference=%s", error.correlation_id)
+            raise error from exc
+        except SQLAlchemyError as exc:
+            error = DomainError.unexpected()
+            logger.error("SQLAlchemy operation failed; reference=%s", error.correlation_id)
+            raise error from exc
+        except Exception as exc:
+            error = DomainError.unexpected()
+            logger.error(
+                "Unexpected database operation failure; reference=%s", error.correlation_id
+            )
+            raise error from exc
+
+    def list_servers(self) -> ServerList:
+        return ServerList(
+            servers=[
+                ServerSummary(name=alias, engine=server.engine, access_level=server.access_level)
+                for alias, server in sorted(
+                    self.config.servers.items(), key=lambda item: item[0].casefold()
+                )
+            ]
+        )
+
+    async def list_databases(self, server: str, name_contains: str | None = None) -> DatabaseList:
+        configured = self._server(server)
+
+        def operation(engine: Engine) -> list[str]:
+            with engine.connect() as connection:
+                return extras_for(configured.engine).list_databases(connection)
+
+        names = await self._run(server, None, operation)
+        return DatabaseList(
+            databases=[
+                DatabaseSummary(name=name)
+                for name in sorted(names, key=str.casefold)
+                if _contains(name, name_contains)
+            ]
+        )
+
+    async def list_tables(
+        self,
+        server: str,
+        database: str,
+        schema: str | None = None,
+        name_contains: str | None = None,
+    ) -> TableList:
+        self._server(server)
+
+        def operation(engine: Engine) -> list[TableSummary]:
+            with engine.connect() as connection:
+                return reflect_tables(connection)
+
+        tables = await self._run(server, database, operation)
+        selected = [
+            table
+            for table in tables
+            if (schema is None or (table.schema_ or "").casefold() == schema.casefold())
+            and _contains(table.name, name_contains)
+        ]
+        selected.sort(key=lambda table: ((table.schema_ or "").casefold(), table.name.casefold()))
+        return TableList(tables=selected)
+
+    @staticmethod
+    def _resolve_table(tables: list[TableSummary], table: str, schema: str | None) -> TableSummary:
+        matches = [
+            item
+            for item in tables
+            if item.name.casefold() == table.casefold()
+            and (schema is None or (item.schema_ or "").casefold() == schema.casefold())
+        ]
+        if not matches:
+            raise DomainError(ErrorCode.NOT_FOUND, f"Table {table!r} was not found.")
+        if len(matches) > 1:
+            candidates = ", ".join(f"{item.schema_}.{item.name}" for item in matches)
+            raise DomainError(
+                ErrorCode.AMBIGUOUS_OBJECT,
+                f"Table {table!r} is ambiguous.",
+                f"Specify schema; candidates: {candidates}.",
+            )
+        return matches[0]
+
+    async def get_table_definition(
+        self, server: str, database: str, table: str, schema: str | None = None
+    ) -> TableDefinition:
+        self._server(server)
+
+        def operation(engine: Engine) -> TableDefinition:
+            with engine.connect() as connection:
+                selected = self._resolve_table(reflect_tables(connection), table, schema)
+                return reflect_table_definition(connection, selected.schema_, selected.name)
+
+        return await self._run(server, database, operation)
+
+    async def list_stored_procedures(
+        self,
+        server: str,
+        database: str,
+        schema: str | None = None,
+        name_contains: str | None = None,
+    ) -> StoredProcedureList:
+        configured = self._server(server)
+
+        def operation(engine: Engine) -> list[StoredProcedureSummary]:
+            with engine.connect() as connection:
+                return extras_for(configured.engine).list_stored_procedures(connection, database)
+
+        procedures = await self._run(server, database, operation)
+        selected = [
+            item
+            for item in procedures
+            if (schema is None or (item.schema_ or "").casefold() == schema.casefold())
+            and _contains(item.name, name_contains)
+        ]
+        selected.sort(key=lambda item: ((item.schema_ or "").casefold(), item.name.casefold()))
+        return StoredProcedureList(stored_procedures=selected)
+
+    async def get_stored_procedure(
+        self,
+        server: str,
+        database: str,
+        name: str,
+        schema: str | None = None,
+    ) -> StoredProcedureDefinition:
+        configured = self._server(server)
+        listing = await self.list_stored_procedures(server, database, schema)
+        matches = [
+            item for item in listing.stored_procedures if item.name.casefold() == name.casefold()
+        ]
+        if not matches:
+            raise DomainError(ErrorCode.NOT_FOUND, f"Stored procedure {name!r} was not found.")
+        if len(matches) > 1:
+            candidates = ", ".join(f"{item.schema_}.{item.name}" for item in matches)
+            raise DomainError(
+                ErrorCode.AMBIGUOUS_OBJECT,
+                f"Stored procedure {name!r} is ambiguous.",
+                f"Specify schema; candidates: {candidates}.",
+            )
+        selected = matches[0]
+
+        def operation(engine: Engine) -> StoredProcedureDefinition | None:
+            with engine.connect() as connection:
+                return extras_for(configured.engine).get_stored_procedure(
+                    connection, database, selected.schema_, selected.name
+                )
+
+        result = await self._run(server, database, operation)
+        if result is None:
+            raise DomainError(ErrorCode.NOT_FOUND, f"Stored procedure {name!r} was not found.")
+        if (
+            result.definition is not None
+            and len(result.definition) > self.config.runtime.max_definition_chars
+        ):
+            raise DomainError(
+                ErrorCode.DEFINITION_TOO_LARGE,
+                "Stored procedure definition exceeds the configured response limit.",
+            )
+        return result

sql_mini_mcp-0.9.1.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: sql-mini-mcp
+Version: 0.9.1
+Summary: Minimal, read-only, PII-safe MCP server for SQL databases.
+License: MIT License
+        
+        Copyright (c) 2026 Anton Padapryhara
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: <3.15,>=3.12
+Requires-Dist: anyio<5,>=4.8
+Requires-Dist: mcp<3,>=2
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: pyodbc<6,>=5.2
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: sqlalchemy<3,>=2.0
+Description-Content-Type: text/markdown
+
+# sql-mini-mcp
+
+<!-- mcp-name: io.github.proprock/sql-mini-mcp -->
+
+Compact MCP server for SQL Server metadata. The current Milestone 1 build supports only SQL
+Server and is metadata-only; PII-safe `execute_sql` is developed separately in Milestone 2.
+
+## Tools
+
+- `list_servers`
+- `list_databases`
+- `list_tables`
+- `get_table_definition`
+- `list_stored_procedures`
+- `get_stored_procedure`
+
+The server does not discover network servers, expose a full catalog as resources, use an ORM, or
+execute caller-provided SQL.
+
+## Install and run
+
+Python 3.12–3.14 and `uv` are required. SQL Server uses `pyodbc` and needs Microsoft ODBC Driver
+18 for SQL Server.
+
+```powershell
+uv sync --all-groups --locked
+Copy-Item sql-mini-mcp.example.yaml sql-mini-mcp.yaml
+$env:SQL_MINI_MCP_CONFIG = "$PWD\sql-mini-mcp.yaml"
+uv run sql-mini-mcp --check-config
+uv run sql-mini-mcp
+```
+
+`sql-mini-mcp` speaks MCP over stdio. Configure the same command and environment in the MCP host.
+All logs go to stderr.
+
+MySQL/MariaDB configuration is intentionally rejected until Milestone 3.
+
+## Configuration and secrets
+
+Connection topology stays in YAML while `${NAME}` placeholders read process environment values.
+A placeholder occupying the entire `connection_url` may contain a complete SQLAlchemy URL;
+embedded values are URL-encoded before substitution.
+
+Every `pii_safe` alias requires its own base64-encoded 32-byte key:
+
+```powershell
+$bytes = New-Object byte[] 32
+[System.Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
+$env:LEGACY_PROD_PII_KEY = [Convert]::ToBase64String($bytes)
+```
+
+Keys are rejected if reused by two aliases. Milestone 2 will authenticate the server alias as
+AES-GCM associated data, so tokens cannot cross aliases even if keys are accidentally duplicated
+outside normal config loading. Key rotation or alias renaming will invalidate existing tokens.
+
+See [sql-mini-mcp.example.yaml](sql-mini-mcp.example.yaml) for a complete example.
+
+## Development
+
+```powershell
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest tests/unit tests/contract -m "not integration"
+```
+
+## Live SQL Server gate
+
+The reproducible Windows gate requires Docker Desktop in Linux-container mode and ODBC Driver 18.
+It starts the digest-pinned SQL Server 2022 service when needed, then reuses the healthy container
+and its test database on later runs:
+
+```powershell
+.\scripts\test-sqlserver.ps1
+```
+
+Each run creates uniquely named schemas, tables, stored procedures, users, and logins, then removes
+those objects in `finally`. The container and its volume remain available for fast repeat runs. To
+explicitly remove that local test service and its volume:
+
+```powershell
+.\scripts\test-sqlserver.ps1 -Reset
+```
+
+The container runs SQL Server 2022 with the test database at compatibility level 130. That exercises
+the SQL Server 2016 compatibility surface, but it is not evidence of a run against an actual SQL
+Server 2016 instance. An external disposable SQL Server can be checked directly:
+
+```powershell
+$env:SQL_MINI_MCP_TEST_SQLSERVER_URL = "mssql+pyodbc://..."
+uv run pytest tests/integration/sqlserver -m integration -v
+```
+
+Live and future Milestone 2 security gates are documented in [CHECKS.md](CHECKS.md). Architecture
+and threat assumptions are in [ARCHITECTURE.md](ARCHITECTURE.md) and [SECURITY.md](SECURITY.md).

sql_mini_mcp-0.9.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+sql_mini_mcp/__init__.py,sha256=8CM4oqvSvhTvMBpyrk-u9hekO-_wnTCdXJUwnq9sMNQ,84
+sql_mini_mcp/__main__.py,sha256=2SW1ssw2kdxbwsgwv38eutoVXtYfsArk2PgvViBLvws,1210
+sql_mini_mcp/config.py,sha256=KYDiW2MR_xI28iay1w73cylnfxkE4R7Noy6dHA_5xZU,8031
+sql_mini_mcp/errors.py,sha256=2V-gXe9j3zdlQQ0ryGEaHk9ET1BxMbWrc7DXkdqOd2w,1483
+sql_mini_mcp/mcp_server.py,sha256=236wIfMI294vM68GaGIlPZec3cvt0hZNeiWt0MxulVo,4358
+sql_mini_mcp/models.py,sha256=IHPm9gXIinHbXEhZSCLh3BoTB3Fk6-rdSUFrDOUNRWU,2348
+sql_mini_mcp/service.py,sha256=6SMLgPds4mTe9bGuF54Bla4T1eB0M6Wlwfat8E6i3zk,9632
+sql_mini_mcp/db/__init__.py,sha256=9OzZMXtRCRhrc9UW7wyP3WpHqYdARd-t9CpEgNJ7n-U,34
+sql_mini_mcp/db/extras.py,sha256=WhawJs8czPfm7EO5-t8kNGPijIVs8qBjlh-cUuTYVso,839
+sql_mini_mcp/db/reflection.py,sha256=7UdtSglUZ8duvMpRCEY6061ZtR41BrdhQOBY6hgMemM,4331
+sql_mini_mcp/db/registry.py,sha256=V-zobzqW1a5KfuP3riEZbNGJ2F0eFWkWE4j4xbbPnT0,3373
+sql_mini_mcp/db/sqlserver.py,sha256=Kky09ANKgPUts-Z8Oa8ywdvTrJdbqDm5UyrJM-xTyE4,2296
+sql_mini_mcp-0.9.1.dist-info/METADATA,sha256=P4jSC2PBZPJsX0CJLFX-_NOAh4LJmJ9WbUgXlfY2tzk,4988
+sql_mini_mcp-0.9.1.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+sql_mini_mcp-0.9.1.dist-info/entry_points.txt,sha256=7wwNP0cLVOr0osCAJudsw5o793e1evW6uK8NSxCyPJ0,60
+sql_mini_mcp-0.9.1.dist-info/licenses/LICENSE,sha256=D5ajj8LaHI_KEmp64J78GqH7a71vwYWZIg3spYMVYJY,1074
+sql_mini_mcp-0.9.1.dist-info/RECORD,,

sql_mini_mcp-0.9.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

sql_mini_mcp-0.9.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sql-mini-mcp = sql_mini_mcp.__main__:main

sql_mini_mcp-0.9.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton Padapryhara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.