sql-mcp 0.1.0__py3-none-any.whl

sql_mcp/auth.py

@@ -0,0 +1,142 @@
+"""Connection and server-policy configuration for sql-mcp (CONCEPT:SQL-1.2).
+
+Named connections come from the environment, in priority order:
+
+1. ``SQL_CONNECTIONS`` — JSON mapping name -> DSN string or
+   ``{"url": ...}`` / ``{"dialect": ..., "host": ..., "port": ...,
+   "username": ..., "password": ..., "database": ..., "options": {...}}``.
+2. ``SQL_URL`` — a single DSN registered as connection ``"default"``.
+3. Discrete fields — ``SQL_DIALECT`` + ``SQL_HOST`` / ``SQL_PORT`` /
+   ``SQL_USERNAME`` / ``SQL_PASSWORD`` / ``SQL_DATABASE`` / ``SQL_OPTIONS``
+   (JSON), registered as ``"default"``.
+4. Nothing configured — a zero-infra in-memory SQLite connection named
+   ``"memory"`` so the server works out of the box.
+
+Secrets are never logged: URLs are parsed into ``sqlalchemy.engine.URL``
+objects and only ever rendered with ``hide_password=True``.
+"""
+
+import json
+import os
+
+from agent_utilities.base_utilities import get_logger, to_boolean
+from sqlalchemy.engine import URL, make_url
+
+from sql_mcp.dialects import build_url
+
+logger = get_logger(__name__)
+
+DEFAULT_MAX_ROWS = 500
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+
+def _connection_from_spec(name: str, spec: object) -> URL:
+    """Build a SQLAlchemy URL from one ``SQL_CONNECTIONS`` entry."""
+    if isinstance(spec, str):
+        return make_url(spec)
+    if isinstance(spec, dict):
+        if "url" in spec:
+            return make_url(spec["url"])
+        if "dialect" in spec:
+            return build_url(
+                spec["dialect"],
+                host=spec.get("host"),
+                port=spec.get("port"),
+                username=spec.get("username"),
+                password=spec.get("password"),
+                database=spec.get("database"),
+                options=spec.get("options"),
+            )
+    raise ValueError(
+        f"Connection {name!r} in SQL_CONNECTIONS must be a DSN string or an "
+        "object with 'url' or 'dialect' fields."
+    )
+
+
+def load_connections() -> dict[str, URL]:
+    """Load the named-connection registry from the environment."""
+    raw = os.getenv("SQL_CONNECTIONS", "")
+    if raw.strip():
+        try:
+            mapping = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"SQL_CONNECTIONS is not valid JSON: {exc}") from exc
+        if not isinstance(mapping, dict) or not mapping:
+            raise ValueError(
+                "SQL_CONNECTIONS must be a non-empty JSON object mapping "
+                "connection names to DSNs or connection objects."
+            )
+        return {
+            name: _connection_from_spec(name, spec) for name, spec in mapping.items()
+        }
+
+    url = os.getenv("SQL_URL", "")
+    if url.strip():
+        return {"default": make_url(url)}
+
+    if os.getenv("SQL_DIALECT") or os.getenv("SQL_HOST"):
+        options_raw = os.getenv("SQL_OPTIONS", "")
+        options = json.loads(options_raw) if options_raw.strip() else None
+        port_raw = os.getenv("SQL_PORT", "")
+        return {
+            "default": build_url(
+                os.getenv("SQL_DIALECT", "postgres"),
+                host=os.getenv("SQL_HOST"),
+                port=int(port_raw) if port_raw.strip() else None,
+                username=os.getenv("SQL_USERNAME"),
+                password=os.getenv("SQL_PASSWORD"),
+                database=os.getenv("SQL_DATABASE"),
+                options=options,
+            )
+        }
+
+    logger.info(
+        "No SQL connection configured (SQL_CONNECTIONS/SQL_URL/SQL_HOST); "
+        "registering a zero-infra in-memory SQLite connection named 'memory'."
+    )
+    return {"memory": make_url("sqlite+pysqlite:///:memory:")}
+
+
+def allow_writes() -> bool:
+    """Whether DML/DDL via ``sql_execute`` is enabled (default: read-only)."""
+    return to_boolean(os.getenv("SQL_ALLOW_WRITES", "False"))
+
+
+def default_max_rows() -> int:
+    """Per-call row cap (``SQL_MAX_ROWS``, default 500); requests are clamped."""
+    return int(os.getenv("SQL_MAX_ROWS", str(DEFAULT_MAX_ROWS)))
+
+
+def default_timeout() -> float:
+    """Per-call statement timeout in seconds (``SQL_TIMEOUT_SECONDS``)."""
+    return float(os.getenv("SQL_TIMEOUT_SECONDS", str(DEFAULT_TIMEOUT_SECONDS)))
+
+
+_api = None
+
+
+def get_api():
+    """Return the process-wide :class:`~sql_mcp.api_client.Api` instance.
+
+    Built lazily from the environment; ``reset_api()`` clears the cache (used
+    by tests and after configuration changes).
+    """
+    global _api
+    if _api is None:
+        from sql_mcp.api_client import Api
+
+        _api = Api(
+            connections=load_connections(),
+            allow_writes=allow_writes(),
+            max_rows=default_max_rows(),
+            timeout=default_timeout(),
+        )
+    return _api
+
+
+def reset_api() -> None:
+    """Dispose the cached client so the next ``get_api()`` re-reads the env."""
+    global _api
+    if _api is not None:
+        _api.dispose()
+    _api = None

sql_mcp/dialects.py

@@ -0,0 +1,183 @@
+"""Dialect registry for sql-mcp (CONCEPT:SQL-1.1).
+
+Mirrors the vector-mcp backend-registry pattern: every supported SQL engine is
+described by a :class:`DialectSpec` entry in :data:`DIALECTS`. The spec carries
+the SQLAlchemy URL scheme, the optional driver package (and which pip extra
+ships it), and the dialect-specific administrative SQL the ``sql_admin`` tool
+uses. Core ships SQLite only (stdlib-backed); the other drivers are optional
+extras so the base install stays thin.
+"""
+
+import importlib
+from dataclasses import dataclass
+
+from sqlalchemy.engine import URL
+
+
+@dataclass(frozen=True)
+class DialectSpec:
+    """Static description of one supported SQL dialect."""
+
+    name: str
+    sqlalchemy_scheme: str
+    driver_module: str | None
+    extra: str | None
+    default_port: int | None
+    explain_prefix: str | None
+    version_sql: str | None
+    active_connections_sql: str | None
+
+
+DIALECTS: dict[str, DialectSpec] = {
+    "sqlite": DialectSpec(
+        name="sqlite",
+        sqlalchemy_scheme="sqlite+pysqlite",
+        driver_module=None,
+        extra=None,
+        default_port=None,
+        explain_prefix="EXPLAIN QUERY PLAN",
+        version_sql="SELECT sqlite_version()",
+        active_connections_sql=None,
+    ),
+    "postgres": DialectSpec(
+        name="postgres",
+        sqlalchemy_scheme="postgresql+psycopg",
+        driver_module="psycopg",
+        extra="postgres",
+        default_port=5432,
+        explain_prefix="EXPLAIN",
+        version_sql="SELECT version()",
+        active_connections_sql=(
+            "SELECT pid, usename, datname, state, application_name, query_start "
+            "FROM pg_stat_activity WHERE pid <> pg_backend_pid()"
+        ),
+    ),
+    "mysql": DialectSpec(
+        name="mysql",
+        sqlalchemy_scheme="mysql+pymysql",
+        driver_module="pymysql",
+        extra="mysql",
+        default_port=3306,
+        explain_prefix="EXPLAIN",
+        version_sql="SELECT VERSION()",
+        active_connections_sql=(
+            "SELECT id, user, host, db, command, time, state "
+            "FROM information_schema.processlist"
+        ),
+    ),
+    "mssql": DialectSpec(
+        name="mssql",
+        sqlalchemy_scheme="mssql+pyodbc",
+        driver_module="pyodbc",
+        extra="mssql",
+        default_port=1433,
+        explain_prefix=None,
+        version_sql="SELECT @@VERSION",
+        active_connections_sql=(
+            "SELECT session_id, login_name, status, host_name, program_name "
+            "FROM sys.dm_exec_sessions WHERE is_user_process = 1"
+        ),
+    ),
+    "oracle": DialectSpec(
+        name="oracle",
+        sqlalchemy_scheme="oracle+oracledb",
+        driver_module="oracledb",
+        extra="oracle",
+        default_port=1521,
+        explain_prefix="EXPLAIN PLAN FOR",
+        version_sql="SELECT banner FROM v$version",
+        active_connections_sql=(
+            "SELECT sid, username, status, machine, program "
+            "FROM v$session WHERE username IS NOT NULL"
+        ),
+    ),
+}
+
+ALIASES: dict[str, str] = {
+    "postgresql": "postgres",
+    "pg": "postgres",
+    "pgsql": "postgres",
+    "mariadb": "mysql",
+    "sqlserver": "mssql",
+    "mssqlserver": "mssql",
+    "sqlite3": "sqlite",
+}
+
+
+def get_dialect(name: str) -> DialectSpec:
+    """Resolve a dialect (or alias) name to its :class:`DialectSpec`.
+
+    Raises ``ValueError`` listing the supported dialects when unknown.
+    """
+    key = ALIASES.get(name.lower().strip(), name.lower().strip())
+    spec = DIALECTS.get(key)
+    if spec is None:
+        supported = ", ".join(sorted(DIALECTS))
+        raise ValueError(f"Unknown SQL dialect {name!r}. Supported: {supported}.")
+    return spec
+
+
+def dialect_for_url(url: URL) -> DialectSpec | None:
+    """Best-effort match of a SQLAlchemy URL to a registered dialect spec."""
+    backend = url.get_backend_name()
+    for spec in DIALECTS.values():
+        if spec.sqlalchemy_scheme.split("+", 1)[0] == backend:
+            return spec
+    alias = ALIASES.get(backend)
+    return DIALECTS.get(alias) if alias else None
+
+
+def require_driver(spec: DialectSpec) -> None:
+    """Verify the dialect's DBAPI driver is importable.
+
+    Raises ``ImportError`` naming the pip extra that ships the driver, so the
+    failure is self-explanatory (``pip install sql-mcp[postgres]`` etc.).
+    """
+    if spec.driver_module is None:
+        return
+    try:
+        importlib.import_module(spec.driver_module)
+    except ImportError as exc:
+        raise ImportError(
+            f"The {spec.name!r} dialect needs the {spec.driver_module!r} driver. "
+            f"Install it with: pip install sql-mcp[{spec.extra}]"
+        ) from exc
+
+
+def driver_available(spec: DialectSpec) -> bool:
+    """Return True when the dialect's DBAPI driver can be imported."""
+    if spec.driver_module is None:
+        return True
+    try:
+        importlib.import_module(spec.driver_module)
+        return True
+    except ImportError:
+        return False
+
+
+def build_url(
+    dialect: str,
+    host: str | None = None,
+    port: int | None = None,
+    username: str | None = None,
+    password: str | None = None,
+    database: str | None = None,
+    options: dict[str, str] | None = None,
+) -> URL:
+    """Build a SQLAlchemy URL from discrete connection fields.
+
+    Uses ``URL.create`` so credentials are quoted correctly and the password
+    is never interpolated into a plain string (redaction-safe by design).
+    """
+    spec = get_dialect(dialect)
+    if spec.name == "sqlite":
+        return URL.create(spec.sqlalchemy_scheme, database=database or ":memory:")
+    return URL.create(
+        spec.sqlalchemy_scheme,
+        username=username,
+        password=password,
+        host=host,
+        port=port or spec.default_port,
+        database=database,
+        query=dict(options or {}),
+    )

sql_mcp/main_agent.json

@@ -0,0 +1,14 @@
+{
+  "task": "main-agent",
+  "input": "# main-agent\n\nYou are the primary orchestrator for this workspace. Your goal is to help the user manage their projects and coordinate specialized agents.\n\n### Core Principles\n* Be concise and efficient.\n* Use the knowledge graph to discover tools and experts.\n* Verify your work before concluding.\n\nYour personality:\n* **Emoji:** 🤖\n* **Vibe:** Professional, efficient, helpful",
+  "type": "prompt",
+  "description": "The primary orchestrator agent for this workspace.",
+  "tools": [
+    "workspace-manager",
+    "agent-workflows"
+  ],
+  "topic": "General Expertise",
+  "tone": "technical and precise",
+  "style": "professional assistant",
+  "goal": "Coordinate specialized agents and manage the workspace."
+}

sql_mcp/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP tool registration for sql_mcp."""
+
+from sql_mcp.mcp.mcp_sql import register_sql_tools
+
+__all__ = ["register_sql_tools"]

sql_mcp/mcp/mcp_sql.py

@@ -0,0 +1,224 @@
+"""Action-dispatch MCP tools for sql-mcp (CONCEPT:SQL-1.0, CONCEPT:SQL-1.5).
+
+Four consolidated tools — ``sql_query``, ``sql_execute``, ``sql_schema``, and
+``sql_admin`` — each routing an ``action`` + ``params_json`` pair to the
+:class:`~sql_mcp.api_client.Api` facade. The tools are thin shims: parameter
+parsing only, no business logic. Every tool accepts an optional ``connection``
+naming one of the configured connections (defaults to the sole/first one).
+"""
+
+import json
+from typing import Any
+
+from fastmcp import FastMCP
+from pydantic import Field
+
+from sql_mcp.auth import get_api
+
+
+def register_sql_tools(mcp: FastMCP) -> None:
+    """Register the query, execute, schema, and admin tools."""
+
+    @mcp.tool(tags={"query"})
+    async def sql_query(
+        action: str = Field(
+            description=(
+                "Query action. One of: 'execute' (run a read-only SELECT/CTE "
+                "with bound parameters), 'explain' (return the dialect's query "
+                "plan for a read-only statement)."
+            )
+        ),
+        params_json: str = Field(
+            default="{}",
+            description=(
+                "JSON of arguments. execute: "
+                '{"sql": "SELECT * FROM users WHERE id = :id", '
+                '"params": {"id": 1}, "max_rows": 100, "timeout": 10}. '
+                'explain: {"sql": "SELECT ...", "params": {...}}. '
+                "Statements must be single, read-only (SELECT/WITH/EXPLAIN/"
+                "SHOW/DESCRIBE/PRAGMA/VALUES), and use :name bound parameters "
+                "— never inline values. max_rows is clamped to the server cap."
+            ),
+        ),
+        connection: str = Field(
+            default="",
+            description=(
+                "Named connection from the server config (see sql_admin "
+                "'connections'). Empty = the default (sole/first) connection."
+            ),
+        ),
+    ) -> Any:
+        """Run read-only SQL with row cap, timeout, and column metadata."""
+        api = get_api()
+        p = json.loads(params_json) if params_json else {}
+        if action == "execute":
+            return api.query(
+                p["sql"],
+                params=p.get("params"),
+                connection=connection or None,
+                max_rows=p.get("max_rows"),
+                timeout=p.get("timeout"),
+            )
+        if action == "explain":
+            return api.explain(
+                p["sql"],
+                params=p.get("params"),
+                connection=connection or None,
+                timeout=p.get("timeout"),
+            )
+        raise ValueError(f"Unknown query action: {action!r}.")
+
+    @mcp.tool(tags={"execute"})
+    async def sql_execute(
+        action: str = Field(
+            description=(
+                "Write action. One of: 'execute' (one DML/DDL statement in a "
+                "transaction; params may be a dict or a list of dicts for "
+                "executemany), 'script' (a list of statements in ONE "
+                "all-or-nothing transaction). Requires the server to run with "
+                "SQL_ALLOW_WRITES=True — the default is read-only."
+            )
+        ),
+        params_json: str = Field(
+            default="{}",
+            description=(
+                "JSON of arguments. execute: "
+                '{"sql": "INSERT INTO t (a) VALUES (:a)", "params": {"a": 1}} '
+                'or "params": [{"a": 1}, {"a": 2}] for executemany. '
+                'script: {"statements": ["CREATE TABLE ...", "INSERT ..."]}. '
+                "Optional 'timeout' (seconds) on both. Returns affected-row "
+                "counts."
+            ),
+        ),
+        connection: str = Field(
+            default="",
+            description=(
+                "Named connection from the server config. Empty = the default "
+                "(sole/first) connection."
+            ),
+        ),
+    ) -> Any:
+        """Run DML/DDL in transactions (gated by SQL_ALLOW_WRITES)."""
+        api = get_api()
+        p = json.loads(params_json) if params_json else {}
+        if action == "execute":
+            return api.execute(
+                p["sql"],
+                params=p.get("params"),
+                connection=connection or None,
+                timeout=p.get("timeout"),
+            )
+        if action == "script":
+            return api.execute_script(
+                p["statements"],
+                connection=connection or None,
+                timeout=p.get("timeout"),
+            )
+        raise ValueError(f"Unknown execute action: {action!r}.")
+
+    @mcp.tool(tags={"schema"})
+    async def sql_schema(
+        action: str = Field(
+            description=(
+                "Schema action. One of: 'schemas' (list schema names), "
+                "'tables', 'views' (list names, optional schema), 'columns', "
+                "'indexes', 'foreign_keys' (describe a table), 'ddl' (reflect "
+                "CREATE TABLE DDL), 'sample' (preview rows with a limit)."
+            )
+        ),
+        params_json: str = Field(
+            default="{}",
+            description=(
+                "JSON of arguments. schemas: {}. tables/views: "
+                '{"schema": "public"} (optional). '
+                'columns/indexes/foreign_keys/ddl: {"table": "users", '
+                '"schema": "public"}. sample: {"table": "users", '
+                '"limit": 10, "schema": "public"} (limit clamped to the '
+                "server row cap)."
+            ),
+        ),
+        connection: str = Field(
+            default="",
+            description=(
+                "Named connection from the server config. Empty = the default "
+                "(sole/first) connection."
+            ),
+        ),
+    ) -> Any:
+        """Inspect schemas, tables, views, columns, indexes, FKs, and DDL."""
+        api = get_api()
+        p = json.loads(params_json) if params_json else {}
+        conn = connection or None
+        schema = p.get("schema")
+        if action == "schemas":
+            return api.list_schemas(connection=conn)
+        if action == "tables":
+            return api.list_tables(schema=schema, connection=conn)
+        if action == "views":
+            return api.list_views(schema=schema, connection=conn)
+        if action == "columns":
+            return api.list_columns(p["table"], schema=schema, connection=conn)
+        if action == "indexes":
+            return api.list_indexes(p["table"], schema=schema, connection=conn)
+        if action == "foreign_keys":
+            return api.list_foreign_keys(p["table"], schema=schema, connection=conn)
+        if action == "ddl":
+            return api.table_ddl(p["table"], schema=schema, connection=conn)
+        if action == "sample":
+            return api.sample_rows(
+                p["table"],
+                schema=schema,
+                limit=p.get("limit", 10),
+                connection=conn,
+            )
+        raise ValueError(f"Unknown schema action: {action!r}.")
+
+    @mcp.tool(tags={"admin"})
+    async def sql_admin(
+        action: str = Field(
+            description=(
+                "Admin action. One of: 'ping' (connection test + latency), "
+                "'version' (server version), 'active_connections' (server "
+                "sessions, where the dialect supports it), 'connections' "
+                "(list configured connections, passwords redacted), "
+                "'dialects' (supported dialects + driver availability)."
+            )
+        ),
+        params_json: str = Field(
+            default="{}",
+            description="JSON of arguments. All admin actions take {}.",
+        ),
+        connection: str = Field(
+            default="",
+            description=(
+                "Named connection from the server config. Empty = the default "
+                "(sole/first) connection."
+            ),
+        ),
+    ) -> Any:
+        """Connection health, server version, sessions, and registry info."""
+        api = get_api()
+        if params_json:
+            json.loads(params_json)  # validate early; admin actions take {}
+        conn = connection or None
+        if action == "ping":
+            return api.ping(connection=conn)
+        if action == "version":
+            return api.server_version(connection=conn)
+        if action == "active_connections":
+            return api.active_connections(connection=conn)
+        if action == "connections":
+            return api.describe_connections()
+        if action == "dialects":
+            from sql_mcp.dialects import DIALECTS, driver_available
+
+            return [
+                {
+                    "dialect": spec.name,
+                    "scheme": spec.sqlalchemy_scheme,
+                    "extra": spec.extra,
+                    "driver_installed": driver_available(spec),
+                }
+                for spec in DIALECTS.values()
+            ]
+        raise ValueError(f"Unknown admin action: {action!r}.")

sql_mcp/mcp_config.json

@@ -0,0 +1,33 @@
+{
+  "mcpServers": {
+    "sql-mcp": {
+      "command": "uv",
+      "args": [
+        "run",
+        "sql-mcp"
+      ],
+      "env": {
+        "FASTMCP_LOG_LEVEL": "<YOUR_FASTMCP_LOG_LEVEL>",
+        "NO_COLOR": "<YOUR_NO_COLOR>",
+        "TERM": "<YOUR_TERM>",
+        "AGENT_DESCRIPTION": "<YOUR_AGENT_DESCRIPTION>",
+        "AGENT_SYSTEM_PROMPT": "<YOUR_AGENT_SYSTEM_PROMPT>",
+        "DEFAULT_AGENT_NAME": "<YOUR_DEFAULT_AGENT_NAME>",
+        "MCP_URL": "<YOUR_MCP_URL>",
+        "SQL_CONNECTIONS": "<YOUR_SQL_CONNECTIONS>",
+        "SQL_URL": "<YOUR_SQL_URL>",
+        "SQL_DIALECT": "<YOUR_SQL_DIALECT>",
+        "SQL_HOST": "<YOUR_SQL_HOST>",
+        "SQL_PORT": "<YOUR_SQL_PORT>",
+        "SQL_USERNAME": "<YOUR_SQL_USERNAME>",
+        "SQL_PASSWORD": "<YOUR_SQL_PASSWORD>",
+        "SQL_DATABASE": "<YOUR_SQL_DATABASE>",
+        "SQL_OPTIONS": "<YOUR_SQL_OPTIONS>",
+        "SQL_ALLOW_WRITES": "False",
+        "SQL_MAX_ROWS": "500",
+        "SQL_TIMEOUT_SECONDS": "30",
+        "SQLTOOL": "True"
+      }
+    }
+  }
+}

sql_mcp/mcp_server.py

@@ -0,0 +1,59 @@
+"""Main FastMCP server and tool registration for sql-mcp."""
+
+import os
+import sys
+from typing import Any
+
+from agent_utilities.base_utilities import to_boolean
+from agent_utilities.mcp_utilities import create_mcp_server
+from dotenv import find_dotenv, load_dotenv
+from fastmcp.utilities.logging import get_logger
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from sql_mcp.mcp.mcp_sql import register_sql_tools
+
+__version__ = "0.1.0"
+logger = get_logger(name="sql_mcp")
+
+
+def get_mcp_instance() -> tuple[Any, ...]:
+    load_dotenv(find_dotenv())
+    args, mcp, middlewares = create_mcp_server(
+        name="SQL MCP",
+        version=__version__,
+        instructions=(
+            "Generic SQL database MCP Server - read-only queries, gated "
+            "DML/DDL, schema reflection, and connection admin over "
+            "SQLAlchemy 2.x Core (SQLite, Postgres, MySQL/MariaDB, MSSQL, "
+            "Oracle) with named multi-connection support."
+        ),
+    )
+
+    @mcp.custom_route("/health", methods=["GET"])
+    async def health_check(request: Request) -> JSONResponse:
+        return JSONResponse({"status": "OK"})
+
+    if to_boolean(os.getenv("SQLTOOL", "True")):
+        register_sql_tools(mcp)
+
+    for mw in middlewares:
+        mcp.add_middleware(mw)
+    return mcp, args, middlewares
+
+
+def mcp_server() -> None:
+    mcp, args, middlewares = get_mcp_instance()
+    print(f"SQL MCP v{__version__}", file=sys.stderr)
+    if args.transport == "stdio":
+        mcp.run(transport="stdio")
+    elif args.transport == "streamable-http":
+        mcp.run(transport="streamable-http", host=args.host, port=args.port)
+    elif args.transport == "sse":
+        mcp.run(transport="sse", host=args.host, port=args.port)
+    else:
+        mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    mcp_server()