sqlserver-semantic-mcp 0.5.0__py3-none-any.whl

sqlserver_semantic_mcp/infrastructure/cache/structural.py

@@ -0,0 +1,203 @@
+import hashlib
+import json
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+import aiosqlite
+
+from ...config import Config
+from ..connection import open_connection
+from ..queries.metadata_queries import (
+    GET_TABLES, GET_COLUMNS, GET_PRIMARY_KEYS,
+    GET_FOREIGN_KEYS, GET_INDEXES, GET_OBJECTS,
+)
+from ..queries.comment_queries import GET_COMMENTS
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class StructuralSnapshot:
+    tables: list[tuple]          # (schema, table)
+    columns: list[tuple]         # (schema, table, col, type, maxlen, nullable, default, ordinal)
+    primary_keys: list[tuple]    # (schema, table, col)
+    foreign_keys: list[tuple]    # (schema, table, col, ref_schema, ref_table, ref_col)
+    indexes: list[tuple]         # (schema, table, index_name, is_unique, is_pk, cols)
+    objects: list[tuple]         # (schema, name, type)
+    comments: list[tuple]        # (schema, object, column, description)
+
+
+def _sha256(obj: Any) -> str:
+    payload = json.dumps(obj, sort_keys=True, default=str)
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def compute_structural_hash(
+    tables, columns, primary_keys, foreign_keys, indexes,
+) -> str:
+    return _sha256({
+        "tables": sorted([list(t) for t in tables]),
+        "columns": sorted([list(c) for c in columns]),
+        "primary_keys": sorted([list(p) for p in primary_keys]),
+        "foreign_keys": sorted([list(f) for f in foreign_keys]),
+        "indexes": sorted([list(i) for i in indexes]),
+    })
+
+
+def compute_object_hash(objects) -> str:
+    return _sha256({"objects": sorted([list(o) for o in objects])})
+
+
+def compute_comment_hash(comments) -> str:
+    return _sha256({"comments": sorted([list(c) for c in comments])})
+
+
+async def read_schema_version(db_path: str, database: str) -> Optional[dict]:
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cur = await db.execute(
+            "SELECT * FROM schema_version WHERE database_name = ?",
+            (database,),
+        )
+        row = await cur.fetchone()
+        return dict(row) if row else None
+
+
+async def write_structural_snapshot(
+    db_path: str, database: str, snap: StructuralSnapshot,
+) -> dict:
+    structural_hash = compute_structural_hash(
+        snap.tables, snap.columns, snap.primary_keys,
+        snap.foreign_keys, snap.indexes,
+    )
+    object_hash = compute_object_hash(snap.objects)
+    comment_hash = compute_comment_hash(snap.comments)
+    captured_at = datetime.now(timezone.utc).isoformat()
+
+    async with aiosqlite.connect(db_path) as db:
+        await db.execute("BEGIN")
+        try:
+            for tbl in [
+                "sc_tables", "sc_columns", "sc_primary_keys",
+                "sc_foreign_keys", "sc_indexes", "sc_objects", "sc_comments",
+            ]:
+                await db.execute(
+                    f"DELETE FROM {tbl} WHERE database_name = ?", (database,),
+                )
+
+            await db.executemany(
+                "INSERT INTO sc_tables (database_name, schema_name, table_name) "
+                "VALUES (?,?,?)",
+                [(database, s, t) for (s, t) in snap.tables],
+            )
+            await db.executemany(
+                "INSERT INTO sc_columns "
+                "(database_name, schema_name, table_name, column_name, data_type, "
+                "max_length, is_nullable, column_default, ordinal_position) "
+                "VALUES (?,?,?,?,?,?,?,?,?)",
+                [(database, *row) for row in snap.columns],
+            )
+            await db.executemany(
+                "INSERT INTO sc_primary_keys "
+                "(database_name, schema_name, table_name, column_name) "
+                "VALUES (?,?,?,?)",
+                [(database, *row) for row in snap.primary_keys],
+            )
+            await db.executemany(
+                "INSERT INTO sc_foreign_keys "
+                "(database_name, schema_name, table_name, column_name, "
+                "ref_schema, ref_table, ref_column) VALUES (?,?,?,?,?,?,?)",
+                [(database, *row) for row in snap.foreign_keys],
+            )
+            await db.executemany(
+                "INSERT INTO sc_indexes "
+                "(database_name, schema_name, table_name, index_name, "
+                "is_unique, is_primary_key, columns) VALUES (?,?,?,?,?,?,?)",
+                [(database, *row) for row in snap.indexes],
+            )
+            await db.executemany(
+                "INSERT INTO sc_objects "
+                "(database_name, schema_name, object_name, object_type) "
+                "VALUES (?,?,?,?)",
+                [(database, *row) for row in snap.objects],
+            )
+            await db.executemany(
+                "INSERT INTO sc_comments "
+                "(database_name, schema_name, object_name, column_name, description) "
+                "VALUES (?,?,?,?,?)",
+                [(database, *row) for row in snap.comments],
+            )
+
+            await db.execute(
+                "INSERT OR REPLACE INTO schema_version "
+                "(database_name, structural_hash, object_hash, comment_hash, "
+                " captured_at) VALUES (?,?,?,?,?)",
+                (database, structural_hash, object_hash, comment_hash, captured_at),
+            )
+
+            # Cascade: mark stale semantic rows dirty
+            await db.execute(
+                "UPDATE sem_table_analysis SET status='dirty' "
+                "WHERE database_name=? AND structural_hash<>?",
+                (database, structural_hash),
+            )
+            await db.execute(
+                "UPDATE sem_object_definitions SET status='dirty' "
+                "WHERE database_name=? AND object_hash<>?",
+                (database, object_hash),
+            )
+            await db.commit()
+        except Exception:
+            await db.rollback()
+            raise
+
+    return {
+        "structural_hash": structural_hash,
+        "object_hash": object_hash,
+        "comment_hash": comment_hash,
+        "captured_at": captured_at,
+    }
+
+
+def fetch_snapshot_from_server(cfg: Config) -> StructuralSnapshot:
+    queries = (
+        GET_TABLES,
+        GET_COLUMNS,
+        GET_PRIMARY_KEYS,
+        GET_FOREIGN_KEYS,
+        GET_INDEXES,
+        GET_OBJECTS,
+        GET_COMMENTS,
+    )
+    results: list[list[tuple]] = []
+    with open_connection(cfg) as conn:
+        cursor = conn.cursor()
+        try:
+            for sql in queries:
+                cursor.execute(sql)
+                results.append(list(cursor.fetchall()))
+        finally:
+            cursor.close()
+
+    return StructuralSnapshot(
+        tables=results[0],
+        columns=results[1],
+        primary_keys=results[2],
+        foreign_keys=results[3],
+        indexes=results[4],
+        objects=results[5],
+        comments=results[6],
+    )
+
+
+async def warmup_structural_cache(cfg: Config) -> dict:
+    """Fetch snapshot from SQL Server and write to SQLite. Returns hashes."""
+    snap = fetch_snapshot_from_server(cfg)
+    logger.info(
+        "Structural snapshot: %d tables, %d columns, %d FKs, %d objects",
+        len(snap.tables), len(snap.columns),
+        len(snap.foreign_keys), len(snap.objects),
+    )
+    return await write_structural_snapshot(cfg.cache_path, cfg.mssql_database, snap)

sqlserver_semantic_mcp/infrastructure/connection.py

@@ -0,0 +1,78 @@
+import logging
+from contextlib import contextmanager
+from typing import Any, Iterator
+
+import pymssql
+
+from ..config import Config, get_config
+
+logger = logging.getLogger(__name__)
+
+
+def build_pymssql_kwargs(cfg: Config) -> dict[str, Any]:
+    server = cfg.mssql_server
+    if server.lower().startswith("(localdb)\\"):
+        instance = server.split("\\", 1)[1]
+        server = f".\\{instance}"
+
+    kwargs: dict[str, Any] = {
+        "server": server,
+        "database": cfg.mssql_database,
+        "port": cfg.mssql_port,
+    }
+
+    if ".database.windows.net" in server.lower():
+        kwargs["tds_version"] = "7.4"
+
+    if cfg.mssql_encrypt:
+        kwargs["tds_version"] = "7.4"
+
+    if not cfg.mssql_windows_auth:
+        if cfg.mssql_user is None or cfg.mssql_password is None:
+            raise ValueError(
+                "SQL auth requires SEMANTIC_MCP_MSSQL_USER and "
+                "SEMANTIC_MCP_MSSQL_PASSWORD"
+            )
+        kwargs["user"] = cfg.mssql_user
+        kwargs["password"] = cfg.mssql_password
+
+    return kwargs
+
+
+@contextmanager
+def open_connection(cfg: Config | None = None) -> Iterator[Any]:
+    cfg = cfg or get_config()
+    kwargs = build_pymssql_kwargs(cfg)
+    conn = pymssql.connect(**kwargs)
+    try:
+        yield conn
+    finally:
+        conn.close()
+
+
+def fetch_all(cfg: Config, sql: str, params: tuple = ()) -> list[tuple]:
+    with open_connection(cfg) as conn:
+        cursor = conn.cursor()
+        cursor.execute(sql, params)
+        rows = cursor.fetchall()
+        cursor.close()
+        return rows
+
+
+def fetch_one(cfg: Config, sql: str, params: tuple = ()) -> tuple | None:
+    with open_connection(cfg) as conn:
+        cursor = conn.cursor()
+        cursor.execute(sql, params)
+        row = cursor.fetchone()
+        cursor.close()
+        return row
+
+
+def execute(cfg: Config, sql: str, params: tuple = ()) -> int:
+    with open_connection(cfg) as conn:
+        cursor = conn.cursor()
+        cursor.execute(sql, params)
+        affected = cursor.rowcount
+        conn.commit()
+        cursor.close()
+        return affected

sqlserver_semantic_mcp/infrastructure/queries/comment_queries.py

@@ -0,0 +1,18 @@
+GET_COMMENTS = """
+SELECT
+    s.name AS SCHEMA_NAME,
+    o.name AS OBJECT_NAME,
+    COALESCE(c.name, '') AS COLUMN_NAME,
+    CAST(ep.value AS NVARCHAR(MAX)) AS DESCRIPTION
+FROM sys.extended_properties ep
+JOIN sys.objects  o ON ep.major_id = o.object_id
+JOIN sys.schemas  s ON o.schema_id = s.schema_id
+LEFT JOIN sys.columns c
+    ON ep.major_id = c.object_id AND ep.minor_id = c.column_id
+WHERE ep.name = 'MS_Description' AND ep.class = 1
+ORDER BY s.name, o.name, ep.minor_id
+"""
+
+GET_OBJECT_DEFINITION = """
+SELECT OBJECT_DEFINITION(OBJECT_ID(%s))
+"""

sqlserver_semantic_mcp/infrastructure/queries/metadata_queries.py

@@ -0,0 +1,70 @@
+GET_TABLES = """
+SELECT TABLE_SCHEMA, TABLE_NAME
+FROM INFORMATION_SCHEMA.TABLES
+WHERE TABLE_TYPE = 'BASE TABLE'
+ORDER BY TABLE_SCHEMA, TABLE_NAME
+"""
+
+GET_COLUMNS = """
+SELECT
+    TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME,
+    DATA_TYPE, CHARACTER_MAXIMUM_LENGTH,
+    CASE WHEN IS_NULLABLE = 'YES' THEN 1 ELSE 0 END AS IS_NULLABLE,
+    COLUMN_DEFAULT, ORDINAL_POSITION
+FROM INFORMATION_SCHEMA.COLUMNS
+ORDER BY TABLE_SCHEMA, TABLE_NAME, ORDINAL_POSITION
+"""
+
+GET_PRIMARY_KEYS = """
+SELECT tc.TABLE_SCHEMA, tc.TABLE_NAME, kcu.COLUMN_NAME
+FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS tc
+JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE kcu
+    ON tc.CONSTRAINT_NAME = kcu.CONSTRAINT_NAME
+    AND tc.TABLE_SCHEMA = kcu.TABLE_SCHEMA
+WHERE tc.CONSTRAINT_TYPE = 'PRIMARY KEY'
+ORDER BY tc.TABLE_SCHEMA, tc.TABLE_NAME, kcu.ORDINAL_POSITION
+"""
+
+GET_FOREIGN_KEYS = """
+SELECT
+    fk.TABLE_SCHEMA, fk.TABLE_NAME, fk.COLUMN_NAME,
+    pk.TABLE_SCHEMA AS REF_SCHEMA,
+    pk.TABLE_NAME   AS REF_TABLE,
+    pk.COLUMN_NAME  AS REF_COLUMN
+FROM INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS rc
+JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE fk
+    ON rc.CONSTRAINT_NAME = fk.CONSTRAINT_NAME
+JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE pk
+    ON rc.UNIQUE_CONSTRAINT_NAME = pk.CONSTRAINT_NAME
+    AND fk.ORDINAL_POSITION = pk.ORDINAL_POSITION
+ORDER BY fk.TABLE_SCHEMA, fk.TABLE_NAME, fk.ORDINAL_POSITION
+"""
+
+GET_INDEXES = """
+SELECT
+    s.name AS SCHEMA_NAME,
+    t.name AS TABLE_NAME,
+    i.name AS INDEX_NAME,
+    CAST(i.is_unique AS INT),
+    CAST(i.is_primary_key AS INT),
+    STRING_AGG(c.name, ',') WITHIN GROUP (ORDER BY ic.key_ordinal) AS COLS
+FROM sys.indexes i
+JOIN sys.tables t  ON i.object_id = t.object_id
+JOIN sys.schemas s ON t.schema_id = s.schema_id
+JOIN sys.index_columns ic
+    ON i.object_id = ic.object_id AND i.index_id = ic.index_id
+JOIN sys.columns c
+    ON ic.object_id = c.object_id AND ic.column_id = c.column_id
+WHERE i.name IS NOT NULL AND ic.is_included_column = 0
+GROUP BY s.name, t.name, i.name, i.is_unique, i.is_primary_key
+ORDER BY s.name, t.name, i.name
+"""
+
+GET_OBJECTS = """
+SELECT ROUTINE_SCHEMA, ROUTINE_NAME, ROUTINE_TYPE
+FROM INFORMATION_SCHEMA.ROUTINES
+UNION ALL
+SELECT TABLE_SCHEMA, TABLE_NAME, 'VIEW'
+FROM INFORMATION_SCHEMA.VIEWS
+ORDER BY 1, 2, 3
+"""

sqlserver_semantic_mcp/infrastructure/queries/object_queries.py

@@ -0,0 +1,15 @@
+GET_OBJECT_DEFINITION = """
+SELECT OBJECT_DEFINITION(OBJECT_ID(%s))
+"""
+
+GET_OBJECT_DEPENDENCIES = """
+SELECT
+    OBJECT_SCHEMA_NAME(d.referenced_id) AS REF_SCHEMA,
+    OBJECT_NAME(d.referenced_id)        AS REF_NAME,
+    o.type_desc                         AS REF_TYPE
+FROM sys.sql_expression_dependencies d
+LEFT JOIN sys.objects o ON d.referenced_id = o.object_id
+WHERE d.referencing_id = OBJECT_ID(%s)
+  AND d.referenced_id IS NOT NULL
+ORDER BY REF_SCHEMA, REF_NAME
+"""

sqlserver_semantic_mcp/main.py

@@ -0,0 +1,90 @@
+import asyncio
+import logging
+
+from mcp.server.stdio import stdio_server
+
+from .config import get_config
+from .infrastructure.background import background_fill_loop
+from .infrastructure.cache.semantic import enqueue_all_tables
+from .infrastructure.cache.store import init_store
+from .infrastructure.cache.structural import (
+    read_schema_version, warmup_structural_cache,
+)
+from .server.app import app, get_context
+from .server import resources  # noqa: F401
+from .server.prompts import register_prompts
+from .server.tools import register_all
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger("sqlserver_semantic_mcp")
+
+
+async def _startup() -> asyncio.Task | None:
+    cfg = get_config()
+    logger.info(
+        "Starting sqlserver-semantic-mcp against %s/%s",
+        cfg.mssql_server, cfg.mssql_database,
+    )
+
+    await init_store(cfg.cache_path)
+
+    bg_task: asyncio.Task | None = None
+    if cfg.cache_enabled:
+        existing = await read_schema_version(cfg.cache_path, cfg.mssql_database)
+        should_warmup = (
+            cfg.startup_mode == "full"
+            or existing is None
+        )
+        if should_warmup:
+            if existing is None:
+                logger.info("No cache found; running structural warmup")
+            else:
+                logger.info(
+                    "Startup mode '%s' requires a fresh structural warmup "
+                    "(cached_at=%s)",
+                    cfg.startup_mode,
+                    existing["captured_at"],
+                )
+            result = await warmup_structural_cache(cfg)
+            structural_hash = result["structural_hash"]
+        else:
+            logger.info(
+                "Startup mode '%s' reuses existing cache (captured_at=%s)",
+                cfg.startup_mode,
+                existing["captured_at"],
+            )
+            structural_hash = existing["structural_hash"]
+        await enqueue_all_tables(
+            cfg.cache_path, cfg.mssql_database, structural_hash,
+        )
+        bg_task = asyncio.create_task(background_fill_loop(cfg))
+
+    register_all()
+    register_prompts()
+    get_context()
+    return bg_task
+
+
+async def _run() -> None:
+    bg_task = await _startup()
+    try:
+        async with stdio_server() as (r, w):
+            await app.run(r, w, app.create_initialization_options())
+    finally:
+        if bg_task is not None:
+            bg_task.cancel()
+            try:
+                await bg_task
+            except (asyncio.CancelledError, Exception):
+                pass
+
+
+def main() -> None:
+    asyncio.run(_run())
+
+
+if __name__ == "__main__":
+    main()

sqlserver_semantic_mcp/policy/analyzer.py

@@ -0,0 +1,194 @@
+import re
+from dataclasses import dataclass, field
+from typing import List
+
+from ..domain.enums import SqlOperation, RiskLevel
+
+
+@dataclass
+class SqlIntent:
+    primary_operation: SqlOperation
+    has_where_clause: bool
+    has_top_clause: bool
+    affected_tables: List[str] = field(default_factory=list)
+    risk_level: RiskLevel = RiskLevel.LOW
+    is_multi_statement: bool = False
+    statement_count: int = 1
+    # v0.5 heuristics — used by workflow router / risk estimation.
+    is_sql_like: bool = True
+    confidence: float = 0.9
+    requires_discovery: bool = False
+    has_unqualified_tables: bool = False
+    contains_dynamic_sql: bool = False
+    contains_cte: bool = False
+
+
+_OP_MAP = {
+    "SELECT": SqlOperation.SELECT,
+    "INSERT": SqlOperation.INSERT,
+    "UPDATE": SqlOperation.UPDATE,
+    "DELETE": SqlOperation.DELETE,
+    "TRUNCATE": SqlOperation.TRUNCATE,
+    "CREATE": SqlOperation.CREATE,
+    "ALTER": SqlOperation.ALTER,
+    "DROP": SqlOperation.DROP,
+    "EXEC": SqlOperation.EXEC,
+    "EXECUTE": SqlOperation.EXECUTE,
+    "MERGE": SqlOperation.MERGE,
+    "WITH": SqlOperation.SELECT,  # CTE — treat body as SELECT for routing
+}
+
+_IDENT = r"\[?[\w]+\]?(?:\.\[?[\w]+\]?)?"
+
+
+def _strip_comments(sql: str) -> str:
+    sql = re.sub(r"/\*.*?\*/", "", sql, flags=re.DOTALL)
+    sql = re.sub(r"--[^\n]*", "", sql)
+    return sql.strip()
+
+
+def _split_statements(sql: str) -> list[str]:
+    parts = re.split(r";\s*", sql)
+    return [p.strip() for p in parts if p.strip()]
+
+
+def _detect_operation(sql: str) -> SqlOperation:
+    m = re.match(r"\s*([A-Za-z]+)", sql)
+    if not m:
+        return SqlOperation.UNKNOWN
+    return _OP_MAP.get(m.group(1).upper(), SqlOperation.UNKNOWN)
+
+
+def _extract_tables(sql: str, operation: SqlOperation) -> list[str]:
+    tables: list[str] = []
+    tables.extend(re.findall(rf"\bFROM\s+({_IDENT})", sql, re.IGNORECASE))
+    tables.extend(re.findall(rf"\bJOIN\s+({_IDENT})", sql, re.IGNORECASE))
+
+    if operation == SqlOperation.UPDATE:
+        m = re.search(rf"\bUPDATE\s+({_IDENT})", sql, re.IGNORECASE)
+        if m:
+            tables.append(m.group(1))
+    elif operation == SqlOperation.INSERT:
+        m = re.search(rf"\bINTO\s+({_IDENT})", sql, re.IGNORECASE)
+        if m:
+            tables.append(m.group(1))
+    elif operation == SqlOperation.DELETE:
+        m = re.search(rf"\bDELETE\s+(?:FROM\s+)?({_IDENT})", sql, re.IGNORECASE)
+        if m:
+            tables.append(m.group(1))
+    elif operation == SqlOperation.MERGE:
+        m = re.search(rf"\bMERGE\s+(?:INTO\s+)?({_IDENT})", sql, re.IGNORECASE)
+        if m:
+            tables.append(m.group(1))
+    elif operation in (SqlOperation.TRUNCATE, SqlOperation.DROP, SqlOperation.ALTER):
+        m = re.search(rf"\b(?:TABLE|VIEW)\s+({_IDENT})", sql, re.IGNORECASE)
+        if m:
+            tables.append(m.group(1))
+
+    seen = set()
+    out = []
+    for t in tables:
+        if t.lower() not in seen:
+            seen.add(t.lower())
+            out.append(t)
+    return out
+
+
+def _compute_risk(
+    operation: SqlOperation, has_where: bool, is_multi: bool,
+) -> RiskLevel:
+    if operation in (SqlOperation.DROP, SqlOperation.TRUNCATE):
+        return RiskLevel.CRITICAL
+    if operation == SqlOperation.ALTER:
+        return RiskLevel.HIGH
+    if operation == SqlOperation.DELETE:
+        return RiskLevel.HIGH if not has_where else RiskLevel.MEDIUM
+    if operation in (SqlOperation.UPDATE, SqlOperation.MERGE):
+        return RiskLevel.HIGH if not has_where else RiskLevel.MEDIUM
+    if operation in (SqlOperation.INSERT, SqlOperation.CREATE,
+                     SqlOperation.EXEC, SqlOperation.EXECUTE):
+        return RiskLevel.MEDIUM
+    if is_multi:
+        return RiskLevel.MEDIUM
+    return RiskLevel.LOW
+
+
+_SQL_KEYWORDS = (
+    "select", "insert", "update", "delete", "truncate", "create",
+    "alter", "drop", "exec", "execute", "merge", "with", "from", "where",
+    "join",
+)
+
+
+def _looks_sql_like(text: str) -> bool:
+    """Heuristic: does this look like SQL rather than a natural-language ask?"""
+    if not text:
+        return False
+    lowered = text.lower()
+    if not any(kw in lowered for kw in _SQL_KEYWORDS):
+        return False
+    words = [w for w in re.split(r"\s+", lowered) if w]
+    if not words:
+        return False
+    punct_ratio = sum(1 for ch in text if ch in ",();.=*") / max(len(text), 1)
+    if words[0] in _SQL_KEYWORDS:
+        return True
+    return punct_ratio >= 0.02
+
+
+def _has_unqualified(tables: list[str]) -> bool:
+    return any("." not in t.strip("[]") for t in tables)
+
+
+_DYNAMIC_PAT = re.compile(
+    r"\b(EXEC(?:UTE)?\s*\(|sp_executesql)\b", re.IGNORECASE,
+)
+_CTE_PAT = re.compile(r"^\s*WITH\b", re.IGNORECASE)
+
+
+def analyze_sql(sql: str) -> SqlIntent:
+    clean = _strip_comments(sql)
+    statements = _split_statements(clean)
+    is_multi = len(statements) > 1
+    first = statements[0] if statements else ""
+
+    operation = _detect_operation(first)
+    has_where = bool(re.search(r"\bWHERE\b", first, re.IGNORECASE))
+    has_top = bool(re.search(r"\bTOP\b", first, re.IGNORECASE))
+    tables = _extract_tables(first, operation)
+    risk = _compute_risk(operation, has_where, is_multi)
+
+    is_sql_like = _looks_sql_like(clean)
+    contains_cte = bool(_CTE_PAT.match(first))
+    contains_dynamic = bool(_DYNAMIC_PAT.search(first))
+    unqualified = _has_unqualified(tables)
+
+    if operation == SqlOperation.UNKNOWN:
+        confidence = 0.1 if not is_sql_like else 0.4
+    elif unqualified and operation != SqlOperation.SELECT:
+        confidence = 0.6
+    elif contains_dynamic:
+        confidence = 0.5
+    else:
+        confidence = 0.9
+
+    requires_discovery = (
+        not is_sql_like
+        or operation == SqlOperation.UNKNOWN
+    )
+
+    return SqlIntent(
+        primary_operation=operation,
+        has_where_clause=has_where,
+        has_top_clause=has_top,
+        affected_tables=tables,
+        risk_level=risk,
+        is_multi_statement=is_multi,
+        statement_count=len(statements),
+        is_sql_like=is_sql_like,
+        confidence=confidence,
+        requires_discovery=requires_discovery,
+        has_unqualified_tables=unqualified,
+        contains_dynamic_sql=contains_dynamic,
+        contains_cte=contains_cte,
+    )