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

sqlserver_semantic_mcp/server/prompts/execution.py

@@ -0,0 +1,64 @@
+"""Prompts for the direct-execution path."""
+from __future__ import annotations
+
+from mcp.types import (
+    GetPromptResult, Prompt, PromptArgument, PromptMessage, TextContent,
+)
+
+from .registry import register_prompt
+
+
+_PROMPT = Prompt(
+    name="safe_sql_execution",
+    description=(
+        "Execute an agent-authored SQL in the shortest safe path, using the "
+        "v0.5 plan_or_execute_query entry."
+    ),
+    arguments=[
+        PromptArgument(
+            name="query",
+            description="SQL the agent already believes is ready to run.",
+            required=True,
+        ),
+        PromptArgument(
+            name="return_mode",
+            description="summary | rows | sample | count_only (default: summary).",
+            required=False,
+        ),
+    ],
+)
+
+
+_BODY = """You have a SQL query already drafted. Prefer the shortest safe path:
+
+1. Call `plan_or_execute_query` with mode="auto" and return_mode={return_mode!r}.
+2. If the response has `path="direct_execute"` and `executed=true`, you are done — present the rows / summary as-is.
+3. If the response has `path="direct_validate"` and `allowed=false`, read `reason` and either:
+   - revise the SQL, or
+   - call `estimate_execution_risk` for more detail before revising.
+4. Do NOT call `get_tables` / `describe_table` / `find_join_path` first when the SQL is already known — that only wastes tokens.
+
+Query:
+```sql
+{query}
+```
+"""
+
+
+async def _handler(arguments: dict) -> GetPromptResult:
+    query = arguments.get("query", "")
+    return_mode = arguments.get("return_mode") or "summary"
+    text = _BODY.format(query=query, return_mode=return_mode)
+    return GetPromptResult(
+        description="Shortest safe path for SQL-ready agents.",
+        messages=[
+            PromptMessage(
+                role="user",
+                content=TextContent(type="text", text=text),
+            ),
+        ],
+    )
+
+
+def register() -> None:
+    register_prompt(_PROMPT, _handler)

sqlserver_semantic_mcp/server/prompts/registry.py

@@ -0,0 +1,41 @@
+"""Prompt registry wired up against ``server.app.app``."""
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable
+
+from mcp.types import GetPromptResult, Prompt, PromptArgument
+
+from ..app import app
+
+
+Handler = Callable[[dict[str, Any]], Awaitable[GetPromptResult]]
+_REGISTRY: dict[str, tuple[Prompt, Handler]] = {}
+
+
+def register_prompt(prompt: Prompt, handler: Handler) -> None:
+    _REGISTRY[prompt.name] = (prompt, handler)
+
+
+@app.list_prompts()
+async def _list_prompts() -> list[Prompt]:
+    return [p for (p, _) in _REGISTRY.values()]
+
+
+@app.get_prompt()
+async def _get_prompt(name: str, arguments: dict | None = None) -> GetPromptResult:
+    if name not in _REGISTRY:
+        raise ValueError(f"Unknown prompt: {name}")
+    _p, handler = _REGISTRY[name]
+    return await handler(arguments or {})
+
+
+def register_prompts() -> None:
+    """Import prompt modules to trigger their registrations."""
+    from . import execution, discovery, analysis  # noqa: F401
+
+    execution.register()
+    discovery.register()
+    analysis.register()
+
+
+__all__ = ["PromptArgument", "Prompt", "register_prompt", "register_prompts"]

sqlserver_semantic_mcp/server/resources/__init__.py

@@ -0,0 +1 @@
+from . import schema  # noqa: F401

sqlserver_semantic_mcp/server/resources/schema.py

@@ -0,0 +1,144 @@
+import json
+
+from mcp.types import Resource, ResourceTemplate
+from pydantic import AnyUrl
+
+from ...services import metadata_service, semantic_service, object_service
+from ..app import app, get_context
+
+
+@app.list_resources()
+async def list_resources() -> list[Resource]:
+    # Only resources without a tool equivalent are listed here.
+    # `get_tables` tool supersedes the old semantic://schema/tables resource.
+    return [
+        Resource(
+            uri=AnyUrl("semantic://summary/database"),
+            name="Database summary", mimeType="application/json",
+        ),
+    ]
+
+
+@app.list_resource_templates()
+async def list_resource_templates() -> list[ResourceTemplate]:
+    return [
+        ResourceTemplate(
+            uriTemplate="semantic://schema/tables/{qualified}",
+            name="Table metadata", mimeType="application/json",
+        ),
+        ResourceTemplate(
+            uriTemplate="semantic://analysis/classification/{qualified}",
+            name="Table classification", mimeType="application/json",
+        ),
+        ResourceTemplate(
+            uriTemplate="semantic://summary/table/{qualified}",
+            name="AI-ready table summary (join-focused)",
+            mimeType="application/json",
+        ),
+        ResourceTemplate(
+            uriTemplate="semantic://summary/object/{type}/{qualified}",
+            name="AI-ready object summary (reads/writes/depends)",
+            mimeType="application/json",
+        ),
+        ResourceTemplate(
+            uriTemplate="semantic://bundle/joining/{qualified}",
+            name="Joining bundle for a single table",
+            mimeType="application/json",
+        ),
+    ]
+
+
+def _split_qualified(qualified: str, uri: str) -> tuple[str, str]:
+    parts = qualified.split(".", 1)
+    if len(parts) != 2 or not parts[0] or not parts[1]:
+        raise ValueError(
+            f"Invalid resource URI '{uri}': expected schema.table format"
+        )
+    return parts[0], parts[1]
+
+
+@app.read_resource()
+async def read_resource(uri: AnyUrl) -> str:
+    ctx = get_context()
+    cp = ctx.cfg.cache_path
+    db = ctx.cfg.mssql_database
+    s = str(uri)
+
+    if s == "semantic://schema/tables":
+        return json.dumps(await metadata_service.list_tables(cp, db), default=str)
+
+    if s == "semantic://summary/database":
+        return json.dumps(
+            await metadata_service.database_summary(cp, db), default=str,
+        )
+
+    if s.startswith("semantic://schema/tables/"):
+        qualified = s[len("semantic://schema/tables/"):]
+        schema, table = _split_qualified(qualified, s)
+        return json.dumps(
+            await metadata_service.describe_table(cp, db, schema, table),
+            default=str,
+        )
+
+    if s.startswith("semantic://analysis/classification/"):
+        qualified = s[len("semantic://analysis/classification/"):]
+        schema, table = _split_qualified(qualified, s)
+        return json.dumps(
+            await semantic_service.classify_table(cp, db, schema, table),
+            default=str,
+        )
+
+    if s.startswith("semantic://analysis/dependencies/"):
+        qualified = s[len("semantic://analysis/dependencies/"):]
+        parts = qualified.split("/")
+        if len(parts) != 2:
+            raise ValueError(
+                f"Invalid resource URI '{s}': expected <type>/<schema>.<name>"
+            )
+        obj_type = parts[0].upper()
+        schema, name = _split_qualified(parts[1], s)
+        return json.dumps(
+            await object_service.describe_object(schema, name, obj_type, ctx.cfg),
+            default=str,
+        )
+
+    if s.startswith("semantic://summary/table/"):
+        qualified = s[len("semantic://summary/table/"):]
+        schema, table = _split_qualified(qualified, s)
+        summary = await semantic_service.summarize_for_joining(
+            cp, db, schema, table,
+        )
+        return json.dumps(summary or {}, default=str)
+
+    if s.startswith("semantic://summary/object/"):
+        rest = s[len("semantic://summary/object/"):]
+        parts = rest.split("/", 1)
+        if len(parts) != 2:
+            raise ValueError(
+                f"Invalid resource URI '{s}': expected <type>/<schema>.<name>"
+            )
+        obj_type = parts[0].upper()
+        schema, name = _split_qualified(parts[1], s)
+        obj = await object_service.describe_object(
+            schema, name, obj_type, ctx.cfg,
+        )
+        payload = {
+            "object": f"{schema}.{name}",
+            "type": obj_type,
+            "status": obj.get("status") if obj else None,
+            "reads": list((obj or {}).get("read_tables", []) or []),
+            "writes": list((obj or {}).get("write_tables", []) or []),
+            "depends_on": list((obj or {}).get("dependencies", []) or []),
+        }
+        return json.dumps(payload, default=str)
+
+    if s.startswith("semantic://bundle/joining/"):
+        qualified = s[len("semantic://bundle/joining/"):]
+        schema, table = _split_qualified(qualified, s)
+        bundle = await ctx.workflow.bundle_context_for_next_step(
+            [{"kind": "table", "schema": schema, "table": table}],
+            goal="joining",
+        )
+        return json.dumps(bundle, default=str)
+
+    raise ValueError(f"Unknown resource URI: {s}")

sqlserver_semantic_mcp/server/tools/__init__.py

@@ -0,0 +1,42 @@
+from . import (
+    metadata, policy, query, cache,
+    relationship, object_tool, semantic, metrics, workflow,
+)  # noqa: F401
+
+
+_GROUP_REGISTRATIONS = {
+    "metadata":     metadata.register,
+    "policy":       policy.register,
+    "query":        query.register,
+    "cache":        cache.register,
+    "relationship": relationship.register,
+    "object":       object_tool.register,
+    "semantic":     semantic.register,
+    "metrics":      metrics.register,
+    "workflow":     workflow.register,
+}
+
+
+def _resolve_profile_groups(profile: str) -> list[str]:
+    if not profile or profile == "all":
+        return list(_GROUP_REGISTRATIONS.keys())
+    requested = [g.strip() for g in profile.split(",") if g.strip()]
+    if not requested:
+        return list(_GROUP_REGISTRATIONS.keys())
+    unknown = [g for g in requested if g not in _GROUP_REGISTRATIONS]
+    if unknown:
+        raise ValueError(
+            f"Unknown tool profile group(s): {', '.join(unknown)}. "
+            f"Valid groups: {', '.join(sorted(_GROUP_REGISTRATIONS.keys()))}"
+        )
+    return requested
+
+
+def register_all() -> None:
+    from ...config import get_config
+    cfg = get_config()
+    groups = _resolve_profile_groups(cfg.tool_profile)
+    if not cfg.workflow_tools_enabled and "workflow" in groups:
+        groups = [g for g in groups if g != "workflow"]
+    for group in groups:
+        _GROUP_REGISTRATIONS[group]()

sqlserver_semantic_mcp/server/tools/cache.py

@@ -0,0 +1,24 @@
+from mcp.types import Tool
+
+from ...infrastructure.cache.structural import warmup_structural_cache
+from ..app import get_context, register_tool
+
+
+def register() -> None:
+    register_tool(
+        Tool(
+            name="refresh_schema_cache",
+            description=(
+                "Re-fetch structural metadata from SQL Server and update SQLite cache. "
+                "Semantic rows whose hash changed become 'dirty' and will recompute."
+            ),
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        _refresh,
+    )
+
+
+async def _refresh(args: dict) -> dict:
+    ctx = get_context()
+    result = await warmup_structural_cache(ctx.cfg)
+    return {"refreshed": True, **result}

sqlserver_semantic_mcp/server/tools/metadata.py

@@ -0,0 +1,167 @@
+from typing import Optional
+
+from mcp.types import Tool
+
+from ...services import metadata_service, semantic_service
+from ..app import get_context, register_tool
+from .shape import (
+    project_describe_table, project_get_columns, resolve_detail,
+)
+
+
+_DETAIL_PROP = {
+    "type": "string", "enum": ["brief", "standard", "full"],
+    "default": "brief",
+    "description": "Response verbosity. brief = minimal identification + counts; "
+                   "standard = columns+FKs; full = indexes+descriptions.",
+}
+
+
+_BUDGET_PROP = {
+    "type": "string", "enum": ["tiny", "low", "medium", "high"],
+    "description": "Payload budget hint. tiny = minimum; high = full.",
+}
+
+
+_BUDGET_LIMITS = {
+    "tiny":   20,
+    "low":    100,
+    "medium": 500,
+    "high":   2000,
+}
+
+
+def register() -> None:
+    register_tool(
+        Tool(
+            name="get_tables",
+            description=(
+                "List tables in the database. Supports schema / keyword filters "
+                "so the response stays small on large DBs. Pass limit or "
+                "token_budget_hint to further cap the payload."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "schema":  {"oneOf": [{"type": "string"},
+                                          {"type": "array",
+                                           "items": {"type": "string"}}]},
+                    "keyword": {"type": "string"},
+                    "limit":   {"type": "integer", "minimum": 1},
+                    "token_budget_hint": _BUDGET_PROP,
+                },
+            },
+        ),
+        _get_tables,
+    )
+    register_tool(
+        Tool(
+            name="describe_table",
+            description=(
+                "Return table metadata. detail=brief (default) returns a compact "
+                "summary {table, column_count, pk, fk_to, important_columns, "
+                "classification}. standard adds columns+FKs; full adds indexes "
+                "and descriptions."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "schema": {"type": "string"},
+                    "table":  {"type": "string"},
+                    "detail": _DETAIL_PROP,
+                },
+                "required": ["schema", "table"],
+            },
+        ),
+        _describe_table,
+    )
+    register_tool(
+        Tool(
+            name="get_columns",
+            description=(
+                "List columns of a table. detail=brief (default) returns name + "
+                "semantic tag only; standard adds type/nullable; full returns "
+                "all metadata."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "schema": {"type": "string"},
+                    "table":  {"type": "string"},
+                    "detail": _DETAIL_PROP,
+                },
+                "required": ["schema", "table"],
+            },
+        ),
+        _get_columns,
+    )
+
+
+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
+
+
+def _resolve_list_limit(args: dict, cfg_default: str) -> int | None:
+    explicit = args.get("limit")
+    if isinstance(explicit, int) and explicit > 0:
+        return explicit
+    hint = args.get("token_budget_hint") or cfg_default
+    return _BUDGET_LIMITS.get(hint)
+
+
+async def _get_tables(args: dict) -> list[dict]:
+    ctx = get_context()
+    schemas = _normalize_schema_filter(args.get("schema"))
+    keyword = args.get("keyword") or None
+    rows = await metadata_service.list_tables(
+        ctx.cfg.cache_path, ctx.cfg.mssql_database,
+        schemas=schemas, keyword=keyword,
+    )
+    cap = _resolve_list_limit(args, ctx.cfg.default_token_budget_hint)
+    if cap is not None and len(rows) > cap:
+        return rows[:cap]
+    return rows
+
+
+async def _describe_table(args: dict) -> Optional[dict]:
+    ctx = get_context()
+    detail = resolve_detail(args)
+    cp = ctx.cfg.cache_path
+    db = ctx.cfg.mssql_database
+    schema = args["schema"]
+    table = args["table"]
+
+    full = await metadata_service.describe_table(cp, db, schema, table)
+    if full is None:
+        return None
+
+    classification = await semantic_service.classify_table(cp, db, schema, table)
+    semantic_map = {
+        c["column_name"]: (semantic_service._column_semantic(c) or "generic")
+        for c in full.get("columns", [])
+    }
+    return project_describe_table(
+        full, detail=detail,
+        classification=classification, column_semantics=semantic_map,
+    )
+
+
+async def _get_columns(args: dict) -> list[dict]:
+    ctx = get_context()
+    detail = resolve_detail(args)
+    cols = await metadata_service.list_columns(
+        ctx.cfg.cache_path, ctx.cfg.mssql_database,
+        args["schema"], args["table"],
+    )
+    semantic_map = {
+        c["column_name"]: (semantic_service._column_semantic(c) or "generic")
+        for c in cols
+    }
+    return project_get_columns(cols, detail=detail, semantic_map=semantic_map)

sqlserver_semantic_mcp/server/tools/metrics.py

@@ -0,0 +1,44 @@
+from mcp.types import Tool
+
+from ...services import metrics_service
+from ..app import get_context, register_tool
+
+
+def register() -> None:
+    register_tool(
+        Tool(
+            name="get_tool_metrics",
+            description=(
+                "Return per-tool payload metrics (call_count, total_bytes, "
+                "avg_bytes, p95_bytes, max_bytes) ordered by total_bytes desc. "
+                "Use to find the heaviest tools for optimization targeting."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "limit": {"type": "integer", "minimum": 1, "default": 10},
+                },
+            },
+        ),
+        _top,
+    )
+    register_tool(
+        Tool(
+            name="reset_tool_metrics",
+            description="Delete all recorded tool metrics. Returns deleted count.",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        _reset,
+    )
+
+
+async def _top(args: dict) -> list[dict]:
+    ctx = get_context()
+    limit = int(args.get("limit", 10))
+    return await metrics_service.query_top_tools(ctx.cfg.cache_path, limit=limit)
+
+
+async def _reset(args: dict) -> dict:
+    ctx = get_context()
+    n = await metrics_service.clear_metrics(ctx.cfg.cache_path)
+    return {"deleted": n}

sqlserver_semantic_mcp/server/tools/object_tool.py

@@ -0,0 +1,113 @@
+import hashlib
+from typing import Any
+
+from mcp.types import Tool
+
+from ...services import object_service
+from ..app import get_context, register_tool
+from .shape import project_describe_object, resolve_detail
+
+
+_DETAIL_PROP = {
+    "type": "string", "enum": ["brief", "standard", "full"],
+    "default": "brief",
+    "description": "Response verbosity. brief strips definition; full always "
+                   "includes it. include_definition overrides to include at "
+                   "brief/standard tiers.",
+}
+
+
+def _input_schema() -> dict:
+    return {
+        "type": "object",
+        "properties": {
+            "schema":             {"type": "string"},
+            "name":               {"type": "string"},
+            "detail":             _DETAIL_PROP,
+            "include_definition": {"type": "boolean", "default": False},
+        },
+        "required": ["schema", "name"],
+    }
+
+
+def register() -> None:
+    register_tool(
+        Tool(
+            name="describe_view",
+            description=(
+                "Return view metadata + dependencies. detail=brief (default) "
+                "strips SQL definition; detail=full or include_definition=true "
+                "returns the full text."
+            ),
+            inputSchema=_input_schema(),
+        ),
+        _describe_view,
+    )
+    register_tool(
+        Tool(
+            name="describe_procedure",
+            description=(
+                "Return procedure metadata + dependencies. detail=brief (default) "
+                "strips SQL definition; detail=full or include_definition=true "
+                "returns the full text."
+            ),
+            inputSchema=_input_schema(),
+        ),
+        _describe_procedure,
+    )
+    register_tool(
+        Tool(
+            name="trace_object_dependencies",
+            description="Return a list of objects/tables the given object depends on.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "schema": {"type": "string"},
+                    "name":   {"type": "string"},
+                    "type":   {"type": "string",
+                               "enum": ["VIEW", "PROCEDURE", "FUNCTION"]},
+                },
+                "required": ["schema", "name", "type"],
+            },
+        ),
+        _trace,
+    )
+
+
+def _attach_hash_and_bytes(obj: dict) -> dict:
+    definition = obj.get("definition")
+    if not isinstance(definition, str) or not definition:
+        return obj
+    if "definition_hash" in obj and "definition_bytes" in obj:
+        return obj
+    encoded = definition.encode("utf-8")
+    out = dict(obj)
+    out.setdefault("definition_hash", hashlib.sha1(encoded).hexdigest()[:8])
+    out.setdefault("definition_bytes", len(encoded))
+    return out
+
+
+async def _describe_object(args: dict, object_type: str) -> dict:
+    ctx = get_context()
+    detail = resolve_detail(args)
+    include = bool(args.get("include_definition", False))
+    obj = await object_service.describe_object(
+        args["schema"], args["name"], object_type, ctx.cfg,
+    )
+    obj = _attach_hash_and_bytes(obj)
+    return project_describe_object(obj, detail=detail, include_definition=include)
+
+
+async def _describe_view(args: dict) -> dict:
+    return await _describe_object(args, "VIEW")
+
+
+async def _describe_procedure(args: dict) -> dict:
+    return await _describe_object(args, "PROCEDURE")
+
+
+async def _trace(args: dict) -> list[str]:
+    ctx = get_context()
+    return await object_service.trace_dependencies(
+        args["schema"], args["name"], args["type"], ctx.cfg,
+    )