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

sqlserver_semantic_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sqlserver_semantic_mcp/config.py

@@ -0,0 +1,78 @@
+from typing import Literal, Optional
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+DetailTier = Literal["brief", "standard", "full"]
+ResponseMode = Literal["summary", "rows", "sample", "count_only"]
+TokenBudgetHint = Literal["tiny", "low", "medium", "high"]
+AffectedRowsPolicy = Literal["strict", "report"]
+StartupMode = Literal["full", "cache_first"]
+
+
+class Config(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="SEMANTIC_MCP_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # ---- DB connection ----
+    mssql_server: str
+    mssql_user: Optional[str] = None
+    mssql_password: Optional[str] = None
+    mssql_database: str
+    mssql_port: int = 1433
+    mssql_windows_auth: bool = False
+    mssql_encrypt: bool = False
+
+    # ---- Cache ----
+    cache_path: str = "./cache/semantic_mcp.db"
+    cache_enabled: bool = True
+    startup_mode: StartupMode = "cache_first"
+    background_batch_size: int = Field(default=5, ge=1)
+    background_interval_ms: int = Field(default=500, ge=0)
+
+    # ---- Policy ----
+    policy_file: Optional[str] = None
+    policy_profile: Optional[str] = None
+
+    # ---- Policy overrides ----
+    max_rows_returned: int = Field(default=1000, ge=1)
+    max_rows_affected: int = Field(default=100, ge=1)
+    query_timeout: int = Field(default=30, ge=1)
+
+    # ---- Tool surface ----
+    tool_profile: str = "all"
+
+    # ---- Metrics ----
+    metrics_enabled: bool = True
+
+    # ---- v0.5 agent-oriented defaults ----
+    default_detail: DetailTier = "brief"
+    default_response_mode: ResponseMode = "summary"
+    default_token_budget_hint: TokenBudgetHint = "low"
+    direct_execute_enabled: bool = True
+    strict_rows_affected_cap: bool = True
+    workflow_tools_enabled: bool = True
+
+    # ---- Analyzer router ----
+    # regex (default, regex-based) | ast (placeholder; falls back to regex)
+    intent_analyzer: Literal["regex", "ast"] = "regex"
+
+
+_config: Optional[Config] = None
+
+
+def get_config() -> Config:
+    global _config
+    if _config is None:
+        _config = Config()
+    return _config
+
+
+def reset_config() -> None:
+    """Test helper only."""
+    global _config
+    _config = None

sqlserver_semantic_mcp/domain/enums.py

@@ -0,0 +1,48 @@
+from enum import Enum
+
+
+class TableType(str, Enum):
+    FACT = "fact"
+    DIMENSION = "dimension"
+    LOOKUP = "lookup"
+    TRANSACTION = "transaction"
+    BRIDGE = "bridge"
+    CONFIG = "config"
+    AUDIT = "audit"
+    UNKNOWN = "unknown"
+
+
+class ObjectType(str, Enum):
+    VIEW = "VIEW"
+    PROCEDURE = "PROCEDURE"
+    FUNCTION = "FUNCTION"
+
+
+class CacheStatus(str, Enum):
+    PENDING = "pending"
+    COMPUTING = "computing"
+    READY = "ready"
+    DIRTY = "dirty"
+    ERROR = "error"
+
+
+class RiskLevel(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class SqlOperation(str, Enum):
+    SELECT = "SELECT"
+    INSERT = "INSERT"
+    UPDATE = "UPDATE"
+    DELETE = "DELETE"
+    TRUNCATE = "TRUNCATE"
+    CREATE = "CREATE"
+    ALTER = "ALTER"
+    DROP = "DROP"
+    EXECUTE = "EXECUTE"
+    EXEC = "EXEC"
+    MERGE = "MERGE"
+    UNKNOWN = "UNKNOWN"

sqlserver_semantic_mcp/domain/models/column.py

@@ -0,0 +1,14 @@
+from typing import Optional
+from pydantic import BaseModel
+
+
+class Column(BaseModel):
+    schema_name: str
+    table_name: str
+    column_name: str
+    data_type: str
+    max_length: Optional[int] = None
+    is_nullable: bool
+    column_default: Optional[str] = None
+    ordinal_position: int
+    description: Optional[str] = None

sqlserver_semantic_mcp/domain/models/object.py

@@ -0,0 +1,13 @@
+from typing import Optional
+from pydantic import BaseModel, Field
+from ..enums import ObjectType
+
+
+class DbObject(BaseModel):
+    schema_name: str
+    object_name: str
+    object_type: ObjectType
+    definition: Optional[str] = None
+    dependencies: list[str] = Field(default_factory=list)
+    affected_tables: list[str] = Field(default_factory=list)
+    description: Optional[str] = None

sqlserver_semantic_mcp/domain/models/relationship.py

@@ -0,0 +1,11 @@
+from pydantic import BaseModel
+
+
+class Relationship(BaseModel):
+    from_schema: str
+    from_table: str
+    to_schema: str
+    to_table: str
+    fk_column: str
+    ref_column: str
+    type: str  # "many_to_one" | "one_to_one" | "self_ref"

sqlserver_semantic_mcp/domain/models/table.py

@@ -0,0 +1,29 @@
+from typing import Optional
+from pydantic import BaseModel, Field
+from ..enums import TableType
+from .column import Column
+
+
+class ForeignKey(BaseModel):
+    column_name: str
+    ref_schema: str
+    ref_table: str
+    ref_column: str
+
+
+class Index(BaseModel):
+    index_name: str
+    is_unique: bool
+    is_primary_key: bool
+    columns: list[str] = Field(default_factory=list)
+
+
+class Table(BaseModel):
+    schema_name: str
+    table_name: str
+    columns: list[Column] = Field(default_factory=list)
+    primary_key: list[str] = Field(default_factory=list)
+    foreign_keys: list[ForeignKey] = Field(default_factory=list)
+    indexes: list[Index] = Field(default_factory=list)
+    description: Optional[str] = None
+    classification: Optional[TableType] = None

sqlserver_semantic_mcp/infrastructure/background.py

@@ -0,0 +1,59 @@
+import asyncio
+import logging
+from typing import Optional
+
+from ..config import Config, get_config
+from ..services import semantic_service
+from .cache.semantic import list_pending_table_analyses
+
+logger = logging.getLogger(__name__)
+
+
+async def run_background_fill_once(cfg: Optional[Config] = None) -> int:
+    cfg = cfg or get_config()
+    pending = await list_pending_table_analyses(
+        cfg.cache_path, cfg.mssql_database, cfg.background_batch_size,
+    )
+    for (s, t) in pending:
+        try:
+            await semantic_service.classify_table(
+                cfg.cache_path, cfg.mssql_database, s, t, force=True,
+            )
+        except Exception:
+            logger.exception("Background classify failed for %s.%s", s, t)
+    return len(pending)
+
+
+async def background_fill_loop(
+    cfg: Optional[Config] = None,
+    stop_event: Optional[asyncio.Event] = None,
+) -> None:
+    cfg = cfg or get_config()
+    stop_event = stop_event or asyncio.Event()
+    interval = cfg.background_interval_ms / 1000.0
+
+    consecutive_errors = 0
+    max_backoff = 60.0
+
+    while not stop_event.is_set():
+        try:
+            processed = await run_background_fill_once(cfg)
+            consecutive_errors = 0  # reset on any successful iteration
+            if processed == 0:
+                try:
+                    await asyncio.wait_for(stop_event.wait(), timeout=10.0)
+                except asyncio.TimeoutError:
+                    continue
+                continue
+            await asyncio.sleep(interval)
+        except Exception:
+            consecutive_errors += 1
+            backoff = min(max_backoff, 2.0 ** consecutive_errors)
+            logger.exception(
+                "Background fill iteration failed (attempt=%d, next retry in %.1fs)",
+                consecutive_errors, backoff,
+            )
+            try:
+                await asyncio.wait_for(stop_event.wait(), timeout=backoff)
+            except asyncio.TimeoutError:
+                continue

sqlserver_semantic_mcp/infrastructure/cache/semantic.py

@@ -0,0 +1,132 @@
+import json
+from datetime import datetime, timezone
+from typing import Optional
+import aiosqlite
+
+
+async def get_table_analysis(
+    db_path: str, database: str, schema: str, table: str,
+) -> Optional[dict]:
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cur = await db.execute(
+            "SELECT * FROM sem_table_analysis "
+            "WHERE database_name=? AND schema_name=? AND table_name=?",
+            (database, schema, table),
+        )
+        row = await cur.fetchone()
+        if not row:
+            return None
+        d = dict(row)
+        for k in ("classification", "column_analysis"):
+            if d.get(k):
+                d[k] = json.loads(d[k])
+        d["is_lookup"] = bool(d["is_lookup"]) if d["is_lookup"] is not None else None
+        return d
+
+
+async def upsert_table_analysis(
+    db_path: str, database: str, schema: str, table: str,
+    *,
+    structural_hash: str,
+    status: str,
+    classification: Optional[dict] = None,
+    column_analysis: Optional[list] = None,
+    is_lookup: Optional[bool] = None,
+    error_message: Optional[str] = None,
+) -> None:
+    async with aiosqlite.connect(db_path) as db:
+        await db.execute(
+            "INSERT OR REPLACE INTO sem_table_analysis "
+            "(database_name, schema_name, table_name, structural_hash, status, "
+            " classification, column_analysis, is_lookup, computed_at, error_message) "
+            "VALUES (?,?,?,?,?,?,?,?,?,?)",
+            (
+                database, schema, table, structural_hash, status,
+                json.dumps(classification) if classification else None,
+                json.dumps(column_analysis) if column_analysis else None,
+                int(is_lookup) if is_lookup is not None else None,
+                datetime.now(timezone.utc).isoformat(),
+                error_message,
+            ),
+        )
+        await db.commit()
+
+
+async def get_object_definition(
+    db_path: str, database: str, schema: str, obj_name: str, obj_type: str,
+) -> Optional[dict]:
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cur = await db.execute(
+            "SELECT * FROM sem_object_definitions "
+            "WHERE database_name=? AND schema_name=? "
+            "AND object_name=? AND object_type=?",
+            (database, schema, obj_name, obj_type),
+        )
+        row = await cur.fetchone()
+        if not row:
+            return None
+        d = dict(row)
+        for k in ("dependencies", "affected_tables"):
+            if d.get(k):
+                d[k] = json.loads(d[k])
+        return d
+
+
+async def upsert_object_definition(
+    db_path: str, database: str, schema: str, obj_name: str, obj_type: str,
+    *,
+    object_hash: str,
+    status: str,
+    definition: Optional[str] = None,
+    dependencies: Optional[list] = None,
+    affected_tables: Optional[list] = None,
+    error_message: Optional[str] = None,
+) -> None:
+    async with aiosqlite.connect(db_path) as db:
+        await db.execute(
+            "INSERT OR REPLACE INTO sem_object_definitions "
+            "(database_name, schema_name, object_name, object_type, object_hash, "
+            " status, definition, dependencies, affected_tables, "
+            " computed_at, error_message) "
+            "VALUES (?,?,?,?,?,?,?,?,?,?,?)",
+            (
+                database, schema, obj_name, obj_type, object_hash, status,
+                definition,
+                json.dumps(dependencies) if dependencies else None,
+                json.dumps(affected_tables) if affected_tables else None,
+                datetime.now(timezone.utc).isoformat(),
+                error_message,
+            ),
+        )
+        await db.commit()
+
+
+async def list_pending_table_analyses(
+    db_path: str, database: str, limit: int,
+) -> list[tuple[str, str]]:
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cur = await db.execute(
+            "SELECT schema_name, table_name FROM sem_table_analysis "
+            "WHERE database_name=? AND status IN ('pending','dirty') "
+            "ORDER BY schema_name, table_name LIMIT ?",
+            (database, limit),
+        )
+        return [(r["schema_name"], r["table_name"]) for r in await cur.fetchall()]
+
+
+async def enqueue_all_tables(db_path: str, database: str, structural_hash: str) -> int:
+    async with aiosqlite.connect(db_path) as db:
+        await db.execute(
+            "INSERT OR IGNORE INTO sem_table_analysis "
+            "(database_name, schema_name, table_name, structural_hash, status) "
+            "SELECT ?, schema_name, table_name, ?, 'pending' "
+            "FROM sc_tables WHERE database_name=?",
+            (database, structural_hash, database),
+        )
+        await db.commit()
+        cur = await db.execute("SELECT changes()")
+        row = await cur.fetchone()
+        return int(row[0]) if row and row[0] is not None else 0

sqlserver_semantic_mcp/infrastructure/cache/store.py

@@ -0,0 +1,152 @@
+from pathlib import Path
+import aiosqlite
+
+
+SCHEMA_TABLES = [
+    "schema_version",
+    "sc_tables", "sc_columns", "sc_primary_keys", "sc_foreign_keys",
+    "sc_indexes", "sc_objects", "sc_comments",
+    "sem_table_analysis", "sem_object_definitions",
+]
+
+SCHEMA_DDL = """
+CREATE TABLE IF NOT EXISTS schema_version (
+    database_name   TEXT PRIMARY KEY,
+    structural_hash TEXT NOT NULL,
+    object_hash     TEXT NOT NULL,
+    comment_hash    TEXT NOT NULL,
+    captured_at     TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sc_tables (
+    database_name TEXT NOT NULL,
+    schema_name   TEXT NOT NULL,
+    table_name    TEXT NOT NULL,
+    PRIMARY KEY (database_name, schema_name, table_name)
+);
+
+CREATE TABLE IF NOT EXISTS sc_columns (
+    database_name    TEXT NOT NULL,
+    schema_name      TEXT NOT NULL,
+    table_name       TEXT NOT NULL,
+    column_name      TEXT NOT NULL,
+    data_type        TEXT NOT NULL,
+    max_length       INTEGER,
+    is_nullable      INTEGER NOT NULL,
+    column_default   TEXT,
+    ordinal_position INTEGER NOT NULL,
+    PRIMARY KEY (database_name, schema_name, table_name, column_name)
+);
+
+CREATE TABLE IF NOT EXISTS sc_primary_keys (
+    database_name TEXT NOT NULL,
+    schema_name   TEXT NOT NULL,
+    table_name    TEXT NOT NULL,
+    column_name   TEXT NOT NULL,
+    PRIMARY KEY (database_name, schema_name, table_name, column_name)
+);
+
+CREATE TABLE IF NOT EXISTS sc_foreign_keys (
+    database_name TEXT NOT NULL,
+    schema_name   TEXT NOT NULL,
+    table_name    TEXT NOT NULL,
+    column_name   TEXT NOT NULL,
+    ref_schema    TEXT NOT NULL,
+    ref_table     TEXT NOT NULL,
+    ref_column    TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_fk_from
+    ON sc_foreign_keys (database_name, schema_name, table_name);
+CREATE INDEX IF NOT EXISTS idx_fk_to
+    ON sc_foreign_keys (database_name, ref_schema, ref_table);
+
+CREATE TABLE IF NOT EXISTS sc_indexes (
+    database_name  TEXT NOT NULL,
+    schema_name    TEXT NOT NULL,
+    table_name     TEXT NOT NULL,
+    index_name     TEXT NOT NULL,
+    is_unique      INTEGER NOT NULL,
+    is_primary_key INTEGER NOT NULL,
+    columns        TEXT NOT NULL,
+    PRIMARY KEY (database_name, schema_name, table_name, index_name)
+);
+
+CREATE TABLE IF NOT EXISTS sc_objects (
+    database_name TEXT NOT NULL,
+    schema_name   TEXT NOT NULL,
+    object_name   TEXT NOT NULL,
+    object_type   TEXT NOT NULL,
+    PRIMARY KEY (database_name, schema_name, object_name, object_type)
+);
+
+CREATE TABLE IF NOT EXISTS sc_comments (
+    database_name TEXT NOT NULL,
+    schema_name   TEXT NOT NULL,
+    object_name   TEXT NOT NULL,
+    column_name   TEXT NOT NULL DEFAULT '',
+    description   TEXT NOT NULL,
+    PRIMARY KEY (database_name, schema_name, object_name, column_name)
+);
+
+CREATE TABLE IF NOT EXISTS sem_table_analysis (
+    database_name   TEXT NOT NULL,
+    schema_name     TEXT NOT NULL,
+    table_name      TEXT NOT NULL,
+    structural_hash TEXT NOT NULL,
+    status          TEXT NOT NULL DEFAULT 'pending',
+    classification  TEXT,
+    column_analysis TEXT,
+    is_lookup       INTEGER,
+    computed_at     TEXT,
+    error_message   TEXT,
+    PRIMARY KEY (database_name, schema_name, table_name)
+);
+CREATE INDEX IF NOT EXISTS idx_sem_table_status
+    ON sem_table_analysis (status);
+
+CREATE TABLE IF NOT EXISTS sem_object_definitions (
+    database_name   TEXT NOT NULL,
+    schema_name     TEXT NOT NULL,
+    object_name     TEXT NOT NULL,
+    object_type     TEXT NOT NULL,
+    object_hash     TEXT NOT NULL,
+    status          TEXT NOT NULL DEFAULT 'pending',
+    definition      TEXT,
+    dependencies    TEXT,
+    affected_tables TEXT,
+    computed_at     TEXT,
+    error_message   TEXT,
+    PRIMARY KEY (database_name, schema_name, object_name, object_type)
+);
+CREATE INDEX IF NOT EXISTS idx_sem_obj_status
+    ON sem_object_definitions (status);
+
+CREATE TABLE IF NOT EXISTS tool_metrics (
+    id                 INTEGER PRIMARY KEY AUTOINCREMENT,
+    tool_name          TEXT NOT NULL,
+    response_bytes     INTEGER NOT NULL,
+    array_length       INTEGER,
+    fields_returned    INTEGER,
+    route_type         TEXT,
+    detail             TEXT,
+    response_mode      TEXT,
+    token_budget_hint  TEXT,
+    was_direct_execute INTEGER,
+    bundle_used        INTEGER,
+    next_action        TEXT,
+    recorded_at        TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_tool_metrics_name
+    ON tool_metrics (tool_name);
+"""
+
+
+async def init_store(db_path: str) -> None:
+    Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+    async with aiosqlite.connect(db_path) as db:
+        await db.executescript(SCHEMA_DDL)
+        await db.commit()
+
+
+def connection(db_path: str):
+    return aiosqlite.connect(db_path)