mcp-sql-querystore 0.1.0__py3-none-any.whl

mcp_sql_querystore/__init__.py

@@ -0,0 +1,3 @@
+"""mcp-sql-querystore: read-only MCP server for SQL Server Query Store diagnostics."""
+
+__version__ = "0.1.0"

mcp_sql_querystore/db.py

@@ -0,0 +1,251 @@
+"""Database connection layer.
+
+The read-only guarantee comes from the SQL login's permissions, NOT from this
+code. Provision a dedicated login with only:
+    GRANT VIEW DATABASE STATE   -- (or VIEW SERVER STATE for server-wide DMVs)
+    GRANT SELECT ON the sys.query_store_* catalog views
+and NO db_datareader / no SELECT on user tables. See README.
+
+This module adds parameterization and a keyword screen as defense-in-depth only.
+
+Secret handling: the connection string can be supplied whole, or assembled from
+parts with the password sourced indirectly (env var or file), so the password
+need not sit in a plaintext MCP config. See _connection_string() for the order.
+
+Audit logging: every query attempt is recorded via the "mcp_sql_querystore.audit"
+logger — tool, database, a hash of the SQL (not the text), row count, duration,
+and outcome. Credentials and parameter values are never logged.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import re
+import time
+from contextlib import contextmanager
+from typing import Any, Iterator
+
+# pyodbc is imported lazily inside get_cursor() rather than at module load. This
+# keeps the pure validators (validate_db_name, assert_select_only) importable in
+# environments without the ODBC driver — e.g. CI running the test suite — while
+# still requiring pyodbc the moment an actual connection is attempted.
+
+audit_log = logging.getLogger("mcp_sql_querystore.audit")
+
+
+# --- Configuration & secret handling ------------------------------------------
+#
+# Resolution order for the connection string:
+#   1. MCP_SQL_CONNECTION_STRING           — full string (back-compat; simplest)
+#   2. MCP_SQL_CONNECTION_STRING_FILE      — path to a file containing the full
+#                                            string (Docker/K8s secret style)
+#   3. assembled from parts:
+#        MCP_SQL_SERVER, MCP_SQL_DATABASE (default "master"),
+#        MCP_SQL_DRIVER (default "ODBC Driver 18 for SQL Server"),
+#        MCP_SQL_ENCRYPT (default "yes"), MCP_SQL_TRUST_CERT (default "no"),
+#        MCP_SQL_EXTRA (optional, appended verbatim, e.g. ApplicationIntent=ReadOnly)
+#      Auth for the assembled form:
+#        - Integrated (Windows/AAD): set MCP_SQL_TRUSTED=yes and omit UID/PWD.
+#          Preferred for CJIS/PCI — no password to store at all.
+#        - SQL auth: MCP_SQL_UID plus the password from ONE of:
+#            MCP_SQL_PWD_FILE   — path to a file holding just the password
+#                                 (secret-store / vault-mounted file)
+#            MCP_SQL_PWD_ENV    — the NAME of another env var holding the password
+#            MCP_SQL_PWD        — the password directly (least preferred)
+
+_FULL_ENV = "MCP_SQL_CONNECTION_STRING"
+_FULL_FILE_ENV = "MCP_SQL_CONNECTION_STRING_FILE"
+
+
+def _read_secret_file(path: str) -> str:
+    # utf-8-sig transparently strips a UTF-8/UTF-16 BOM if present (e.g. files
+    # written by PowerShell Out-File or some secret mounts) and reads plain
+    # UTF-8 otherwise.
+    try:
+        with open(path, encoding="utf-8-sig") as fh:
+            return fh.read().strip()
+    except UnicodeDecodeError:
+        # Fall back for UTF-16 without/with BOM that utf-8-sig can't handle.
+        try:
+            with open(path, encoding="utf-16") as fh:
+                return fh.read().strip()
+        except (OSError, UnicodeError) as exc:
+            raise RuntimeError(
+                f"Secret file {path!r} is not UTF-8 or UTF-16 text: {exc}"
+            ) from exc
+    except OSError as exc:
+        raise RuntimeError(f"Could not read secret file {path!r}: {exc}") from exc
+
+
+def _resolve_password() -> str:
+    """Resolve the SQL password from a file, a named env var, or directly —
+    in that order of preference. Returns '' if none set (caller decides if ok)."""
+    pwd_file = os.environ.get("MCP_SQL_PWD_FILE")
+    if pwd_file:
+        return _read_secret_file(pwd_file)
+    pwd_env = os.environ.get("MCP_SQL_PWD_ENV")
+    if pwd_env:
+        val = os.environ.get(pwd_env)
+        if val is None:
+            raise RuntimeError(
+                f"MCP_SQL_PWD_ENV points to {pwd_env!r} but that variable is not set."
+            )
+        return val
+    return os.environ.get("MCP_SQL_PWD", "")
+
+
+def _assemble_connection_string() -> str:
+    server = os.environ.get("MCP_SQL_SERVER")
+    if not server:
+        raise RuntimeError(
+            "No connection configured. Set MCP_SQL_CONNECTION_STRING, or "
+            "MCP_SQL_CONNECTION_STRING_FILE, or MCP_SQL_SERVER (+ auth parts)."
+        )
+    driver = os.environ.get("MCP_SQL_DRIVER", "ODBC Driver 18 for SQL Server")
+    database = os.environ.get("MCP_SQL_DATABASE", "master")
+    encrypt = os.environ.get("MCP_SQL_ENCRYPT", "yes")
+    trust_cert = os.environ.get("MCP_SQL_TRUST_CERT", "no")
+
+    parts = [
+        f"Driver={{{driver}}}",
+        f"Server={server}",
+        f"Database={database}",
+        f"Encrypt={encrypt}",
+        f"TrustServerCertificate={trust_cert}",
+    ]
+
+    if os.environ.get("MCP_SQL_TRUSTED", "").lower() in ("1", "yes", "true"):
+        parts.append("Trusted_Connection=yes")
+    else:
+        uid = os.environ.get("MCP_SQL_UID")
+        if not uid:
+            raise RuntimeError(
+                "SQL auth selected but MCP_SQL_UID is not set (and MCP_SQL_TRUSTED "
+                "is not enabled for integrated auth)."
+            )
+        pwd = _resolve_password()
+        if not pwd:
+            raise RuntimeError(
+                "No password resolved. Set MCP_SQL_PWD_FILE, MCP_SQL_PWD_ENV, or "
+                "MCP_SQL_PWD — or use integrated auth via MCP_SQL_TRUSTED=yes."
+            )
+        parts.append(f"UID={uid}")
+        parts.append(f"PWD={pwd}")
+
+    extra = os.environ.get("MCP_SQL_EXTRA")
+    if extra:
+        parts.append(extra)
+    return ";".join(parts) + ";"
+
+
+def _connection_string() -> str:
+    full = os.environ.get(_FULL_ENV)
+    if full:
+        return full
+    full_file = os.environ.get(_FULL_FILE_ENV)
+    if full_file:
+        return _read_secret_file(full_file)
+    return _assemble_connection_string()
+
+
+# --- Defense-in-depth identifier + statement screening ------------------------
+
+# Database names are validated against this before being used to switch context.
+# SQL Server identifiers are broad, but we deliberately restrict to a safe subset
+# rather than trying to fully escape arbitrary names.
+_SAFE_DB_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_$#]{0,127}$")
+
+
+def validate_db_name(name: str) -> str:
+    if not isinstance(name, str) or not _SAFE_DB_NAME.match(name):
+        raise ValueError(
+            f"Invalid database name: {name!r}. Expected a plain SQL Server "
+            "identifier (letters, digits, _ $ #; starting with a letter/underscore)."
+        )
+    return name
+
+
+# Statements we run are all fixed SELECT text defined in this codebase. This
+# screen is a tripwire in case someone adds dynamic text later.
+_FORBIDDEN = re.compile(
+    r"\b(INSERT|UPDATE|DELETE|MERGE|DROP|ALTER|CREATE|TRUNCATE|EXEC|EXECUTE|"
+    r"GRANT|REVOKE|DENY|BACKUP|RESTORE|SHUTDOWN|RECONFIGURE)\b",
+    re.IGNORECASE,
+)
+
+
+def assert_select_only(sql: str) -> None:
+    if _FORBIDDEN.search(sql):
+        raise ValueError("Refusing to run: statement contains a non-SELECT keyword.")
+
+
+# --- Connection handling ------------------------------------------------------
+
+# Per-query command timeout (seconds); 0 disables. Connect timeout is separate.
+_QUERY_TIMEOUT = int(os.environ.get("MCP_SQL_QUERY_TIMEOUT", "30"))
+_CONNECT_TIMEOUT = int(os.environ.get("MCP_SQL_CONNECT_TIMEOUT", "10"))
+
+
+@contextmanager
+def get_cursor() -> Iterator[Any]:
+    import pyodbc  # lazy: only needed when actually connecting
+
+    conn = pyodbc.connect(_connection_string(), timeout=_CONNECT_TIMEOUT)
+    try:
+        # Belt-and-suspenders: reject any accidental writes at the session level.
+        # This does NOT replace login permissions.
+        conn.autocommit = True
+        conn.timeout = _QUERY_TIMEOUT  # per-command timeout
+        cursor = conn.cursor()
+        yield cursor
+    finally:
+        conn.close()
+
+
+def _sql_fingerprint(sql: str) -> str:
+    """Short stable hash of the SQL text, for the audit log — lets you correlate
+    which fixed statement ran without recording the text itself."""
+    return hashlib.sha256(sql.encode("utf-8")).hexdigest()[:12]
+
+
+def run_query(
+    sql: str,
+    params: tuple[Any, ...] = (),
+    database: str | None = None,
+    tool: str | None = None,
+) -> list[dict[str, Any]]:
+    """Run a fixed SELECT against an optional database context.
+
+    database, if given, is validated and switched via USE with a validated
+    identifier (it cannot be parameterized). params are bound positionally.
+    tool, if given, is recorded in the audit log to attribute the query.
+    """
+    assert_select_only(sql)
+    fingerprint = _sql_fingerprint(sql)
+    started = time.monotonic()
+    try:
+        with get_cursor() as cursor:
+            if database is not None:
+                db = validate_db_name(database)
+                # Identifier cannot be a bound parameter; db is validated above.
+                cursor.execute(f"USE [{db}];")
+            cursor.execute(sql, params)
+            columns = [c[0] for c in cursor.description]
+            rows = [dict(zip(columns, row)) for row in cursor.fetchall()]
+    except Exception as exc:
+        elapsed_ms = round((time.monotonic() - started) * 1000, 1)
+        # Log the outcome, never the SQL text, params, or connection string.
+        audit_log.warning(
+            "query_failed tool=%s db=%s sql=%s elapsed_ms=%s error=%s",
+            tool or "-", database or "-", fingerprint, elapsed_ms,
+            type(exc).__name__,
+        )
+        raise
+    elapsed_ms = round((time.monotonic() - started) * 1000, 1)
+    audit_log.info(
+        "query_ok tool=%s db=%s sql=%s rows=%s elapsed_ms=%s",
+        tool or "-", database or "-", fingerprint, len(rows), elapsed_ms,
+    )
+    return rows

mcp_sql_querystore/plan_parser.py

@@ -0,0 +1,101 @@
+"""Parse SQL Server showplan XML into a compact JSON summary.
+
+Goal: strip the heavy XML down to the things an LLM actually needs to reason
+about — missing indexes, implicit conversions (via warnings), key lookups, and
+plan-level warnings — so we don't burn tokens on raw showplan.
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from typing import Any
+
+# Showplan uses this namespace on every element.
+_NS = {"s": "http://schemas.microsoft.com/sqlserver/2004/07/showplan"}
+
+
+def _tag(elem: ET.Element) -> str:
+    return elem.tag.split("}", 1)[-1]
+
+
+def summarize_plan(plan_xml: str) -> dict[str, Any]:
+    """Return a compact dict summary of a showplan XML string."""
+    try:
+        root = ET.fromstring(plan_xml)
+    except ET.ParseError as exc:
+        return {"error": f"could not parse plan XML: {exc}"}
+
+    summary: dict[str, Any] = {
+        "missing_indexes": _missing_indexes(root),
+        "warnings": _warnings(root),
+        "key_lookups": _count_ops(root, "Key Lookup"),
+        "index_scans": _count_ops(root, "Index Scan"),
+        "table_scans": _count_ops(root, "Table Scan"),
+        "estimated_subtree_cost": _root_cost(root),
+    }
+    return summary
+
+
+def _missing_indexes(root: ET.Element) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for mig in root.iter("{%s}MissingIndexGroup" % _NS["s"]):
+        impact = mig.get("Impact")
+        for mi in mig.iter("{%s}MissingIndex" % _NS["s"]):
+            cols = {"equality": [], "inequality": [], "included": []}
+            for cg in mi.iter("{%s}ColumnGroup" % _NS["s"]):
+                usage = cg.get("Usage", "").upper()
+                names = [c.get("Name") for c in cg.iter("{%s}Column" % _NS["s"])]
+                # Check INEQUALITY before EQUALITY: "EQUALITY" is a substring of
+                # "INEQUALITY", so a loose "equality in usage" test misclassifies
+                # inequality column groups as equality ones.
+                if usage == "INEQUALITY":
+                    cols["inequality"] = names
+                elif usage == "EQUALITY":
+                    cols["equality"] = names
+                elif usage == "INCLUDE":
+                    cols["included"] = names
+            out.append(
+                {
+                    "impact_pct": float(impact) if impact else None,
+                    "database": mi.get("Database"),
+                    "schema": mi.get("Schema"),
+                    "table": mi.get("Table"),
+                    "columns": cols,
+                }
+            )
+    return out
+
+
+def _warnings(root: ET.Element) -> list[str]:
+    found: list[str] = []
+    for w in root.iter("{%s}Warnings" % _NS["s"]):
+        for child in w:
+            name = _tag(child)
+            # Common ones: PlanAffectingConvert (implicit conversion),
+            # SpillToTempDb, ColumnsWithNoStatistics, NoJoinPredicate.
+            if name == "PlanAffectingConvert":
+                found.append(
+                    f"implicit_conversion: {child.get('Expression', '')[:200]}"
+                )
+            else:
+                found.append(name)
+    return found
+
+
+def _count_ops(root: ET.Element, physical_op: str) -> int:
+    return sum(
+        1
+        for rel in root.iter("{%s}RelOp" % _NS["s"])
+        if rel.get("PhysicalOp") == physical_op
+    )
+
+
+def _root_cost(root: ET.Element) -> float | None:
+    for stmt in root.iter("{%s}StmtSimple" % _NS["s"]):
+        cost = stmt.get("StatementSubTreeCost")
+        if cost:
+            try:
+                return float(cost)
+            except ValueError:
+                return None
+    return None

mcp_sql_querystore/queries.py

@@ -0,0 +1,261 @@
+"""Fixed T-SQL for each diagnostic tool.
+
+All statements are SELECT-only and parameterized. Metric column names are chosen
+from a fixed whitelist in the caller — never interpolated from user input.
+
+Query Store column availability assumed: SQL Server 2019+/2022 and Azure SQL MI.
+On 2016/2017 some columns (e.g. avg_query_max_used_memory) differ; adjust if you
+target those.
+"""
+
+from __future__ import annotations
+
+# Whitelist mapping the public "metric" enum to the Query Store column.
+# The value is substituted into SQL, so it MUST come from this dict only.
+METRIC_COLUMNS: dict[str, str] = {
+    "cpu_time": "avg_cpu_time",
+    "duration": "avg_duration",
+    "logical_reads": "avg_logical_io_reads",
+}
+
+
+def regressed_queries_sql(metric_column: str) -> str:
+    """Baseline-vs-recent regression detection.
+
+    Splits the lookback window into a baseline period (older) and a recent period
+    (newer), aggregates the chosen metric per query over each, and returns queries
+    whose recent metric is materially worse than baseline.
+
+    metric_column MUST be a value from METRIC_COLUMNS (caller enforces this).
+    All other values are bound positionally via pyodbc `?` placeholders.
+
+    Bound parameter order (see server._get_regressed_queries):
+        1  recent_hours     -> recent window boundary
+        2  recent_hours     -> (reused) baseline window start
+        3  baseline_hours   -> (reused) baseline window start
+        4  min_executions   -> baseline exec floor
+        5  min_executions   -> recent exec floor
+        6  regression_threshold
+        7  top_n
+    """
+    return f"""
+SET NOCOUNT ON;
+
+DECLARE @now DATETIMEOFFSET = SYSUTCDATETIME();
+DECLARE @recent_start DATETIMEOFFSET = DATEADD(HOUR, -CAST(? AS INT), @now);
+DECLARE @baseline_start DATETIMEOFFSET =
+    DATEADD(HOUR, -(CAST(? AS INT) + CAST(? AS INT)), @now);
+
+WITH stats AS (
+    SELECT
+        q.query_id,
+        rs.plan_id,
+        rsi.start_time,
+        rs.count_executions,
+        rs.{metric_column} AS metric_val
+    FROM sys.query_store_runtime_stats rs
+    JOIN sys.query_store_runtime_stats_interval rsi
+        ON rs.runtime_stats_interval_id = rsi.runtime_stats_interval_id
+    JOIN sys.query_store_plan p
+        ON rs.plan_id = p.plan_id
+    JOIN sys.query_store_query q
+        ON p.query_id = q.query_id
+    WHERE rsi.start_time >= @baseline_start
+),
+baseline AS (
+    SELECT
+        query_id,
+        -- execution-weighted average over the baseline period
+        SUM(metric_val * count_executions) / NULLIF(SUM(count_executions), 0)
+            AS base_metric,
+        SUM(count_executions) AS base_execs
+    FROM stats
+    WHERE start_time <  @recent_start
+    GROUP BY query_id
+),
+recent AS (
+    SELECT
+        query_id,
+        SUM(metric_val * count_executions) / NULLIF(SUM(count_executions), 0)
+            AS recent_metric,
+        SUM(count_executions) AS recent_execs
+    FROM stats
+    WHERE start_time >= @recent_start
+    GROUP BY query_id
+)
+SELECT TOP (CAST(? AS INT))
+    r.query_id,
+    CAST(qt.query_sql_text AS NVARCHAR(1000)) AS query_text_sample,
+    b.base_metric,
+    r.recent_metric,
+    CASE WHEN b.base_metric > 0
+         THEN (r.recent_metric - b.base_metric) / b.base_metric
+         ELSE NULL END AS pct_change,
+    b.base_execs,
+    r.recent_execs
+FROM recent r
+JOIN baseline b ON r.query_id = b.query_id
+JOIN sys.query_store_query q ON q.query_id = r.query_id
+JOIN sys.query_store_query_text qt ON q.query_text_id = qt.query_text_id
+WHERE b.base_metric > 0
+  AND b.base_execs   >= ?
+  AND r.recent_execs >= ?
+  -- regression threshold: recent is at least X% worse than baseline
+  AND (r.recent_metric - b.base_metric) / b.base_metric >= ?
+ORDER BY (r.recent_metric - b.base_metric) / b.base_metric DESC;
+"""
+
+
+# get_query_execution_plan: returns the plan XML and the compiled plans for a
+# query_id. Missing-index / warning parsing is done in Python from the XML.
+EXECUTION_PLAN_SQL = """
+SET NOCOUNT ON;
+
+SELECT
+    p.plan_id,
+    p.query_id,
+    p.query_plan,                         -- XML showplan
+    p.is_forced_plan,
+    p.count_compiles,
+    -- pyodbc cannot convert datetimeoffset (SQL type -155); return as ISO string.
+    CONVERT(NVARCHAR(34), p.last_compile_start_time, 127) AS last_compile_start_time,
+    CAST(qt.query_sql_text AS NVARCHAR(MAX)) AS query_sql_text
+FROM sys.query_store_plan p
+JOIN sys.query_store_query q ON p.query_id = q.query_id
+JOIN sys.query_store_query_text qt ON q.query_text_id = qt.query_text_id
+WHERE p.query_id = ?
+ORDER BY p.last_compile_start_time DESC;
+"""
+
+# analyze_parameter_sniffing: find query_ids that have multiple plans AND high
+# runtime variance across those plans — the classic sniffing signature (one query,
+# several plans, wildly different durations). We use the stdev columns Query Store
+# already stores, so no XML parsing is needed here.
+#
+# Bound parameter order (text order):
+#   1: min_plan_count   (HAVING COUNT(DISTINCT plan_id) >= ?)
+#   2: top_n            (SELECT TOP)
+PARAMETER_SNIFFING_SQL = """
+SET NOCOUNT ON;
+
+WITH plan_stats AS (
+    SELECT
+        q.query_id,
+        rs.plan_id,
+        SUM(rs.count_executions) AS execs,
+        -- execution-weighted mean duration for this plan
+        SUM(rs.avg_duration * rs.count_executions)
+            / NULLIF(SUM(rs.count_executions), 0) AS mean_duration,
+        -- max stdev observed for this plan (per-interval stdev, take the worst)
+        MAX(rs.stdev_duration) AS max_stdev_duration
+    FROM sys.query_store_runtime_stats rs
+    JOIN sys.query_store_plan p ON rs.plan_id = p.plan_id
+    JOIN sys.query_store_query q ON p.query_id = q.query_id
+    GROUP BY q.query_id, rs.plan_id
+),
+agg AS (
+    SELECT
+        query_id,
+        COUNT(DISTINCT plan_id) AS plan_count,
+        SUM(execs)              AS total_execs,
+        MIN(mean_duration)      AS min_plan_mean_duration,
+        MAX(mean_duration)      AS max_plan_mean_duration,
+        MAX(max_stdev_duration) AS worst_stdev_duration
+    FROM plan_stats
+    GROUP BY query_id
+    HAVING COUNT(DISTINCT plan_id) >= ?
+)
+SELECT TOP (CAST(? AS INT))
+    a.query_id,
+    a.plan_count,
+    a.total_execs,
+    a.min_plan_mean_duration,
+    a.max_plan_mean_duration,
+    -- ratio of the slowest plan's mean to the fastest: bigger = more suspicious
+    CASE WHEN a.min_plan_mean_duration > 0
+         THEN a.max_plan_mean_duration / a.min_plan_mean_duration
+         ELSE NULL END AS duration_ratio,
+    a.worst_stdev_duration,
+    CAST(qt.query_sql_text AS NVARCHAR(1000)) AS query_text_sample
+FROM agg a
+JOIN sys.query_store_query q ON q.query_id = a.query_id
+JOIN sys.query_store_query_text qt ON q.query_text_id = qt.query_text_id
+ORDER BY duration_ratio DESC;
+"""
+
+
+# get_missing_index_impact: the missing-index impact score lives inside the plan
+# XML, not in any column. So we fetch the most recent plans (bounded) and let the
+# Python side parse + aggregate + rank. This query just returns candidate plans.
+#
+# Bound parameter order (text order):
+#   1: plan_scan_limit  (SELECT TOP — how many recent plans to scan for indexes)
+MISSING_INDEX_PLANS_SQL = """
+SET NOCOUNT ON;
+
+SELECT TOP (CAST(? AS INT))
+    p.plan_id,
+    p.query_id,
+    p.query_plan,
+    CAST(qt.query_sql_text AS NVARCHAR(1000)) AS query_text_sample
+FROM sys.query_store_plan p
+JOIN sys.query_store_query q ON p.query_id = q.query_id
+JOIN sys.query_store_query_text qt ON q.query_text_id = qt.query_text_id
+WHERE p.query_plan LIKE '%<MissingIndexes>%'
+ORDER BY p.last_execution_time DESC;
+"""
+
+# get_wait_stats: aggregate query wait time by wait category over a time window.
+# Answers "why is it slow" (CPU vs blocking vs IO vs memory) rather than "what is
+# slow". Per MS docs, wait rows must be de-duplicated by grouping on plan_id,
+# interval, execution_type and wait_category before summing, or flushed + in-memory
+# rows double-count. We aggregate to the wait_category level across the window.
+#
+# Bound parameter order (text order):
+#   1: recent_hours   (window start)
+#   2: top_n          (SELECT TOP)
+WAIT_STATS_SQL = """
+SET NOCOUNT ON;
+
+DECLARE @window_start DATETIMEOFFSET =
+    DATEADD(HOUR, -CAST(? AS INT), SYSUTCDATETIME());
+
+WITH deduped AS (
+    -- one row per (plan, interval, execution_type, category): MS-recommended grain
+    SELECT
+        ws.plan_id,
+        ws.runtime_stats_interval_id,
+        ws.execution_type,
+        ws.wait_category_desc,
+        SUM(ws.total_query_wait_time_ms) AS total_wait_ms,
+        MAX(ws.max_query_wait_time_ms)   AS max_wait_ms
+    FROM sys.query_store_wait_stats ws
+    JOIN sys.query_store_runtime_stats_interval rsi
+        ON ws.runtime_stats_interval_id = rsi.runtime_stats_interval_id
+    WHERE rsi.start_time >= @window_start
+    GROUP BY ws.plan_id, ws.runtime_stats_interval_id,
+             ws.execution_type, ws.wait_category_desc
+)
+SELECT TOP (CAST(? AS INT))
+    wait_category_desc,
+    SUM(total_wait_ms)              AS total_wait_ms,
+    MAX(max_wait_ms)               AS max_wait_ms,
+    COUNT(DISTINCT plan_id)        AS distinct_plans
+FROM deduped
+GROUP BY wait_category_desc
+ORDER BY SUM(total_wait_ms) DESC;
+"""
+
+# list_querystore_databases: enumerate online databases with Query Store actually
+# ON, so the sweep skips DBs that would error or return nothing. Runs in the
+# server context (master); no USE needed. sys.databases is server-scoped.
+LIST_QS_DATABASES_SQL = """
+SET NOCOUNT ON;
+
+SELECT name
+FROM sys.databases
+WHERE state_desc = 'ONLINE'
+  AND database_id > 4            -- skip system DBs
+  AND is_query_store_on = 1
+ORDER BY name;
+"""

mcp_sql_querystore/server.py

@@ -0,0 +1,504 @@
+"""MCP server exposing read-only Query Store diagnostics.
+
+Run with:  python -m mcp_sql_querystore.server
+Requires:  MCP_SQL_CONNECTION_STRING set to a dedicated read-only login.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import mcp.types as types
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+
+from . import queries
+from .db import run_query
+from .plan_parser import summarize_plan
+
+app: Server = Server("mcp-sql-querystore")
+
+
+# --- Tool catalog -------------------------------------------------------------
+
+
+@app.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="get_regressed_queries",
+            description=(
+                "Detect queries whose performance regressed by comparing a recent "
+                "period against an earlier baseline period from Query Store."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "database_name": {
+                        "type": "string",
+                        "description": "Target SQL Server database name.",
+                    },
+                    "metric": {
+                        "type": "string",
+                        "enum": list(queries.METRIC_COLUMNS.keys()),
+                        "default": "cpu_time",
+                        "description": "Metric to evaluate regression against.",
+                    },
+                    "recent_hours": {
+                        "type": "integer",
+                        "default": 24,
+                        "description": "Length of the recent window, in hours.",
+                    },
+                    "baseline_hours": {
+                        "type": "integer",
+                        "default": 168,
+                        "description": "Length of the baseline window preceding the "
+                        "recent window, in hours (default 7 days).",
+                    },
+                    "regression_threshold": {
+                        "type": "number",
+                        "default": 0.5,
+                        "description": "Minimum fractional worsening to flag "
+                        "(0.5 = 50% worse than baseline).",
+                    },
+                    "min_executions": {
+                        "type": "integer",
+                        "default": 5,
+                        "description": "Ignore queries with fewer executions than "
+                        "this in either period (filters noise).",
+                    },
+                    "top_n": {
+                        "type": "integer",
+                        "default": 10,
+                        "description": "Max rows to return.",
+                    },
+                },
+                "required": ["database_name"],
+            },
+        ),
+        types.Tool(
+            name="get_query_execution_plan",
+            description=(
+                "Fetch execution plan(s) for a Query Store query_id and return a "
+                "compact summary (missing indexes, warnings, lookups) plus optional "
+                "raw XML."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "database_name": {
+                        "type": "string",
+                        "description": "Target SQL Server database name.",
+                    },
+                    "query_id": {
+                        "type": "integer",
+                        "description": "Query Store Query ID.",
+                    },
+                    "include_xml": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Include raw showplan XML alongside summary.",
+                    },
+                },
+                "required": ["database_name", "query_id"],
+            },
+        ),
+        types.Tool(
+            name="analyze_parameter_sniffing",
+            description=(
+                "Detect queries whose runtime varies widely across multiple compiled "
+                "plans — the classic parameter-sniffing signature. Ranks by the ratio "
+                "of slowest to fastest plan mean duration."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "database_name": {
+                        "type": "string",
+                        "description": "Target SQL Server database name.",
+                    },
+                    "min_plan_count": {
+                        "type": "integer",
+                        "default": 2,
+                        "description": "Minimum distinct plans for a query to be "
+                        "considered (2 = at least two plans).",
+                    },
+                    "top_n": {
+                        "type": "integer",
+                        "default": 10,
+                        "description": "Max rows to return.",
+                    },
+                },
+                "required": ["database_name"],
+            },
+        ),
+        types.Tool(
+            name="get_missing_index_impact",
+            description=(
+                "Aggregate missing-index recommendations found in Query Store plans, "
+                "ranked by the optimizer's estimated impact score. Groups duplicate "
+                "recommendations across queries."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "database_name": {
+                        "type": "string",
+                        "description": "Target SQL Server database name.",
+                    },
+                    "top_n": {
+                        "type": "integer",
+                        "default": 10,
+                        "description": "Max index recommendations to return.",
+                    },
+                    "plan_scan_limit": {
+                        "type": "integer",
+                        "default": 200,
+                        "description": "How many recent plans (that contain missing "
+                        "indexes) to scan and aggregate. Higher = more thorough, slower.",
+                    },
+                },
+                "required": ["database_name"],
+            },
+        ),
+        types.Tool(
+            name="get_wait_stats",
+            description=(
+                "Aggregate query wait time by wait category over a time window — shows "
+                "WHY queries are slow (CPU, blocking/locks, IO, memory, etc.) rather "
+                "than which are slow. Ranked by total wait time."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "database_name": {
+                        "type": "string",
+                        "description": "Target SQL Server database name.",
+                    },
+                    "recent_hours": {
+                        "type": "integer",
+                        "default": 24,
+                        "description": "Lookback window in hours.",
+                    },
+                    "top_n": {
+                        "type": "integer",
+                        "default": 10,
+                        "description": "Max wait categories to return.",
+                    },
+                },
+                "required": ["database_name"],
+            },
+        ),
+        types.Tool(
+            name="sweep_regressions",
+            description=(
+                "Run regression detection across ALL online databases that have Query "
+                "Store enabled, and return the worst regressions found per database. "
+                "Use this to triage a whole instance instead of one database at a time."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "metric": {
+                        "type": "string",
+                        "enum": list(queries.METRIC_COLUMNS.keys()),
+                        "default": "cpu_time",
+                        "description": "Metric to evaluate regression against.",
+                    },
+                    "recent_hours": {
+                        "type": "integer",
+                        "default": 24,
+                        "description": "Length of the recent window, in hours.",
+                    },
+                    "baseline_hours": {
+                        "type": "integer",
+                        "default": 168,
+                        "description": "Length of the baseline window, in hours.",
+                    },
+                    "regression_threshold": {
+                        "type": "number",
+                        "default": 0.5,
+                        "description": "Minimum fractional worsening to flag.",
+                    },
+                    "min_executions": {
+                        "type": "integer",
+                        "default": 5,
+                        "description": "Ignore queries below this execution count.",
+                    },
+                    "top_n_per_db": {
+                        "type": "integer",
+                        "default": 3,
+                        "description": "Max regressed queries to return per database.",
+                    },
+                    "database_names": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Optional explicit list of databases to sweep. "
+                        "If omitted, sweeps all Query Store-enabled online databases.",
+                    },
+                },
+                "required": [],
+            },
+        ),
+    ]
+
+
+# --- Tool dispatch ------------------------------------------------------------
+
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> list[types.TextContent]:
+    try:
+        if name == "get_regressed_queries":
+            result = _get_regressed_queries(arguments)
+        elif name == "get_query_execution_plan":
+            result = _get_query_execution_plan(arguments)
+        elif name == "analyze_parameter_sniffing":
+            result = _analyze_parameter_sniffing(arguments)
+        elif name == "get_missing_index_impact":
+            result = _get_missing_index_impact(arguments)
+        elif name == "get_wait_stats":
+            result = _get_wait_stats(arguments)
+        elif name == "sweep_regressions":
+            result = _sweep_regressions(arguments)
+        else:
+            raise ValueError(f"Unknown tool: {name}")
+    except Exception as exc:  # surface a clean error to the agent
+        result = {"error": type(exc).__name__, "message": str(exc)}
+
+    return [types.TextContent(type="text", text=json.dumps(result, default=str, indent=2))]
+
+
+def _run_regression(
+    database: str,
+    metric: str,
+    recent_hours: int,
+    baseline_hours: int,
+    min_executions: int,
+    threshold: float,
+    top_n: int,
+    tool: str = "get_regressed_queries",
+) -> list[dict[str, Any]]:
+    """Core regression query for one database. Single source of truth for the
+    parameter binding order, reused by both the single-DB tool and the sweep."""
+    if metric not in queries.METRIC_COLUMNS:
+        raise ValueError(f"Unsupported metric: {metric}")
+    metric_column = queries.METRIC_COLUMNS[metric]  # whitelisted, safe to interpolate
+    sql = queries.regressed_queries_sql(metric_column)
+
+    # Params bound in the ORDER THE ? PLACEHOLDERS APPEAR in the SQL text:
+    #   1: recent_start DATEADD           (recent_hours)
+    #   2: baseline_start recent portion  (recent_hours)
+    #   3: baseline_start baseline portion(baseline_hours)
+    #   4: SELECT TOP                     (top_n)
+    #   5: baseline exec floor            (min_executions)
+    #   6: recent exec floor              (min_executions)
+    #   7: regression threshold           (threshold)
+    params = (
+        recent_hours,
+        recent_hours,
+        baseline_hours,
+        top_n,
+        min_executions,
+        min_executions,
+        threshold,
+    )
+    return run_query(sql, params, database=database, tool=tool)
+
+
+def _get_regressed_queries(args: dict[str, Any]) -> dict[str, Any]:
+    metric = args.get("metric", "cpu_time")
+    rows = _run_regression(
+        database=args["database_name"],
+        metric=metric,
+        recent_hours=int(args.get("recent_hours", 24)),
+        baseline_hours=int(args.get("baseline_hours", 168)),
+        min_executions=int(args.get("min_executions", 5)),
+        threshold=float(args.get("regression_threshold", 0.5)),
+        top_n=int(args.get("top_n", 10)),
+    )
+    return {"metric": metric, "count": len(rows), "regressed_queries": rows}
+
+
+def _get_query_execution_plan(args: dict[str, Any]) -> dict[str, Any]:
+    rows = run_query(
+        queries.EXECUTION_PLAN_SQL,
+        (int(args["query_id"]),),
+        database=args["database_name"],
+        tool="get_query_execution_plan",
+    )
+    include_xml = bool(args.get("include_xml", False))
+    plans = []
+    for row in rows:
+        xml = row.get("query_plan") or ""
+        entry: dict[str, Any] = {
+            "plan_id": row.get("plan_id"),
+            "is_forced_plan": row.get("is_forced_plan"),
+            "count_compiles": row.get("count_compiles"),
+            "summary": summarize_plan(xml) if xml else {"error": "no plan xml"},
+        }
+        if include_xml:
+            entry["query_plan_xml"] = xml
+        plans.append(entry)
+    return {
+        "query_id": args["query_id"],
+        "plan_count": len(plans),
+        "plans": plans,
+    }
+
+
+def _analyze_parameter_sniffing(args: dict[str, Any]) -> dict[str, Any]:
+    min_plan_count = int(args.get("min_plan_count", 2))
+    top_n = int(args.get("top_n", 10))
+    # Bound params in text order: min_plan_count (HAVING), then top_n (TOP).
+    rows = run_query(
+        queries.PARAMETER_SNIFFING_SQL,
+        (min_plan_count, top_n),
+        database=args["database_name"],
+        tool="analyze_parameter_sniffing",
+    )
+    return {"count": len(rows), "suspected_sniffing": rows}
+
+
+def _get_missing_index_impact(args: dict[str, Any]) -> dict[str, Any]:
+    top_n = int(args.get("top_n", 10))
+    plan_scan_limit = int(args.get("plan_scan_limit", 200))
+    rows = run_query(
+        queries.MISSING_INDEX_PLANS_SQL,
+        (plan_scan_limit,),
+        database=args["database_name"],
+        tool="get_missing_index_impact",
+    )
+
+    # Aggregate missing-index recommendations across the scanned plans. The impact
+    # score and column set come from the plan XML (parsed by summarize_plan). We key
+    # duplicates by (table, equality, inequality, included) so the same suggested
+    # index across many queries is combined rather than listed repeatedly.
+    aggregated: dict[tuple, dict[str, Any]] = {}
+    for row in rows:
+        xml = row.get("query_plan") or ""
+        if not xml:
+            continue
+        for mi in summarize_plan(xml).get("missing_indexes", []):
+            cols = mi.get("columns", {})
+            key = (
+                mi.get("table"),
+                tuple(cols.get("equality", [])),
+                tuple(cols.get("inequality", [])),
+                tuple(cols.get("included", [])),
+            )
+            impact = mi.get("impact_pct") or 0.0
+            if key not in aggregated:
+                aggregated[key] = {
+                    "table": mi.get("table"),
+                    "schema": mi.get("schema"),
+                    "database": mi.get("database"),
+                    "equality_columns": cols.get("equality", []),
+                    "inequality_columns": cols.get("inequality", []),
+                    "included_columns": cols.get("included", []),
+                    "max_impact_pct": impact,
+                    "occurrences": 0,
+                }
+            entry = aggregated[key]
+            entry["occurrences"] += 1
+            entry["max_impact_pct"] = max(entry["max_impact_pct"], impact)
+
+    # Rank by impact first, then by how often the recommendation recurs.
+    ranked = sorted(
+        aggregated.values(),
+        key=lambda e: (e["max_impact_pct"], e["occurrences"]),
+        reverse=True,
+    )[:top_n]
+    return {
+        "plans_scanned": len(rows),
+        "distinct_recommendations": len(aggregated),
+        "recommendations": ranked,
+    }
+
+
+def _get_wait_stats(args: dict[str, Any]) -> dict[str, Any]:
+    recent_hours = int(args.get("recent_hours", 24))
+    top_n = int(args.get("top_n", 10))
+    # Bound params in text order: recent_hours (window), then top_n (TOP).
+    rows = run_query(
+        queries.WAIT_STATS_SQL,
+        (recent_hours, top_n),
+        database=args["database_name"],
+        tool="get_wait_stats",
+    )
+    return {"recent_hours": recent_hours, "count": len(rows), "wait_categories": rows}
+
+
+def _sweep_regressions(args: dict[str, Any]) -> dict[str, Any]:
+    metric = args.get("metric", "cpu_time")
+    recent_hours = int(args.get("recent_hours", 24))
+    baseline_hours = int(args.get("baseline_hours", 168))
+    min_executions = int(args.get("min_executions", 5))
+    threshold = float(args.get("regression_threshold", 0.5))
+    top_n_per_db = int(args.get("top_n_per_db", 3))
+
+    # Determine the database set: explicit list, or auto-enumerate QS-enabled DBs.
+    explicit = args.get("database_names")
+    if explicit:
+        databases = [str(d) for d in explicit]
+    else:
+        # is_query_store_on in sys.databases is a cached bit and can be stale after
+        # AG/mirroring failover, so a DB may pass this filter yet error on query —
+        # that per-DB error is caught below and reported, not fatal to the sweep.
+        db_rows = run_query(queries.LIST_QS_DATABASES_SQL, tool="sweep_regressions")  # server context
+        databases = [r["name"] for r in db_rows]
+
+    results: list[dict[str, Any]] = []
+    errors: list[dict[str, Any]] = []
+    for db in databases:
+        try:
+            rows = _run_regression(
+                database=db,
+                metric=metric,
+                tool="sweep_regressions",
+                recent_hours=recent_hours,
+                baseline_hours=baseline_hours,
+                min_executions=min_executions,
+                threshold=threshold,
+                top_n=top_n_per_db,
+            )
+            if rows:  # only report databases that actually have regressions
+                results.append({"database": db, "regression_count": len(rows),
+                                "top_regressions": rows})
+        except Exception as exc:
+            # One bad database must not sink the whole sweep.
+            errors.append({"database": db, "error": type(exc).__name__,
+                           "message": str(exc)})
+
+    # Databases with the worst single regression first.
+    results.sort(
+        key=lambda r: max((abs(q.get("pct_change") or 0) for q in r["top_regressions"]),
+                          default=0),
+        reverse=True,
+    )
+    return {
+        "metric": metric,
+        "databases_scanned": len(databases),
+        "databases_with_regressions": len(results),
+        "results": results,
+        "errors": errors,
+    }
+
+
+async def main() -> None:
+    async with stdio_server() as (read_stream, write_stream):
+        await app.run(read_stream, write_stream, app.create_initialization_options())
+
+
+def run() -> None:
+    """Synchronous entry point for the console script. The console script in
+    pyproject.toml must point here, not at the async `main`, or invoking the
+    command just creates a coroutine and never awaits it."""
+    import asyncio
+
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    run()

mcp_sql_querystore-0.1.0.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.5
+Name: mcp-sql-querystore
+Version: 0.1.0
+Summary: Read-only MCP server for SQL Server performance diagnostics over Query Store, DMVs, and execution plans
+Project-URL: Homepage, https://github.com/deepeshd87/mcp-sql-querystore
+Project-URL: Repository, https://github.com/deepeshd87/mcp-sql-querystore
+Project-URL: Issues, https://github.com/deepeshd87/mcp-sql-querystore/issues
+Author: Deepesh Dhake
+License: MIT
+Keywords: database,dba,mcp,model-context-protocol,mssql,performance-tuning,query-store,sql-server
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.2.0
+Requires-Dist: pyodbc>=5.1.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mcp-sql-querystore
+
+Read-only MCP server exposing SQL Server Query Store diagnostics to LLM agents.
+
+Six read-only diagnostic tools over Query Store, DMVs, and execution plans. The
+tools have been validated against a live SQL Server instance and are covered by a
+unit + integration test suite. Still validate against a non-prod instance of your
+own before pointing it at production, especially on SQL Server versions other than
+those noted under caveats.
+
+## Quickstart
+
+1. **Provision a read-only login.** Run `provisioning/create_readonly_login.sql`
+   against your instance (edit names first). This login's permissions are the
+   read-only guarantee — see the security model below.
+2. **Install.** `pip install -e .` in a virtual environment. ODBC Driver 18 for
+   SQL Server must be installed on the host.
+3. **Store the password outside the repo.** Put it in a plain-text file somewhere
+   the repo can't reach (not under the project folder):
+
+       # Windows PowerShell, UTF-8, password only, no quotes/newline
+       New-Item -ItemType Directory -Force C:\Users\you\secrets | Out-Null
+       Set-Content -NoNewline -Encoding utf8 C:\Users\you\secrets\mcp_sql.pwd 'your-password'
+
+   Or skip the password entirely with integrated auth (`MCP_SQL_TRUSTED=yes`) —
+   preferred for CJIS/PCI. See **Secret handling** below for all options.
+4. **Configure your MCP client.** Copy the `sql-querystore` block from
+   `claude_desktop_config.example.json` into your real Claude Desktop config
+   (Windows: `%APPDATA%\Claude\claude_desktop_config.json`), then replace the
+   placeholder paths, server name, and `MCP_SQL_PWD_FILE`. Set
+   `MCP_SQL_TRUST_CERT=yes` only for a self-signed/local cert; leave it `no`
+   against instances with proper certificates.
+5. **Restart your MCP client** and confirm the server shows as running.
+
+Never commit your real config or your password file. `.gitignore` already
+excludes `*.pwd`, `.env`, and `claude_desktop_config.json`.
+
+## Security model (read this first)
+
+The read-only guarantee comes from **the SQL login's permissions**, not from any
+code in this repo:
+
+- Provision a dedicated login with `VIEW DATABASE STATE` (and `VIEW SERVER STATE`
+  only if you use server-scoped DMVs) and **nothing else** — no `db_datareader`,
+  no `SELECT` on user tables. See `provisioning/create_readonly_login.sql`.
+- The keyword screen in `db.py` and the fixed SELECT-only query text are
+  **defense-in-depth**, not the primary control.
+- `ApplicationIntent=ReadOnly` in the connection string only routes to a readable
+  secondary in an availability group. On a standalone instance it does not make
+  the session read-only. Do not rely on it for safety.
+- Credentials never belong in code. The simplest setup uses the
+  `MCP_SQL_CONNECTION_STRING` env var, but for CJIS/PCI environments prefer
+  integrated auth or a file/secret-store-sourced password — see the
+  **Secret handling** section below.
+- Every query is recorded via the audit logger — see **Audit logging** below. In
+  a regulated environment, route that logger to a durable file or SIEM.
+
+## Setup
+
+ODBC Driver 18 for SQL Server must be installed on the host. Install the package,
+then configure the connection via environment variables (see **Secret handling**
+for all options). The recommended form keeps the password in a file, not inline:
+
+```powershell
+pip install -e .
+
+# PowerShell — connection assembled from parts, password read from a file
+$env:MCP_SQL_SERVER      = "yourhost\INSTANCE"
+$env:MCP_SQL_DATABASE    = "master"
+$env:MCP_SQL_UID         = "mcp_readonly"
+$env:MCP_SQL_PWD_FILE    = "C:\path\to\your\secret.pwd"
+$env:MCP_SQL_TRUST_CERT  = "no"   # "yes" only for a self-signed/local cert
+
+python -m mcp_sql_querystore.server
+```
+
+Or use integrated auth with no stored password at all (`MCP_SQL_TRUSTED=yes`).
+A full `MCP_SQL_CONNECTION_STRING` is also accepted for simple cases — see
+**Secret handling**.
+
+Register it with your MCP client (e.g. Claude Desktop) as an stdio server
+invoking `python -m mcp_sql_querystore.server`; see
+`claude_desktop_config.example.json`.
+
+## Tools
+
+All tools are read-only and take a `database_name` (except `sweep_regressions`,
+which can sweep all databases). Each returns JSON, or a structured error dict on
+failure rather than raising.
+
+- **get_regressed_queries** — compares a recent window against an earlier
+  baseline window per query and flags those worse by at least
+  `regression_threshold`. A real baseline-vs-recent comparison, not a top-CPU list.
+- **get_query_execution_plan** — returns compiled plans for a `query_id` with a
+  compact JSON summary (missing indexes, warnings incl. implicit conversions,
+  key lookups) and optional raw XML.
+- **analyze_parameter_sniffing** — finds queries with multiple compiled plans and
+  ranks them by the ratio of slowest to fastest plan mean duration — the classic
+  parameter-sniffing signature.
+- **get_missing_index_impact** — scans recent plans containing missing-index
+  recommendations, parses the impact score from the plan XML, and aggregates
+  duplicate recommendations across queries, ranked by impact then recurrence.
+- **get_wait_stats** — aggregates query wait time by wait category over a window,
+  showing *why* queries are slow (CPU, blocking/locks, IO, memory) rather than
+  which. De-duplicates flushed vs in-memory rows per Microsoft guidance.
+- **sweep_regressions** — runs regression detection across all Query Store-enabled
+  online databases (or an explicit `database_names` list) and returns the worst
+  per database, ranked. One failing database does not abort the sweep; its error
+  is collected and reported.
+
+## Example prompts
+
+Once the server is connected to your MCP client, you drive the tools in plain
+language. Name the target database in the prompt (except `sweep_regressions`,
+which can scan all of them). Replace `YourDB` with your database name.
+
+**Wait stats — why queries are slow**
+- "What are the top wait categories in YourDB over the last week?"
+- "Is YourDB waiting on CPU, memory, or IO?"
+- "Show me wait stats for YourDB over the last 24 hours."
+
+**Execution plans**
+- "Get the execution plan for query_id 10 in YourDB and summarize it."
+- "Does query_id 13 in YourDB have missing index recommendations?"
+- "Are there implicit conversion warnings in query 12's plan in YourDB?"
+
+**Regression analysis**
+- "Check YourDB for CPU regressions over the last 24 hours."
+- "Which queries in YourDB regressed by more than 30%?"
+- "Find duration regressions in YourDB, ignoring anything with fewer than 10 executions."
+
+**Parameter sniffing**
+- "Check YourDB for parameter sniffing."
+- "Which queries in YourDB have unstable plans?"
+
+**Missing indexes**
+- "What missing indexes does YourDB need most?"
+- "Show me the top 10 index recommendations for YourDB by impact."
+
+**Multi-database sweep (no database name needed)**
+- "Sweep all my databases for CPU regressions."
+- "Which database has the worst regressions this week?"
+
+**Combined — chaining tools in one turn**
+- "Find the biggest CPU regression in YourDB, pull its plan, and tell me why it might have regressed."
+- "YourDB feels slow — diagnose it." (wait stats → regressions → plans)
+- "Full performance triage of YourDB: wait stats, top regressions, and missing indexes."
+
+## Known caveats / TODO
+
+- **Version differences.** Query Store column names assume SQL Server 2019+/2022
+  and Azure SQL MI. Verify against 2016/2017 if you target those.
+- **Regression semantics.** Current logic uses execution-weighted averages. You
+  may prefer percentile-based comparison (Query Store doesn't store percentiles
+  directly, so that needs `*_stdev` columns and assumptions).
+- **Not time-windowed:** `analyze_parameter_sniffing` aggregates across all Query
+  Store history; on busy databases consider adding a `recent_hours` filter like
+  the other tools have.
+- **Remaining hardening:** connection retry with backoff, and version-aware column
+  handling for mixed 2016/2017/2019/2022 fleets.
+
+## Secret handling
+
+The connection string is resolved in this order, so the password need not sit in
+plaintext config:
+
+1. `MCP_SQL_CONNECTION_STRING` — the full string (simplest; back-compat).
+2. `MCP_SQL_CONNECTION_STRING_FILE` — path to a file holding the full string
+   (Docker/K8s secret-mount style).
+3. Assembled from parts: `MCP_SQL_SERVER` (+ `MCP_SQL_DATABASE`, `MCP_SQL_DRIVER`,
+   `MCP_SQL_ENCRYPT`, `MCP_SQL_TRUST_CERT`, `MCP_SQL_EXTRA`). Auth is either:
+   - **Integrated** (preferred for CJIS/PCI — no password stored): `MCP_SQL_TRUSTED=yes`.
+   - **SQL auth**: `MCP_SQL_UID` plus the password from `MCP_SQL_PWD_FILE` (a
+     vault-mounted file), `MCP_SQL_PWD_ENV` (name of another env var), or
+     `MCP_SQL_PWD` (direct; least preferred).
+
+Timeouts: `MCP_SQL_CONNECT_TIMEOUT` (default 10s) and `MCP_SQL_QUERY_TIMEOUT`
+(default 30s, 0 disables).
+
+## Audit logging
+
+Every query attempt is logged via the `mcp_sql_querystore.audit` logger: tool,
+database, a 12-char hash of the SQL (not the text), row count, elapsed ms, and
+outcome. Connection strings, SQL text, and parameter values are never logged.
+Configure a handler for that logger to route the audit trail to a file or SIEM.
+
+## Testing
+
+Unit tests (no database, safe in CI):
+
+    pip install -e ".[test]"
+    pytest
+
+Integration tests (real instance, opt-in):
+
+    # set a working connection (any form above), then:
+    $env:MCP_SQL_TEST_DATABASE = "RAG"
+    $env:MCP_SQL_RUN_INTEGRATION = "1"
+    pytest tests/test_integration.py -v

mcp_sql_querystore-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+mcp_sql_querystore/__init__.py,sha256=17bkvpLjjo2E8PrbLs5YHZOwEOKkaM2p5NQVEQaa9zU,110
+mcp_sql_querystore/db.py,sha256=938cnNIIq2v5F5Wr35BGi4-j0yMBuqs85e9Tqigbn_M,9956
+mcp_sql_querystore/plan_parser.py,sha256=QwG-gzcazerpiLe6xpdD20D3aovKDn-dUYi73Ug_OPI,3617
+mcp_sql_querystore/queries.py,sha256=mCCP2t5_ChfibfdeFji2qRFMgLBYrrDfYGGUG5xaPF0,9524
+mcp_sql_querystore/server.py,sha256=-LU7DPjE1JM7pDPLaXtwzh30ZCuNLoBcZodbMY9QPlE,19729
+mcp_sql_querystore-0.1.0.dist-info/METADATA,sha256=GmdMx2Nt-ozCzV7BgLrD2K1Wz3Ulah5XtABIW5K6TdE,10613
+mcp_sql_querystore-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+mcp_sql_querystore-0.1.0.dist-info/entry_points.txt,sha256=OhWq9ia51RlL9-TYX3xGFXdq8QqhATlSl6mV_aDcZY4,69
+mcp_sql_querystore-0.1.0.dist-info/RECORD,,

mcp_sql_querystore-0.1.0.dist-info/WHEEL

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

mcp_sql_querystore-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-sql-querystore = mcp_sql_querystore.server:run