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

sqlserver_semantic_mcp/server/tools/workflow.py

@@ -0,0 +1,307 @@
+"""Workflow-layer MCP tools (v0.5)."""
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.types import Tool
+
+from ...services import relationship_service, semantic_service, object_service
+from ..app import get_context, register_tool
+
+
+_DETAIL_PROP = {
+    "type": "string", "enum": ["brief", "standard", "full"], "default": "brief",
+}
+
+
+def register() -> None:
+    register_tool(
+        Tool(
+            name="discover_relevant_tables",
+            description=(
+                "Return a small, ranked candidate set for a natural-language "
+                "goal. Use before describe_table / find_join_path when the "
+                "target tables are not yet known."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "goal":    {"type": "string"},
+                    "schemas": {"type": "array",
+                                "items": {"type": "string"}},
+                    "keyword": {"type": "string"},
+                    "limit":   {"type": "integer", "minimum": 1, "default": 10},
+                    "classify": {"type": "boolean", "default": False},
+                },
+                "required": ["goal"],
+            },
+        ),
+        _discover,
+    )
+    register_tool(
+        Tool(
+            name="suggest_next_tool",
+            description=(
+                "Given the agent's current state (optional query, goal, or "
+                "discovered context), return the recommended next tool call. "
+                "Runs no DB queries."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query":           {"type": "string"},
+                    "goal":            {"type": "string"},
+                    "have_candidates": {"type": "boolean", "default": False},
+                    "have_join_path":  {"type": "boolean", "default": False},
+                    "have_object":     {"type": "string"},
+                },
+            },
+        ),
+        _suggest,
+    )
+    register_tool(
+        Tool(
+            name="bundle_context_for_next_step",
+            description=(
+                "Compress prior tool results into the minimum context the "
+                "next tool needs. goal=joining expects items [{kind:table, "
+                "schema, table}]; goal=object_impact expects [{kind:object, "
+                "schema, object_name, object_type}]."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "items": {
+                        "type": "array",
+                        "items": {"type": "object"},
+                    },
+                    "goal":   {"type": "string",
+                               "enum": ["joining", "object_impact"],
+                               "default": "joining"},
+                    "detail": _DETAIL_PROP,
+                },
+                "required": ["items"],
+            },
+        ),
+        _bundle,
+    )
+    register_tool(
+        Tool(
+            name="score_join_candidate",
+            description=(
+                "Compute a usability score for a join path candidate. "
+                "Penalises excess hops and bridge/audit/lookup hops."
+            ),
+            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"],
+            },
+        ),
+        _score_join,
+    )
+    register_tool(
+        Tool(
+            name="summarize_table_for_joining",
+            description=(
+                "Return a compact join-ready summary for a single table — "
+                "classification, PK, important columns, FK edges."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "schema": {"type": "string"},
+                    "table":  {"type": "string"},
+                },
+                "required": ["schema", "table"],
+            },
+        ),
+        _summarize_table,
+    )
+    register_tool(
+        Tool(
+            name="summarize_object_for_impact",
+            description=(
+                "Return a compact impact summary for a VIEW/PROCEDURE/FUNCTION "
+                "— reads, writes, depends_on."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "schema": {"type": "string"},
+                    "name":   {"type": "string"},
+                    "type":   {"type": "string",
+                               "enum": ["VIEW", "PROCEDURE", "FUNCTION"]},
+                },
+                "required": ["schema", "name", "type"],
+            },
+        ),
+        _summarize_object,
+    )
+
+
+# ---- handlers ---------------------------------------------------------------
+
+
+async def _discover(args: dict) -> dict:
+    ctx = get_context()
+    schemas = args.get("schemas") or None
+    return await ctx.workflow.discover_relevant_tables(
+        args["goal"],
+        schemas=schemas,
+        keyword=args.get("keyword"),
+        limit=int(args.get("limit", 10)),
+        classify=bool(args.get("classify", False)),
+    )
+
+
+async def _suggest(args: dict) -> dict:
+    ctx = get_context()
+    return ctx.workflow.suggest_next_tool(
+        query=args.get("query"),
+        goal=args.get("goal"),
+        have_candidates=bool(args.get("have_candidates", False)),
+        have_join_path=bool(args.get("have_join_path", False)),
+        have_object=args.get("have_object"),
+    )
+
+
+async def _bundle(args: dict) -> dict:
+    ctx = get_context()
+    return await ctx.workflow.bundle_context_for_next_step(
+        args["items"],
+        goal=args.get("goal", "joining"),
+        detail=args.get("detail", "brief"),
+    )
+
+
+# ---- reasoning helpers ------------------------------------------------------
+
+
+_CLASSIFICATION_PENALTY = {
+    "bridge": 0.25,
+    "audit":  0.2,
+    "lookup": 0.1,
+}
+
+
+async def _score_join(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),
+    )
+
+    if path is None:
+        return {
+            "kind": "score_join_candidate",
+            "detail": "brief",
+            "found": False,
+            "next_action": "broaden_or_pick_different_start",
+            "recommended_tool": "discover_relevant_tables",
+            "data": {"score": 0.0, "path": [], "penalties": []},
+        }
+
+    hops = len(path)
+    score = 1.0 - (0.15 * max(hops - 1, 0))
+    penalties: list[dict] = []
+
+    for edge in path:
+        schema = edge.get("to_schema")
+        table = edge.get("to_table")
+        if not schema or not table:
+            continue
+        cls = await semantic_service.classify_table(
+            ctx.cfg.cache_path, ctx.cfg.mssql_database, schema, table,
+        )
+        penalty = _CLASSIFICATION_PENALTY.get(cls.get("type"), 0.0)
+        if penalty:
+            score -= penalty
+            penalties.append({
+                "at": f"{schema}.{table}",
+                "classification": cls.get("type"),
+                "penalty": penalty,
+            })
+
+    score = max(0.0, min(1.0, score))
+
+    return {
+        "kind": "score_join_candidate",
+        "detail": "brief",
+        "found": True,
+        "confidence": score,
+        "next_action": "execute" if score >= 0.5 else "consider_alternatives",
+        "recommended_tool": (
+            "plan_or_execute_query" if score >= 0.5 else "find_join_path"
+        ),
+        "data": {
+            "score": round(score, 3),
+            "hops": hops,
+            "path": path,
+            "penalties": penalties,
+        },
+    }
+
+
+async def _summarize_table(args: dict) -> Any:
+    ctx = get_context()
+    summary = await semantic_service.summarize_for_joining(
+        ctx.cfg.cache_path, ctx.cfg.mssql_database,
+        args["schema"], args["table"],
+    )
+    if summary is None:
+        return {
+            "kind": "summarize_table_for_joining",
+            "detail": "brief",
+            "next_action": "broaden_search",
+            "recommended_tool": "get_tables",
+            "data": {"error": "table not found"},
+        }
+    return {
+        "kind": "summarize_table_for_joining",
+        "detail": "brief",
+        "next_action": "find_or_score_join",
+        "recommended_tool": "find_join_path",
+        "data": summary,
+    }
+
+
+async def _summarize_object(args: dict) -> dict:
+    ctx = get_context()
+    obj = await object_service.describe_object(
+        args["schema"], args["name"], args["type"], ctx.cfg,
+    )
+    if not obj or obj.get("status") == "error":
+        return {
+            "kind": "summarize_object_for_impact",
+            "detail": "brief",
+            "next_action": "revise",
+            "recommended_tool": "describe_view",
+            "data": {
+                "object": f"{args['schema']}.{args['name']}",
+                "type": args["type"],
+                "error": obj.get("error_message") if obj else "not found",
+            },
+        }
+    return {
+        "kind": "summarize_object_for_impact",
+        "detail": "brief",
+        "next_action": "trace_impact",
+        "recommended_tool": "trace_object_dependencies",
+        "data": {
+            "object": f"{args['schema']}.{args['name']}",
+            "type": args["type"],
+            "reads": list(obj.get("read_tables", []) or []),
+            "writes": list(obj.get("write_tables", []) or []),
+            "depends_on": list(obj.get("dependencies", []) or []),
+        },
+    }

sqlserver_semantic_mcp/services/metadata_service.py

@@ -0,0 +1,173 @@
+from typing import Optional
+import aiosqlite
+
+
+async def _list_columns_from_db(
+    db: aiosqlite.Connection,
+    database: str,
+    schema: str,
+    table: str,
+) -> list[dict]:
+    cur = await db.execute(
+        "SELECT column_name, data_type, max_length, is_nullable, "
+        "column_default, ordinal_position "
+        "FROM sc_columns "
+        "WHERE database_name=? AND schema_name=? AND table_name=? "
+        "ORDER BY ordinal_position",
+        (database, schema, table),
+    )
+    cols = [dict(r) for r in await cur.fetchall()]
+
+    cur = await db.execute(
+        "SELECT column_name, description FROM sc_comments "
+        "WHERE database_name=? AND schema_name=? AND object_name=? "
+        "AND column_name<>''",
+        (database, schema, table),
+    )
+    comments = {r["column_name"]: r["description"]
+                for r in await cur.fetchall()}
+
+    for c in cols:
+        c["is_nullable"] = bool(c["is_nullable"])
+        c["default_value"] = c.pop("column_default", None)
+        c["description"] = comments.get(c["column_name"])
+    return cols
+
+
+async def list_tables(
+    db_path: str, database: str, *,
+    schemas: Optional[list[str]] = None,
+    keyword: Optional[str] = None,
+) -> list[dict]:
+    sql = ("SELECT schema_name, table_name FROM sc_tables "
+           "WHERE database_name = ?")
+    params: list = [database]
+
+    if schemas:
+        placeholders = ",".join("?" for _ in schemas)
+        sql += f" AND schema_name IN ({placeholders})"
+        params.extend(schemas)
+
+    if keyword:
+        sql += (" AND (LOWER(schema_name || '.' || table_name) "
+                "LIKE ? ESCAPE '\\')")
+        kw = keyword.lower().replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        params.append(f"%{kw}%")
+
+    sql += " ORDER BY schema_name, table_name"
+
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cur = await db.execute(sql, tuple(params))
+        return [dict(r) for r in await cur.fetchall()]
+
+
+async def list_columns(
+    db_path: str, database: str, schema: str, table: str,
+) -> list[dict]:
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        return await _list_columns_from_db(db, database, schema, table)
+
+
+async def describe_table(
+    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 1 FROM sc_tables WHERE database_name=? "
+            "AND schema_name=? AND table_name=?",
+            (database, schema, table),
+        )
+        if not await cur.fetchone():
+            return None
+
+        columns = await _list_columns_from_db(db, database, schema, table)
+
+        cur = await db.execute(
+            "SELECT column_name FROM sc_primary_keys "
+            "WHERE database_name=? AND schema_name=? AND table_name=?",
+            (database, schema, table),
+        )
+        pk = [r["column_name"] for r in await cur.fetchall()]
+
+        cur = await db.execute(
+            "SELECT column_name, ref_schema, ref_table, ref_column "
+            "FROM sc_foreign_keys "
+            "WHERE database_name=? AND schema_name=? AND table_name=?",
+            (database, schema, table),
+        )
+        fks = [dict(r) for r in await cur.fetchall()]
+
+        cur = await db.execute(
+            "SELECT index_name, is_unique, is_primary_key, columns "
+            "FROM sc_indexes "
+            "WHERE database_name=? AND schema_name=? AND table_name=?",
+            (database, schema, table),
+        )
+        indexes = []
+        for r in await cur.fetchall():
+            indexes.append({
+                "index_name": r["index_name"],
+                "is_unique": bool(r["is_unique"]),
+                "is_primary_key": bool(r["is_primary_key"]),
+                "columns": r["columns"].split(",") if r["columns"] else [],
+            })
+
+        cur = await db.execute(
+            "SELECT description FROM sc_comments "
+            "WHERE database_name=? AND schema_name=? AND object_name=? "
+            "AND column_name=''",
+            (database, schema, table),
+        )
+        row = await cur.fetchone()
+        description = row["description"] if row else None
+
+    return {
+        "schema_name": schema,
+        "table_name": table,
+        "columns": columns,
+        "primary_key": pk,
+        "foreign_keys": fks,
+        "indexes": indexes,
+        "description": description,
+    }
+
+
+async def database_summary(db_path: str, database: str) -> dict:
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        counts = {}
+        for tbl in ["sc_tables", "sc_columns", "sc_foreign_keys",
+                    "sc_indexes", "sc_objects"]:
+            cur = await db.execute(
+                f"SELECT COUNT(*) AS n FROM {tbl} WHERE database_name=?",
+                (database,),
+            )
+            counts[tbl] = (await cur.fetchone())["n"]
+
+        cur = await db.execute(
+            "SELECT object_type, COUNT(*) AS n FROM sc_objects "
+            "WHERE database_name=? GROUP BY object_type",
+            (database,),
+        )
+        object_counts = {r["object_type"]: r["n"]
+                         for r in await cur.fetchall()}
+
+        cur = await db.execute(
+            "SELECT * FROM schema_version WHERE database_name=?",
+            (database,),
+        )
+        ver = await cur.fetchone()
+
+    return {
+        "database_name": database,
+        "table_count": counts["sc_tables"],
+        "column_count": counts["sc_columns"],
+        "foreign_key_count": counts["sc_foreign_keys"],
+        "index_count": counts["sc_indexes"],
+        "object_count": counts["sc_objects"],
+        "objects_by_type": object_counts,
+        "schema_version": dict(ver) if ver else None,
+    }

sqlserver_semantic_mcp/services/metrics_service.py

@@ -0,0 +1,124 @@
+"""Per-tool response metrics recording and query.
+
+See docs/superpowers/specs/2026-04-19-p4-measurement-design.md for the
+original design. v0.5 extends the record with workflow-aware fields so
+the team can measure how many tasks complete via the direct-execute
+fast path and which tools still dominate the token budget.
+"""
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+import aiosqlite
+
+
+_EXTRA_FIELDS = (
+    "route_type",
+    "detail",
+    "response_mode",
+    "token_budget_hint",
+    "was_direct_execute",
+    "bundle_used",
+    "next_action",
+)
+
+
+async def _ensure_extra_columns(db: aiosqlite.Connection) -> None:
+    """Best-effort migration for in-place stores created before v0.5."""
+    cur = await db.execute("PRAGMA table_info(tool_metrics)")
+    existing = {row[1] for row in await cur.fetchall()}
+    for col in _EXTRA_FIELDS:
+        if col not in existing:
+            coltype = "INTEGER" if col in ("was_direct_execute", "bundle_used") else "TEXT"
+            await db.execute(
+                f"ALTER TABLE tool_metrics ADD COLUMN {col} {coltype}"
+            )
+    await db.commit()
+
+
+async def record_metric(
+    db_path: str, tool_name: str, *,
+    response_bytes: int,
+    array_length: Optional[int] = None,
+    fields_returned: Optional[int] = None,
+    route_type: Optional[str] = None,
+    detail: Optional[str] = None,
+    response_mode: Optional[str] = None,
+    token_budget_hint: Optional[str] = None,
+    was_direct_execute: Optional[bool] = None,
+    bundle_used: Optional[bool] = None,
+    next_action: Optional[str] = None,
+) -> None:
+    async with aiosqlite.connect(db_path) as db:
+        await _ensure_extra_columns(db)
+        await db.execute(
+            "INSERT INTO tool_metrics "
+            "(tool_name, response_bytes, array_length, fields_returned, "
+            " route_type, detail, response_mode, token_budget_hint, "
+            " was_direct_execute, bundle_used, next_action, recorded_at) "
+            "VALUES (?,?,?,?,?,?,?,?,?,?,?,?)",
+            (
+                tool_name, response_bytes, array_length, fields_returned,
+                route_type, detail, response_mode, token_budget_hint,
+                1 if was_direct_execute else (0 if was_direct_execute is False else None),
+                1 if bundle_used else (0 if bundle_used is False else None),
+                next_action,
+                datetime.now(timezone.utc).isoformat(),
+            ),
+        )
+        await db.commit()
+
+
+def _p95(values: list[int]) -> int:
+    if not values:
+        return 0
+    vs = sorted(values)
+    idx = max(0, int(0.95 * len(vs)) - 1)
+    return vs[idx]
+
+
+async def query_top_tools(db_path: str, *, limit: int = 10) -> list[dict]:
+    """Return tool metrics aggregated, ordered by total_bytes desc."""
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        await _ensure_extra_columns(db)
+        cur = await db.execute(
+            "SELECT tool_name, COUNT(*) AS call_count, "
+            "       SUM(response_bytes) AS total_bytes, "
+            "       AVG(response_bytes) AS avg_bytes, "
+            "       MAX(response_bytes) AS max_bytes, "
+            "       SUM(CASE WHEN was_direct_execute=1 THEN 1 ELSE 0 END) "
+            "           AS direct_execute_count, "
+            "       SUM(CASE WHEN bundle_used=1 THEN 1 ELSE 0 END) "
+            "           AS bundle_count "
+            "FROM tool_metrics "
+            "GROUP BY tool_name "
+            "ORDER BY total_bytes DESC "
+            "LIMIT ?",
+            (limit,),
+        )
+        aggregated = [dict(r) for r in await cur.fetchall()]
+
+        for row in aggregated:
+            cur = await db.execute(
+                "SELECT response_bytes FROM tool_metrics "
+                "WHERE tool_name=? ORDER BY response_bytes",
+                (row["tool_name"],),
+            )
+            values = [r[0] for r in await cur.fetchall()]
+            row["p95_bytes"] = _p95(values)
+            row["avg_bytes"] = int(row["avg_bytes"] or 0)
+        return aggregated
+
+
+async def clear_metrics(db_path: str) -> int:
+    async with aiosqlite.connect(db_path) as db:
+        cur = await db.execute("DELETE FROM tool_metrics")
+        await db.commit()
+        return cur.rowcount
+
+
+__all__: list[str] = [
+    "record_metric",
+    "query_top_tools",
+    "clear_metrics",
+]