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

sqlserver_semantic_mcp/policy/enforcer.py

@@ -0,0 +1,104 @@
+from dataclasses import dataclass
+
+from ..domain.enums import SqlOperation
+from .analyzer import SqlIntent
+from .models import PolicyProfile
+
+
+@dataclass
+class EnforcementResult:
+    allowed: bool
+    reason: str
+
+
+_OP_FIELD = {
+    SqlOperation.SELECT:   "select",
+    SqlOperation.INSERT:   "insert",
+    SqlOperation.UPDATE:   "update",
+    SqlOperation.DELETE:   "delete",
+    SqlOperation.TRUNCATE: "truncate",
+    SqlOperation.CREATE:   "create",
+    SqlOperation.ALTER:    "alter",
+    SqlOperation.DROP:     "drop",
+    SqlOperation.EXEC:     "execute",
+    SqlOperation.EXECUTE:  "execute",
+    SqlOperation.MERGE:    "merge",
+}
+
+
+def _bare(name: str) -> str:
+    return name.strip("[]").split(".")[-1].strip("[]")
+
+
+def enforce(
+    intent: SqlIntent, policy: PolicyProfile, database: str = "",
+) -> EnforcementResult:
+    op = intent.primary_operation
+    if op == SqlOperation.UNKNOWN:
+        return EnforcementResult(False, "Unable to determine SQL operation")
+
+    field = _OP_FIELD.get(op)
+    if field is None or not getattr(policy.operations, field, False):
+        return EnforcementResult(
+            False, f"Operation {op.value} is not allowed by policy"
+        )
+
+    if intent.is_multi_statement and not policy.constraints.allow_multi_statement:
+        return EnforcementResult(False, "Multi-statement queries are not allowed")
+
+    if op == SqlOperation.UPDATE and policy.constraints.require_where_for_update \
+            and not intent.has_where_clause:
+        return EnforcementResult(False, "UPDATE requires a WHERE clause")
+
+    if op == SqlOperation.DELETE and policy.constraints.require_where_for_delete \
+            and not intent.has_where_clause:
+        return EnforcementResult(False, "DELETE requires a WHERE clause")
+
+    if op == SqlOperation.SELECT and policy.constraints.require_top_for_select \
+            and not intent.has_top_clause:
+        return EnforcementResult(False, "SELECT requires a TOP clause")
+
+    scope = policy.scope
+
+    if scope.allowed_databases and database:
+        if database not in scope.allowed_databases:
+            return EnforcementResult(
+                False, f"Database '{database}' is not allowed by policy"
+            )
+
+    bare_tables = [_bare(t) for t in intent.affected_tables]
+
+    if scope.denied_tables:
+        for name in bare_tables:
+            if name in scope.denied_tables:
+                return EnforcementResult(
+                    False, f"Table '{name}' is denied by policy"
+                )
+
+    if scope.allowed_tables:
+        for name in bare_tables:
+            if name not in scope.allowed_tables:
+                return EnforcementResult(
+                    False,
+                    f"Table '{name}' is not in the allowed tables list",
+                )
+
+    if scope.allowed_schemas:
+        for t in intent.affected_tables:
+            parts = t.strip("[]").split(".")
+            if len(parts) == 2:
+                schema = parts[0].strip("[]")
+                if schema not in scope.allowed_schemas:
+                    return EnforcementResult(
+                        False,
+                        f"Schema '{schema}' is not in the allowed schemas list",
+                    )
+            else:
+                # Unqualified table name — cannot verify schema, reject
+                return EnforcementResult(
+                    False,
+                    f"Table '{t}' is unqualified; allowed_schemas requires "
+                    f"schema-qualified names (e.g., 'dbo.{t}')",
+                )
+
+    return EnforcementResult(True, "Query is allowed")

sqlserver_semantic_mcp/policy/intents/__init__.py

@@ -0,0 +1,16 @@
+"""Pluggable SQL intent analyzers.
+
+The regex analyzer is the current default. The AST analyzer is a
+placeholder that falls back to regex until a real parser lands.
+"""
+from .base import IntentAnalyzer
+from .regex_analyzer import RegexIntentAnalyzer
+from .ast_analyzer import AstIntentAnalyzer
+from .router import get_analyzer
+
+__all__ = [
+    "IntentAnalyzer",
+    "RegexIntentAnalyzer",
+    "AstIntentAnalyzer",
+    "get_analyzer",
+]

sqlserver_semantic_mcp/policy/intents/ast_analyzer.py

@@ -0,0 +1,24 @@
+"""AST analyzer placeholder.
+
+Currently falls back to :class:`RegexIntentAnalyzer`. The slot exists so
+the workflow layer and tests do not need to change when a real parser
+lands.
+"""
+from __future__ import annotations
+
+from ..analyzer import SqlIntent
+from .regex_analyzer import RegexIntentAnalyzer
+
+
+class AstIntentAnalyzer:
+    name = "ast"
+
+    def __init__(self) -> None:
+        self._fallback = RegexIntentAnalyzer()
+
+    def analyze(self, sql: str) -> SqlIntent:
+        # Real AST analysis TBD; until then, return the regex result but
+        # lower the confidence so routing code can treat it as provisional.
+        intent = self._fallback.analyze(sql)
+        intent.confidence = min(intent.confidence, 0.7)
+        return intent

sqlserver_semantic_mcp/policy/intents/base.py

@@ -0,0 +1,17 @@
+"""Analyzer contract for SQL intent detection."""
+from __future__ import annotations
+
+from typing import Protocol
+
+from ..analyzer import SqlIntent
+
+
+class IntentAnalyzer(Protocol):
+    """Analyze a SQL string and return a :class:`SqlIntent`.
+
+    Implementations must not raise for malformed SQL; they should return
+    an ``UNKNOWN`` intent with ``is_sql_like=False`` instead, so the
+    workflow router can send the request down the discovery path.
+    """
+
+    def analyze(self, sql: str) -> SqlIntent: ...

sqlserver_semantic_mcp/policy/intents/regex_analyzer.py

@@ -0,0 +1,11 @@
+"""Default regex-based analyzer — wraps the existing ``analyze_sql``."""
+from __future__ import annotations
+
+from ..analyzer import SqlIntent, analyze_sql
+
+
+class RegexIntentAnalyzer:
+    name = "regex"
+
+    def analyze(self, sql: str) -> SqlIntent:
+        return analyze_sql(sql)

sqlserver_semantic_mcp/policy/intents/router.py

@@ -0,0 +1,21 @@
+"""Selects the active intent analyzer based on :class:`Config`."""
+from __future__ import annotations
+
+from typing import Optional
+
+from ...config import Config, get_config
+from .ast_analyzer import AstIntentAnalyzer
+from .base import IntentAnalyzer
+from .regex_analyzer import RegexIntentAnalyzer
+
+
+_REGISTRY: dict[str, type] = {
+    "regex": RegexIntentAnalyzer,
+    "ast":   AstIntentAnalyzer,
+}
+
+
+def get_analyzer(cfg: Optional[Config] = None) -> IntentAnalyzer:
+    cfg = cfg or get_config()
+    cls = _REGISTRY.get(cfg.intent_analyzer, RegexIntentAnalyzer)
+    return cls()

sqlserver_semantic_mcp/policy/loader.py

@@ -0,0 +1,90 @@
+import json
+import logging
+from pathlib import Path
+from typing import Optional
+
+from ..config import Config, get_config
+from .models import (
+    PolicyFile, PolicyProfile, PolicyOperations,
+    PolicyConstraints, PolicyScope,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def builtin_readonly() -> PolicyProfile:
+    return PolicyProfile(
+        profile_name="readonly",
+        operations=PolicyOperations(select=True),
+        constraints=PolicyConstraints(
+            max_rows_returned=1000,
+            allow_multi_statement=False,
+        ),
+    )
+
+
+def select_profile(pf: PolicyFile, override: Optional[str]) -> PolicyProfile:
+    name = override or pf.active_profile
+    if name not in pf.profiles:
+        raise ValueError(f"Profile '{name}' not found in policy file")
+    profile = pf.profiles[name]
+    profile.profile_name = name
+    return profile
+
+
+def apply_env_overrides(profile: PolicyProfile, cfg: Config) -> PolicyProfile:
+    data = profile.model_dump()
+    data["constraints"]["max_rows_returned"] = cfg.max_rows_returned
+    data["constraints"]["max_rows_affected"] = cfg.max_rows_affected
+    data["constraints"]["query_timeout_seconds"] = cfg.query_timeout
+    return PolicyProfile.model_validate(data)
+
+
+def load_policy_from_file(
+    path: Optional[str], profile_override: Optional[str],
+) -> PolicyProfile:
+    if not path:
+        logger.warning("No policy file specified; using built-in readonly profile")
+        return builtin_readonly()
+
+    p = Path(path)
+    if not p.exists():
+        logger.warning(
+            "Policy file %s not found; using built-in readonly profile", path,
+        )
+        return builtin_readonly()
+
+    try:
+        text = p.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as e:
+        logger.error(
+            "Policy file %s unreadable (%s); falling back to readonly", path, e,
+        )
+        return builtin_readonly()
+
+    try:
+        raw = json.loads(text)
+    except json.JSONDecodeError as e:
+        logger.error(
+            "Policy file %s has invalid JSON (%s); falling back to readonly",
+            path, e,
+        )
+        return builtin_readonly()
+
+    try:
+        pf = PolicyFile.model_validate(raw)
+    except Exception as e:
+        logger.error(
+            "Policy file %s failed schema validation (%s); falling back to readonly",
+            path, e,
+        )
+        return builtin_readonly()
+
+    # Profile-override errors still raise (caller misconfiguration)
+    return select_profile(pf, profile_override)
+
+
+def load_active_policy(cfg: Optional[Config] = None) -> PolicyProfile:
+    cfg = cfg or get_config()
+    base = load_policy_from_file(cfg.policy_file, cfg.policy_profile)
+    return apply_env_overrides(base, cfg)

sqlserver_semantic_mcp/policy/models.py

@@ -0,0 +1,43 @@
+from pydantic import BaseModel, Field
+
+
+class PolicyOperations(BaseModel):
+    select:   bool = True
+    insert:   bool = False
+    update:   bool = False
+    delete:   bool = False
+    truncate: bool = False
+    create:   bool = False
+    alter:    bool = False
+    drop:     bool = False
+    execute:  bool = False
+    merge:    bool = False
+
+
+class PolicyConstraints(BaseModel):
+    require_where_for_update: bool = True
+    require_where_for_delete: bool = True
+    require_top_for_select:   bool = False
+    max_rows_returned:        int  = Field(default=1000, ge=1)
+    max_rows_affected:        int  = Field(default=100, ge=1)
+    allow_multi_statement:    bool = False
+    query_timeout_seconds:    int  = Field(default=30, ge=1)
+
+
+class PolicyScope(BaseModel):
+    allowed_databases: list[str] = Field(default_factory=list)
+    allowed_schemas:   list[str] = Field(default_factory=list)
+    allowed_tables:    list[str] = Field(default_factory=list)
+    denied_tables:     list[str] = Field(default_factory=list)
+
+
+class PolicyProfile(BaseModel):
+    profile_name: str
+    operations:   PolicyOperations  = Field(default_factory=PolicyOperations)
+    constraints:  PolicyConstraints = Field(default_factory=PolicyConstraints)
+    scope:        PolicyScope       = Field(default_factory=PolicyScope)
+
+
+class PolicyFile(BaseModel):
+    active_profile: str = "readonly"
+    profiles: dict[str, PolicyProfile]

sqlserver_semantic_mcp/server/app.py

@@ -0,0 +1,125 @@
+import json
+import logging
+from typing import Any, Awaitable, Callable, Optional
+
+from mcp.server import Server
+from mcp.types import Tool, TextContent
+
+from ..config import Config, get_config
+from ..services import metrics_service
+from ..services.policy_service import PolicyService
+from ..services.query_service import QueryService
+from ..workflows.facade import WorkflowFacade
+from .compact import compact
+
+logger = logging.getLogger(__name__)
+
+
+_WORKFLOW_TOOLS = frozenset({
+    "plan_or_execute_query",
+    "preview_safe_query",
+    "discover_relevant_tables",
+    "suggest_next_tool",
+    "estimate_execution_risk",
+    "bundle_context_for_next_step",
+    "score_join_candidate",
+    "summarize_table_for_joining",
+    "summarize_object_for_impact",
+})
+
+
+class Context:
+    def __init__(self, cfg: Config) -> None:
+        self.cfg = cfg
+        self.policy = PolicyService(cfg)
+        self.query = QueryService(self.policy, cfg)
+        self.workflow = WorkflowFacade(cfg, self.policy, self.query)
+
+
+_ctx: Context | None = None
+
+
+def get_context() -> Context:
+    global _ctx
+    if _ctx is None:
+        _ctx = Context(get_config())
+        _ctx.policy.load()
+    return _ctx
+
+
+def reset_context() -> None:
+    global _ctx
+    _ctx = None
+
+
+app = Server("sqlserver-semantic-mcp")
+
+ToolHandler = Callable[[dict[str, Any]], Awaitable[Any]]
+_TOOL_REGISTRY: dict[str, tuple[Tool, ToolHandler]] = {}
+
+
+def register_tool(tool: Tool, handler: ToolHandler) -> None:
+    if tool.name in _TOOL_REGISTRY:
+        raise ValueError(f"Duplicate tool registration: {tool.name}")
+    _TOOL_REGISTRY[tool.name] = (tool, handler)
+
+
+@app.list_tools()
+async def _list_tools() -> list[Tool]:
+    return [t for (t, _) in _TOOL_REGISTRY.values()]
+
+
+def _infer_workflow_metrics(name: str, shaped: Any) -> dict[str, Any]:
+    """Extract workflow-aware fields from the response envelope, if any."""
+    extras: dict[str, Any] = {}
+    if not isinstance(shaped, dict):
+        return extras
+    if name in _WORKFLOW_TOOLS:
+        extras["route_type"] = shaped.get("kind")
+    for key in ("detail", "response_mode", "token_budget_hint",
+                "next_action", "bundle_key"):
+        if key in shaped:
+            extras[key] = shaped.get(key)
+    data = shaped.get("data")
+    if isinstance(data, dict):
+        if "path" in data and "route_type" not in extras:
+            extras["route_type"] = data.get("path")
+        if name == "plan_or_execute_query":
+            extras["was_direct_execute"] = (
+                data.get("path") == "direct_execute"
+                and bool(data.get("executed"))
+            )
+        if "response_mode" not in extras and "response_mode" in data:
+            extras["response_mode"] = data.get("response_mode")
+    if "bundle_key" in shaped:
+        extras["bundle_used"] = True
+    return extras
+
+
+@app.call_tool()
+async def _call_tool(name: str, arguments: dict) -> list[TextContent]:
+    if name not in _TOOL_REGISTRY:
+        return [TextContent(type="text", text=f"Unknown tool: {name}")]
+    _t, handler = _TOOL_REGISTRY[name]
+    try:
+        result = await handler(arguments or {})
+        shaped = compact(result)
+        text = json.dumps(
+            shaped, ensure_ascii=False, default=str, separators=(",", ":"),
+        )
+        if get_config().metrics_enabled:
+            try:
+                extras = _infer_workflow_metrics(name, shaped)
+                await metrics_service.record_metric(
+                    get_config().cache_path, name,
+                    response_bytes=len(text.encode("utf-8")),
+                    array_length=len(shaped) if isinstance(shaped, list) else None,
+                    fields_returned=len(shaped) if isinstance(shaped, dict) else None,
+                    **extras,
+                )
+            except Exception:
+                logger.exception("metrics_service.record_metric failed")
+        return [TextContent(type="text", text=text)]
+    except Exception as e:
+        logger.exception("Tool %s raised", name)
+        return [TextContent(type="text", text=json.dumps({"error": str(e)}))]

sqlserver_semantic_mcp/server/compact.py

@@ -0,0 +1,74 @@
+"""Transport-layer response shaping helper.
+
+See docs/superpowers/specs/2026-04-19-p0-token-optimization-design.md for rules.
+"""
+from typing import Any
+
+NULLABLE_FALSE_KEEP: frozenset[str] = frozenset({"is_nullable"})
+
+
+def _is_falsy_strippable(value: Any) -> bool:
+    return value is None or value == [] or value == {} or value is False
+
+
+def _merge_table_id(d: dict) -> dict:
+    schema = d.get("schema_name")
+    table = d.get("table_name")
+    if not (isinstance(schema, str) and isinstance(table, str) and schema and table):
+        return d
+    out: dict[str, Any] = {}
+    merged = False
+    for k, v in d.items():
+        if k == "schema_name":
+            if not merged:
+                out["table"] = f"{schema}.{table}"
+                merged = True
+        elif k == "table_name":
+            continue
+        else:
+            out[k] = v
+    return out
+
+
+def _merge_object_id(d: dict) -> dict:
+    schema = d.get("schema")
+    name = d.get("object_name")
+    if not (isinstance(schema, str) and isinstance(name, str) and schema and name):
+        return d
+    out: dict[str, Any] = {}
+    merged = False
+    for k, v in d.items():
+        if k == "schema":
+            if not merged:
+                out["object"] = f"{schema}.{name}"
+                merged = True
+        elif k == "object_name":
+            continue
+        elif k == "object_type":
+            out["type"] = v
+        else:
+            out[k] = v
+    return out
+
+
+def compact(obj: Any) -> Any:
+    """Recursively strip falsy values and merge identifier pairs.
+
+    Application order within a dict: R2 (table merge) -> R3 (object merge) -> R1 (strip).
+    """
+    if isinstance(obj, dict):
+        merged = _merge_table_id(obj)
+        merged = _merge_object_id(merged)
+        out: dict[str, Any] = {}
+        for k, v in merged.items():
+            v = compact(v)
+            if k in NULLABLE_FALSE_KEEP and v is False:
+                out[k] = v
+                continue
+            if _is_falsy_strippable(v):
+                continue
+            out[k] = v
+        return out
+    if isinstance(obj, list):
+        return [compact(x) for x in obj]
+    return obj

sqlserver_semantic_mcp/server/prompts/__init__.py

@@ -0,0 +1,5 @@
+"""MCP prompts for agent-oriented workflows."""
+from . import execution, discovery, analysis  # noqa: F401
+from .registry import register_prompts
+
+__all__ = ["register_prompts"]

sqlserver_semantic_mcp/server/prompts/analysis.py

@@ -0,0 +1,56 @@
+"""Object / impact analysis prompts."""
+from __future__ import annotations
+
+from mcp.types import (
+    GetPromptResult, Prompt, PromptArgument, PromptMessage, TextContent,
+)
+
+from .registry import register_prompt
+
+
+_PROMPT = Prompt(
+    name="trace_data_impact",
+    description=(
+        "Trace the downstream impact of changing a view/procedure/function "
+        "without dumping raw SQL bodies into the context."
+    ),
+    arguments=[
+        PromptArgument(name="schema", required=True),
+        PromptArgument(name="name", required=True),
+        PromptArgument(
+            name="type",
+            description="VIEW | PROCEDURE | FUNCTION",
+            required=True,
+        ),
+    ],
+)
+
+
+_BODY = """You need to understand the impact of modifying {type} {schema}.{name}. Follow the impact chain:
+
+1. `summarize_object_for_impact(schema={schema!r}, name={name!r}, type={type!r})` — returns reads / writes / depends_on in compact form.
+2. `trace_object_dependencies(schema={schema!r}, name={name!r}, type={type!r})` — returns the dependency list.
+3. `bundle_context_for_next_step(items=[...], goal="object_impact")` — compress before recommending changes.
+
+Only request full definitions (`describe_view` / `describe_procedure` with detail="full") if the summaries leave a concrete gap.
+"""
+
+
+async def _handler(arguments: dict) -> GetPromptResult:
+    schema = arguments.get("schema", "")
+    name = arguments.get("name", "")
+    obj_type = (arguments.get("type") or "VIEW").upper()
+    text = _BODY.format(schema=schema, name=name, type=obj_type)
+    return GetPromptResult(
+        description="Impact analysis chain for schema objects.",
+        messages=[
+            PromptMessage(
+                role="user",
+                content=TextContent(type="text", text=text),
+            ),
+        ],
+    )
+
+
+def register() -> None:
+    register_prompt(_PROMPT, _handler)

sqlserver_semantic_mcp/server/prompts/discovery.py

@@ -0,0 +1,55 @@
+"""Discovery prompts."""
+from __future__ import annotations
+
+from mcp.types import (
+    GetPromptResult, Prompt, PromptArgument, PromptMessage, TextContent,
+)
+
+from .registry import register_prompt
+
+
+_PROMPT = Prompt(
+    name="discover_tables_for_business_question",
+    description=(
+        "Translate a natural-language question into the shortest discovery "
+        "chain — candidates → describe → join path."
+    ),
+    arguments=[
+        PromptArgument(
+            name="goal",
+            description="Free-form business question.",
+            required=True,
+        ),
+    ],
+)
+
+
+_BODY = """You have a business question but not the target tables. Follow the discovery chain:
+
+1. `discover_relevant_tables(goal={goal!r})` — returns a small ranked candidate set.
+2. For the top 2–3 candidates, call `describe_table(detail="brief")` only. Skip "full" until you must.
+3. If the question joins concepts, call `find_join_path` for each plausible pair, then `score_join_candidate` to pick the best.
+4. When you are confident, draft SQL and call `plan_or_execute_query` with mode="auto".
+
+Keep each step's detail level at "brief" unless the prior step surfaced ambiguity.
+
+Question: {goal}
+"""
+
+
+async def _handler(arguments: dict) -> GetPromptResult:
+    goal = arguments.get("goal", "")
+    text = _BODY.format(goal=goal)
+    return GetPromptResult(
+        description="Discovery chain for unknown tables.",
+        messages=[
+            PromptMessage(
+                role="user",
+                content=TextContent(type="text", text=text),
+            ),
+        ],
+    )
+
+
+def register() -> None:
+    register_prompt(_PROMPT, _handler)