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

sqlserver_semantic_mcp/server/tools/policy.py

@@ -0,0 +1,48 @@
+from mcp.types import Tool
+
+from ..app import get_context, register_tool
+
+
+def register() -> None:
+    register_tool(
+        Tool(
+            name="get_execution_policy",
+            description="Return the active execution policy.",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        _get_policy,
+    )
+    register_tool(
+        Tool(
+            name="validate_sql_against_policy",
+            description="Validate SQL against active policy WITHOUT executing.",
+            inputSchema={
+                "type": "object",
+                "properties": {"query": {"type": "string"}},
+                "required": ["query"],
+            },
+        ),
+        _validate_sql,
+    )
+    register_tool(
+        Tool(
+            name="refresh_policy",
+            description="Reload policy file from disk.",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        _refresh,
+    )
+
+
+async def _get_policy(args: dict) -> dict:
+    return get_context().policy.current_policy().model_dump()
+
+
+async def _validate_sql(args: dict) -> dict:
+    return get_context().policy.validate(args["query"])
+
+
+async def _refresh(args: dict) -> dict:
+    ctx = get_context()
+    ctx.policy.reload()
+    return {"reloaded": True, "profile": ctx.policy.current_policy().profile_name}

sqlserver_semantic_mcp/server/tools/query.py

@@ -0,0 +1,159 @@
+from mcp.types import Tool
+
+from ..app import get_context, register_tool
+
+
+_DETAIL_PROP = {
+    "type": "string", "enum": ["brief", "standard", "full"], "default": "brief",
+}
+_BUDGET_PROP = {
+    "type": "string", "enum": ["tiny", "low", "medium", "high"],
+}
+_RESPONSE_MODE_PROP = {
+    "type": "string", "enum": ["summary", "rows", "sample", "count_only"],
+    "description": "summary=columns+count; rows=full page; "
+                   "sample=columns+first N; count_only=row_count only.",
+}
+_AFFECTED_POLICY_PROP = {
+    "type": "string", "enum": ["strict", "report"],
+    "description": "strict = roll back if affected rows exceed cap; "
+                   "report = execute and report exceeded_cap.",
+}
+
+
+def register() -> None:
+    register_tool(
+        Tool(
+            name="validate_query",
+            description=(
+                "Analyze a SQL query and report intent + whether policy allows "
+                "it. Use this when you want to test a query without executing."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {"query": {"type": "string"}},
+                "required": ["query"],
+            },
+        ),
+        _validate,
+    )
+    register_tool(
+        Tool(
+            name="run_safe_query",
+            description=(
+                "Execute SQL after policy validation. Result rows are truncated "
+                "to max_rows_returned. Prefer plan_or_execute_query for the "
+                "shortest safe path when SQL is already known."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string"},
+                    "max_rows": {"type": "integer", "minimum": 1},
+                },
+                "required": ["query"],
+            },
+        ),
+        _run_safe,
+    )
+    register_tool(
+        Tool(
+            name="plan_or_execute_query",
+            description=(
+                "v0.5 main entry for SQL-ready agents. mode=auto validates then "
+                "executes if safe; mode=validate_only stops after validation; "
+                "mode=dry_run returns preview without side effects. Do not use "
+                "this for schema discovery — use discover_relevant_tables first "
+                "when the target tables are unknown."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query":                _required_query(),
+                    "mode": {
+                        "type": "string",
+                        "enum": ["auto", "validate_only", "dry_run",
+                                 "execute_if_safe"],
+                        "default": "auto",
+                    },
+                    "max_rows":             {"type": "integer", "minimum": 1},
+                    "return_mode":          _RESPONSE_MODE_PROP,
+                    "detail":               _DETAIL_PROP,
+                    "token_budget_hint":    _BUDGET_PROP,
+                    "affected_rows_policy": _AFFECTED_POLICY_PROP,
+                },
+                "required": ["query"],
+            },
+        ),
+        _plan_or_execute,
+    )
+    register_tool(
+        Tool(
+            name="preview_safe_query",
+            description=(
+                "Return a minimal plan — operation, affected tables, policy "
+                "outcome, applied row caps — without executing."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query":    _required_query(),
+                    "max_rows": {"type": "integer", "minimum": 1},
+                },
+                "required": ["query"],
+            },
+        ),
+        _preview,
+    )
+    register_tool(
+        Tool(
+            name="estimate_execution_risk",
+            description=(
+                "Estimate payload / policy / qualification risks for a SQL "
+                "string without executing it."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {"query": {"type": "string"}},
+                "required": ["query"],
+            },
+        ),
+        _estimate_risk,
+    )
+
+
+def _required_query() -> dict:
+    return {"type": "string", "description": "SQL to execute / validate."}
+
+
+async def _validate(args: dict) -> dict:
+    return get_context().query.validate(args["query"])
+
+
+async def _run_safe(args: dict) -> dict:
+    return get_context().query.run_safe_query(
+        args["query"], max_rows=args.get("max_rows"),
+    )
+
+
+async def _plan_or_execute(args: dict) -> dict:
+    ctx = get_context()
+    return ctx.workflow.plan_or_execute_query(
+        args["query"],
+        mode=args.get("mode", "auto"),
+        max_rows=args.get("max_rows"),
+        return_mode=args.get("return_mode"),
+        detail=args.get("detail", "brief"),
+        token_budget_hint=args.get("token_budget_hint"),
+        affected_rows_policy=args.get("affected_rows_policy"),
+    )
+
+
+async def _preview(args: dict) -> dict:
+    return get_context().workflow.preview_safe_query(
+        args["query"], max_rows=args.get("max_rows"),
+    )
+
+
+async def _estimate_risk(args: dict) -> dict:
+    return get_context().workflow.estimate_execution_risk(args["query"])

sqlserver_semantic_mcp/server/tools/relationship.py

@@ -0,0 +1,104 @@
+from mcp.types import Tool
+
+from ...services import relationship_service
+from ..app import get_context, register_tool
+
+
+def register() -> None:
+    register_tool(
+        Tool(
+            name="get_table_relationships",
+            description="List inbound + outbound FK relationships for a table.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "schema": {"type": "string"},
+                    "table":  {"type": "string"},
+                },
+                "required": ["schema", "table"],
+            },
+        ),
+        _rels,
+    )
+    register_tool(
+        Tool(
+            name="find_join_path",
+            description=(
+                "Find a shortest FK-based join path between two tables "
+                "(BFS, bidirectional edges). Use after candidate tables are "
+                "known. For ranking multiple reasonable paths, call "
+                "score_join_candidate next."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "from_schema": {"type": "string"},
+                    "from_table":  {"type": "string"},
+                    "to_schema":   {"type": "string"},
+                    "to_table":    {"type": "string"},
+                    "max_hops":    {"type": "integer", "minimum": 1, "default": 5},
+                },
+                "required": ["from_schema", "from_table", "to_schema", "to_table"],
+            },
+        ),
+        _path,
+    )
+    register_tool(
+        Tool(
+            name="get_dependency_chain",
+            description=(
+                "List all tables reachable from a given table via FKs. "
+                "schemas param limits the BFS frontier to allowed schemas "
+                "(start table always included)."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "schema":    {"type": "string"},
+                    "table":     {"type": "string"},
+                    "max_depth": {"type": "integer", "default": 10},
+                    "schemas":   {"oneOf": [{"type": "string"},
+                                            {"type": "array",
+                                             "items": {"type": "string"}}]},
+                },
+                "required": ["schema", "table"],
+            },
+        ),
+        _chain,
+    )
+
+
+async def _rels(args: dict) -> list[dict]:
+    ctx = get_context()
+    return await relationship_service.get_table_relationships(
+        ctx.cfg.cache_path, ctx.cfg.mssql_database,
+        args["schema"], args["table"],
+    )
+
+
+async def _path(args: dict) -> dict:
+    ctx = get_context()
+    path = await relationship_service.find_join_path(
+        ctx.cfg.cache_path, ctx.cfg.mssql_database,
+        args["from_schema"], args["from_table"],
+        args["to_schema"], args["to_table"],
+        max_hops=args.get("max_hops", 5),
+    )
+    return {"found": path is not None, "path": path or []}
+
+
+async def _chain(args: dict) -> list[dict]:
+    ctx = get_context()
+    raw = args.get("schemas")
+    if isinstance(raw, str):
+        schemas = [raw] if raw else None
+    elif isinstance(raw, list):
+        schemas = [s for s in raw if isinstance(s, str) and s] or None
+    else:
+        schemas = None
+    return await relationship_service.get_dependency_chain(
+        ctx.cfg.cache_path, ctx.cfg.mssql_database,
+        args["schema"], args["table"],
+        max_depth=args.get("max_depth", 10),
+        schemas=schemas,
+    )

sqlserver_semantic_mcp/server/tools/semantic.py

@@ -0,0 +1,112 @@
+from typing import Optional
+
+from mcp.types import Tool
+
+from ...services import semantic_service
+from ..app import get_context, register_tool
+from .shape import project_classify, resolve_detail
+
+
+_DETAIL_PROP = {
+    "type": "string", "enum": ["brief", "standard", "full"],
+    "default": "brief",
+    "description": "brief = type+confidence only; standard/full include reasons.",
+}
+
+
+def register() -> None:
+    register_tool(
+        Tool(
+            name="classify_table",
+            description="Classify a table (fact / dimension / lookup / bridge / audit).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "schema": {"type": "string"},
+                    "table":  {"type": "string"},
+                    "force":  {"type": "boolean", "default": False},
+                    "detail": _DETAIL_PROP,
+                },
+                "required": ["schema", "table"],
+            },
+        ),
+        _classify,
+    )
+    register_tool(
+        Tool(
+            name="analyze_columns",
+            description="Return semantic labels for each column (audit, status, etc.).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "schema": {"type": "string"},
+                    "table":  {"type": "string"},
+                },
+                "required": ["schema", "table"],
+            },
+        ),
+        _columns,
+    )
+    register_tool(
+        Tool(
+            name="detect_lookup_tables",
+            description=(
+                "Scan DB and return likely lookup tables. Supports schema / "
+                "keyword / confidence_min filters to limit the sweep."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "schema":         {"oneOf": [{"type": "string"},
+                                                 {"type": "array",
+                                                  "items": {"type": "string"}}]},
+                    "keyword":        {"type": "string"},
+                    "confidence_min": {"type": "number",
+                                       "minimum": 0.0, "maximum": 1.0,
+                                       "default": 0.0},
+                },
+            },
+        ),
+        _lookups,
+    )
+
+
+def _normalize_schema_filter(raw) -> Optional[list[str]]:
+    if raw is None:
+        return None
+    if isinstance(raw, str):
+        return [raw] if raw else None
+    if isinstance(raw, list):
+        vals = [s for s in raw if isinstance(s, str) and s]
+        return vals or None
+    return None
+
+
+async def _classify(args: dict) -> dict:
+    ctx = get_context()
+    detail = resolve_detail(args)
+    classification = await semantic_service.classify_table(
+        ctx.cfg.cache_path, ctx.cfg.mssql_database,
+        args["schema"], args["table"],
+        force=args.get("force", False),
+    )
+    return project_classify(classification, detail)
+
+
+async def _columns(args: dict) -> list[dict]:
+    ctx = get_context()
+    return await semantic_service.analyze_columns(
+        ctx.cfg.cache_path, ctx.cfg.mssql_database,
+        args["schema"], args["table"],
+    )
+
+
+async def _lookups(args: dict) -> list[dict]:
+    ctx = get_context()
+    schemas = _normalize_schema_filter(args.get("schema"))
+    keyword = args.get("keyword") or None
+    confidence_min = float(args.get("confidence_min", 0.0))
+    return await semantic_service.detect_lookup_tables(
+        ctx.cfg.cache_path, ctx.cfg.mssql_database,
+        schemas=schemas, keyword=keyword, confidence_min=confidence_min,
+    )

sqlserver_semantic_mcp/server/tools/shape.py

@@ -0,0 +1,204 @@
+"""Detail-tier projection helpers for P1 response contract reset.
+
+See docs/superpowers/specs/2026-04-19-p1-response-contract-reset-design.md.
+"""
+from typing import Any, Optional
+
+VALID_DETAILS: frozenset[str] = frozenset({"brief", "standard", "full"})
+
+_IMPORTANT_COLS_CAP = 8
+
+
+class DetailError(ValueError):
+    """Raised when an invalid `detail` value is passed."""
+
+
+def resolve_detail(args: dict) -> str:
+    val = args.get("detail", "brief")
+    if val not in VALID_DETAILS:
+        raise DetailError(
+            f"invalid detail '{val}'; expected one of {sorted(VALID_DETAILS)}"
+        )
+    return val
+
+
+def _important_columns(
+    columns: list[dict], pk: list[str], fks: list[dict],
+    semantic_map: dict[str, str],
+) -> list[str]:
+    seen: set[str] = set()
+    order: list[str] = []
+
+    def push(name: str) -> None:
+        if name in seen or name is None:
+            return
+        seen.add(name)
+        order.append(name)
+        if len(order) >= _IMPORTANT_COLS_CAP:
+            raise StopIteration
+
+    try:
+        for name in pk:
+            push(name)
+        for fk in fks:
+            push(fk.get("column_name"))
+        # columns with a non-generic semantic tag, in ordinal order
+        for col in columns:
+            name = col["column_name"]
+            sem = semantic_map.get(name)
+            if sem and sem != "generic":
+                push(name)
+        # fill remaining with next columns in ordinal order
+        for col in columns:
+            push(col["column_name"])
+    except StopIteration:
+        pass
+
+    return order[:_IMPORTANT_COLS_CAP]
+
+
+def project_describe_table(
+    full: dict, detail: str,
+    classification: Optional[dict],
+    column_semantics: dict[str, str],
+) -> dict:
+    schema = full.get("schema_name", "")
+    table = full.get("table_name", "")
+    columns = full.get("columns", [])
+    pk = full.get("primary_key", []) or []
+    fks = full.get("foreign_keys", []) or []
+    cls_type = (classification or {}).get("type", "unknown")
+
+    fk_to = sorted({
+        f"{fk.get('ref_schema')}.{fk.get('ref_table')}"
+        for fk in fks
+        if fk.get("ref_schema") and fk.get("ref_table")
+    })
+
+    brief: dict[str, Any] = {
+        "table": f"{schema}.{table}",
+        "column_count": len(columns),
+        "pk": list(pk),
+        "fk_to": fk_to,
+        "important_columns": _important_columns(columns, pk, fks, column_semantics),
+        "classification": cls_type,
+    }
+    if detail == "brief":
+        return brief
+
+    # standard: brief + full columns (name/type/nullable) + full FK rows
+    standard_cols = [
+        {"name": c["column_name"], "type": c.get("data_type"),
+         "is_nullable": bool(c.get("is_nullable"))}
+        for c in columns
+    ]
+    standard: dict[str, Any] = {
+        **brief,
+        "columns": standard_cols,
+        "foreign_keys": list(fks),
+    }
+    if detail == "standard":
+        return standard
+
+    # full: standard + indexes + description + per-column default_value + description
+    full_cols = []
+    for c in columns:
+        full_cols.append({
+            "name": c["column_name"],
+            "type": c.get("data_type"),
+            "is_nullable": bool(c.get("is_nullable")),
+            "max_length": c.get("max_length"),
+            "default_value": c.get("default_value"),
+            "description": c.get("description"),
+        })
+    return {
+        **brief,
+        "columns": full_cols,
+        "foreign_keys": list(fks),
+        "indexes": full.get("indexes", []),
+        "description": full.get("description"),
+    }
+
+
+def project_get_columns(
+    columns: list[dict], detail: str,
+    semantic_map: dict[str, str],
+) -> list[dict]:
+    def semantic_for(name: str) -> str:
+        return semantic_map.get(name) or "generic"
+
+    if detail == "brief":
+        return [
+            {"name": c["column_name"], "semantic": semantic_for(c["column_name"])}
+            for c in columns
+        ]
+    if detail == "standard":
+        return [
+            {"name": c["column_name"], "type": c.get("data_type"),
+             "is_nullable": bool(c.get("is_nullable")),
+             "semantic": semantic_for(c["column_name"])}
+            for c in columns
+        ]
+    # full
+    return [
+        {"name": c["column_name"], "type": c.get("data_type"),
+         "max_length": c.get("max_length"),
+         "is_nullable": bool(c.get("is_nullable")),
+         "default_value": c.get("default_value"),
+         "description": c.get("description"),
+         "semantic": semantic_for(c["column_name"])}
+        for c in columns
+    ]
+
+
+def project_classify(classification: dict, detail: str) -> dict:
+    if detail == "brief":
+        return {
+            "type": classification.get("type"),
+            "confidence": classification.get("confidence"),
+        }
+    return dict(classification)
+
+
+def project_describe_object(
+    obj: dict, detail: str, include_definition: bool,
+) -> dict:
+    schema = obj.get("schema", "")
+    name = obj.get("object_name", "")
+    obj_type = obj.get("object_type") or obj.get("type")
+
+    brief: dict[str, Any] = {
+        "object": f"{schema}.{name}",
+        "type": obj_type,
+        "depends_on": list(obj.get("dependencies", []) or []),
+        "definition_bytes": obj.get("definition_bytes"),
+    }
+    if obj.get("status") == "error":
+        brief["status"] = "error"
+        brief["error_message"] = obj.get("error_message")
+
+    # include_definition explicit true overrides brief
+    if detail == "brief":
+        if include_definition and obj.get("definition"):
+            brief["definition"] = obj["definition"]
+            brief["definition_hash"] = obj.get("definition_hash")
+        return brief
+
+    # standard / full share more fields
+    standard: dict[str, Any] = {
+        **brief,
+        "definition_hash": obj.get("definition_hash"),
+        "read_tables": list(obj.get("read_tables", []) or []),
+        "write_tables": list(obj.get("write_tables", []) or []),
+        "affected_tables": list(obj.get("affected_tables", []) or []),
+        "description": obj.get("description"),
+        "status": obj.get("status"),
+    }
+
+    if detail == "standard":
+        if include_definition and obj.get("definition"):
+            standard["definition"] = obj["definition"]
+        return standard
+
+    # full: always include definition
+    return {**standard, "definition": obj.get("definition")}