pretensor 0.1.0__py3-none-any.whl

pretensor/mcp/resources/markdown.py

@@ -0,0 +1,314 @@
+"""MCP markdown resources (databases, per-db overview, clusters, metrics)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pretensor.intelligence.cluster_labeler import HEURISTIC_CLUSTER_DESCRIPTION
+from pretensor.mcp.payload_types import iso_format, stale_threshold_days, staleness_days
+from pretensor.mcp.service_context import (
+    get_effective_graph_config,
+    get_effective_visibility_filter,
+)
+from pretensor.mcp.service_registry import (
+    counts_for_graph,
+    graph_path_for_entry,
+    load_registry,
+    open_store_for_entry,
+    release_store,
+    resolve_registry_entry,
+)
+from pretensor.mcp.tools.list import list_databases_payload
+from pretensor.visibility.filter import VisibilityFilter
+
+
+def clusters_resource_markdown(
+    graph_dir: Path,
+    name: str,
+    *,
+    visibility_filter: VisibilityFilter | None = None,
+) -> str:
+    """Markdown for ``pretensor://db/{name}/clusters``."""
+    reg = load_registry(graph_dir)
+    entry = resolve_registry_entry(reg, name)
+    if entry is None:
+        return f"# Unknown database `{name}`\n\nNo matching registry entry."
+    gp = graph_path_for_entry(entry)
+    if not gp.exists():
+        return f"# Clusters — {name}\n\n_Graph file missing._"
+
+    db_key = str(entry.database)
+    vf = visibility_filter or get_effective_visibility_filter()
+    cn = str(entry.connection_name)
+    store = open_store_for_entry(entry)
+    try:
+        rows = store.query_all_rows(
+            """
+            MATCH (t:SchemaTable)-[:IN_CLUSTER]->(c:Cluster)
+            WHERE c.database_key = $db
+            RETURN c.label, c.description, c.cohesion_score,
+                   collect(concat(t.schema_name, '.', t.table_name)) AS tables
+            ORDER BY c.cohesion_score DESC
+            """,
+            {"db": db_key},
+        )
+        lines = [
+            f"# Domain Clusters — {entry.connection_name}",
+            "",
+            f"_Logical database:_ `{db_key}`",
+            "",
+        ]
+        if not rows:
+            lines.append("_No clusters indexed yet; re-run `pretensor index`._")
+            return "\n".join(lines)
+
+        for lab, desc, coh, tables in rows:
+            tlist = [str(x) for x in (tables or []) if x]
+            if vf is not None:
+                filtered: list[str] = []
+                for qual in tlist:
+                    if "." not in qual:
+                        continue
+                    sn, _, tn = qual.partition(".")
+                    if vf.is_table_visible(cn, sn, tn):
+                        filtered.append(qual)
+                tlist = sorted(set(filtered))
+            else:
+                tlist = sorted(set(tlist))
+            cohesion = float(coh) if coh is not None else 0.0
+            lines.append(f"## {lab} _(cohesion: {cohesion:.2f})_")
+            lines.append("")
+            if desc and str(desc) != HEURISTIC_CLUSTER_DESCRIPTION:
+                lines.append(str(desc))
+                lines.append("")
+            show = tlist[:40]
+            suffix = f" and {len(tlist) - 40} more" if len(tlist) > 40 else ""
+            lines.append("**Tables:** " + ", ".join(show) + suffix)
+            lines.append("")
+        lines.append(
+            f"*Last indexed: {iso_format(entry.last_indexed_at)}. "
+            "Use `context` for table detail or `traverse` for join paths.*"
+        )
+        return "\n".join(lines)
+    finally:
+        release_store(store)
+
+
+def databases_resource_markdown(
+    graph_dir: Path,
+    *,
+    visibility_filter: VisibilityFilter | None = None,
+) -> str:
+    """Markdown for ``pretensor://databases``."""
+    data = list_databases_payload(graph_dir, visibility_filter=visibility_filter)
+    lines = ["# Indexed databases", ""]
+    for item in data["databases"]:
+        lines.append(f"## {item['name']}")
+        # ``database`` is omitted from the payload when it equals ``name`` (see
+        # list_databases_payload); fall back to ``name`` for the markdown row.
+        lines.append(f"- **Database:** {item.get('database', item['name'])}")
+        lines.append(f"- **Tables:** {item['table_count']}")
+        lines.append(f"- **Row count (sum):** {item['row_count']}")
+        schemas = item.get("schemas") or []
+        lines.append("- **Schemas:** " + (", ".join(schemas) if schemas else "_none_"))
+        lines.append(
+            f"- **dbt manifest:** {item.get('has_dbt_manifest', 'not_attempted')}"
+        )
+        lines.append(
+            f"- **LLM enrichment:** {item.get('has_llm_enrichment', 'not_attempted')}"
+        )
+        lines.append(
+            f"- **External consumers:** {item.get('has_external_consumers', 'not_attempted')}"
+        )
+        lines.append(f"- **Last indexed:** {item['last_indexed']}")
+        lines.append(f"- **Stale (>7d):** {item['is_stale']}")
+        lines.append(f"- **Graph:** `{item['graph_path']}`")
+        lines.append("")
+    if len(data["databases"]) == 0:
+        lines.append("_No entries in registry._")
+    return "\n".join(lines)
+
+
+def db_overview_resource_markdown(
+    graph_dir: Path,
+    name: str,
+    *,
+    visibility_filter: VisibilityFilter | None = None,
+) -> str:
+    """Markdown for ``pretensor://db/{name}/overview``."""
+    reg = load_registry(graph_dir)
+    entry = resolve_registry_entry(reg, name)
+    if entry is None:
+        return f"# Unknown database `{name}`\n\nNo matching registry entry."
+    gp = graph_path_for_entry(entry)
+    entity_count = 0
+    table_count = 0
+    column_count = 0
+    row_sum = 0
+    vf = visibility_filter or get_effective_visibility_filter()
+    if gp.exists():
+        store = open_store_for_entry(entry)
+        try:
+            counts = counts_for_graph(
+                store,
+                connection_name=entry.connection_name,
+                visibility_filter=vf,
+            )
+            table_count = counts.table_count
+            column_count = counts.column_count
+            row_sum = counts.row_count
+            er = store.query_all_rows("MATCH (e:Entity) RETURN count(*)")
+            if er:
+                entity_count = int(er[0][0])
+        finally:
+            release_store(store)
+    days = staleness_days(entry.last_indexed_at)
+    threshold = stale_threshold_days(get_effective_graph_config())
+    stale = days > threshold
+    lines = [
+        f"# Overview: {entry.connection_name}",
+        "",
+        f"- **Logical database:** {entry.database}",
+        f"- **Tables:** {table_count}",
+        f"- **Columns (graph):** {column_count}",
+        f"- **Entities:** {entity_count}",
+        f"- **Row count (sum over tables):** {row_sum}",
+        f"- **Last indexed:** {iso_format(entry.last_indexed_at)}",
+        f"- **Staleness (days):** {days} (warn if >{threshold})",
+        f"- **Graph file:** `{entry.graph_path}`",
+        "",
+    ]
+    if stale:
+        lines.append(
+            f"> **Warning:** Graph index is {days} days old; run "
+            "`pretensor reindex <dsn>` or `pretensor index`."
+        )
+    return "\n".join(lines)
+
+
+def metrics_resource_markdown(
+    graph_dir: Path,
+    name: str,
+    *,
+    visibility_filter: VisibilityFilter | None = None,
+) -> str:
+    """Markdown for ``pretensor://db/{name}/metrics``."""
+    reg = load_registry(graph_dir)
+    entry = resolve_registry_entry(reg, name)
+    if entry is None:
+        return f"# Unknown database `{name}`\n\nNo matching registry entry."
+    gp = graph_path_for_entry(entry)
+    if not gp.exists():
+        return f"# Metrics — {name}\n\n_Graph file missing._"
+
+    db_key = str(entry.database)
+    cn = str(entry.connection_name)
+    vf = visibility_filter or get_effective_visibility_filter()
+    store = open_store_for_entry(entry)
+    try:
+        rows = store.query_all_rows(
+            """
+            MATCH (m:MetricTemplate {connection_name: $cn, database: $db})
+            OPTIONAL MATCH (m)-[:METRIC_DEPENDS]->(t:SchemaTable)
+            WITH m, collect(concat(t.schema_name, '.', t.table_name)) AS dep_tables
+            RETURN m.name, m.display_name, m.description, m.sql_template, m.validated,
+                   m.validation_errors_json, m.generated_at_iso, m.stale, m.dialect, dep_tables
+            ORDER BY m.name
+            """,
+            {"cn": cn, "db": db_key},
+        )
+        lines = [
+            f"# Metric templates — {entry.connection_name}",
+            "",
+            f"_Logical database:_ `{db_key}`",
+            "",
+        ]
+        if not rows:
+            lines.append(
+                "_No `MetricTemplate` nodes yet. The default OSS indexing flow does "
+                "not create them automatically; this resource only lists templates "
+                "when they are already present in the graph._"
+            )
+            return "\n".join(lines)
+
+        for (
+            mname,
+            dname,
+            desc,
+            sql,
+            ok,
+            errs_json,
+            gen_iso,
+            stale,
+            dialect,
+            dep_tables,
+        ) in rows:
+            tlist_raw = sorted(
+                {str(x) for x in (dep_tables or []) if x is not None and str(x).strip()}
+            )
+            if vf is not None:
+                tlist_vis = []
+                for qual in tlist_raw:
+                    if "." not in qual:
+                        continue
+                    sn, _, tn = qual.partition(".")
+                    if vf.is_table_visible(cn, sn, tn):
+                        tlist_vis.append(qual)
+                if not tlist_vis and tlist_raw:
+                    continue
+                tlist = tlist_vis
+            else:
+                tlist = tlist_raw
+            lines.append(f"## `{mname}`")
+            lines.append("")
+            if dname:
+                lines.append(f"**Display:** {dname}")
+                lines.append("")
+            if desc:
+                lines.append(str(desc))
+                lines.append("")
+            validated = bool(ok) if ok is not None else False
+            lines.append(f"- **Validated:** {validated}")
+            if dialect:
+                lines.append(f"- **Dialect:** {dialect}")
+            if stale:
+                lines.append(
+                    "- **Stale:** yes — graph changed since this template was generated; "
+                    "re-run full `pretensor index` or `--recompute-intelligence` on reindex."
+                )
+            if gen_iso:
+                lines.append(f"- **Generated:** {gen_iso}")
+            if tlist:
+                lines.append(f"- **Tables:** {', '.join(tlist)}")
+            lines.append("")
+            lines.append("```sql")
+            lines.append(str(sql or "").strip() or "-- (empty)")
+            lines.append("```")
+            lines.append("")
+            if errs_json and str(errs_json).strip() not in ("", "[]"):
+                try:
+                    parsed = json.loads(str(errs_json))
+                    if isinstance(parsed, list) and parsed:
+                        lines.append("_Validation messages:_")
+                        for item in parsed[:8]:
+                            lines.append(f"- {item}")
+                        lines.append("")
+                except json.JSONDecodeError:
+                    pass
+
+        lines.append(
+            f"*Last registry index: {iso_format(entry.last_indexed_at)}. "
+            "Use `query` to search tables when available.*"
+        )
+        return "\n".join(lines)
+    finally:
+        release_store(store)
+
+
+__all__ = [
+    "clusters_resource_markdown",
+    "databases_resource_markdown",
+    "db_overview_resource_markdown",
+    "metrics_resource_markdown",
+]

pretensor/mcp/server.py

@@ -0,0 +1,285 @@
+"""MCP server (stdio) exposing Pretensor graph tools and resources."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+import uuid
+from pathlib import Path
+from typing import Any
+
+import mcp.types as types
+from mcp.server import NotificationOptions, Server
+from mcp.server.stdio import stdio_server
+from pydantic import AnyUrl
+
+from pretensor.config import PretensorConfig
+from pretensor.mcp.service import (
+    clusters_resource_markdown,
+    databases_resource_markdown,
+    db_overview_resource_markdown,
+    mcp_config_json,
+    metrics_resource_markdown,
+)
+from pretensor.mcp.service_context import build_server_context, set_server_context
+from pretensor.mcp.tool_registry import McpTool, McpToolRegistry
+from pretensor.mcp.tools import (
+    compile_metric as compile_metric_tool,
+)
+from pretensor.mcp.tools import (
+    consumers as consumers_tool,
+)
+from pretensor.mcp.tools import (
+    context as context_tool,
+)
+from pretensor.mcp.tools import (
+    cypher as cypher_tool,
+)
+from pretensor.mcp.tools import (
+    detect_changes as detect_changes_tool,
+)
+from pretensor.mcp.tools import (
+    impact as impact_tool,
+)
+from pretensor.mcp.tools import (
+    list as list_tool,
+)
+from pretensor.mcp.tools import (
+    schema as schema_tool,
+)
+from pretensor.mcp.tools import (
+    search as search_tool,
+)
+from pretensor.mcp.tools import (
+    semantic_search as semantic_search_tool,
+)
+from pretensor.mcp.tools import (
+    traverse as traverse_tool,
+)
+from pretensor.mcp.tools import (
+    validate_sql as validate_sql_tool,
+)
+
+__all__ = ["create_server", "run_server", "print_mcp_config"]
+
+logger = logging.getLogger(__name__)
+
+_DB_OVERVIEW_PATTERN = re.compile(
+    r"^pretensor://db/(?P<name>[^/]+)/overview$",
+)
+_DB_CLUSTERS_PATTERN = re.compile(
+    r"^pretensor://db/(?P<name>[^/]+)/clusters$",
+)
+_DB_METRICS_PATTERN = re.compile(
+    r"^pretensor://db/(?P<name>[^/]+)/metrics$",
+)
+
+
+def print_mcp_config(graph_dir: Path, *, stream: Any = None) -> None:
+    """Print the ``mcpServers`` JSON block (for Claude / Cursor) to a text stream.
+
+    Defaults to **stderr** so stdout stays reserved for MCP JSON-RPC over stdio
+    after ``serve`` starts the server.
+    """
+    out = stream if stream is not None else __import__("sys").stderr
+    out.write(mcp_config_json(graph_dir) + "\n")
+    out.flush()
+
+
+def _build_oss_registry(graph_dir: Path) -> McpToolRegistry:
+    """Build a :class:`McpToolRegistry` pre-loaded with all OSS tools.
+
+    Internal helper — use :func:`create_server` as the extension point (it
+    accepts ``extra_tools`` for downstream registration).
+    """
+    registry = McpToolRegistry()
+    for create in (
+        list_tool.create_tool,
+        schema_tool.create_tool,
+        cypher_tool.create_tool,
+        search_tool.create_tool,
+        semantic_search_tool.create_tool,
+        context_tool.create_tool,
+        traverse_tool.create_tool,
+        impact_tool.create_tool,
+        consumers_tool.create_tool,
+        detect_changes_tool.create_tool,
+        compile_metric_tool.create_tool,
+        validate_sql_tool.create_tool,
+    ):
+        registry.register(create(graph_dir))
+    return registry
+
+
+def render_resource_markdown(graph_dir: Path, key: str) -> str:
+    """Resolve a resource URI to markdown, with a sanitized error fallback.
+
+    On any handler error the full stack is logged server-side under a
+    correlation id and the client receives a generic message — never the
+    exception text or a filesystem path.
+    """
+    try:
+        if key == "pretensor://databases":
+            return databases_resource_markdown(graph_dir)
+        match = _DB_OVERVIEW_PATTERN.match(key)
+        if match:
+            return db_overview_resource_markdown(graph_dir, match.group("name"))
+        match_c = _DB_CLUSTERS_PATTERN.match(key)
+        if match_c:
+            return clusters_resource_markdown(graph_dir, match_c.group("name"))
+        match_m = _DB_METRICS_PATTERN.match(key)
+        if match_m:
+            return metrics_resource_markdown(graph_dir, match_m.group("name"))
+        return f"# Resource not found\n\nUnknown URI: `{key}`"
+    except Exception:
+        correlation_id = uuid.uuid4().hex
+        logger.exception(
+            "Error reading MCP resource %r [correlation_id=%s]",
+            key,
+            correlation_id,
+        )
+        return f"# Error\n\nFailed to load resource. Correlation ID: `{correlation_id}`"
+
+
+def create_server(
+    graph_dir: Path,
+    *,
+    visibility_path: Path | None = None,
+    profile: str | None = None,
+    config: PretensorConfig | None = None,
+    extra_tools: list[McpTool] | None = None,
+) -> Server[object, object]:
+    """Build the low-level MCP :class:`Server` bound to ``graph_dir``.
+
+    Args:
+        graph_dir: Root directory of the Pretensor graph store.
+        visibility_path: Optional path to a visibility filter config file.
+        profile: Optional named profile for the server context.
+        config: Optional central Pretensor configuration for MCP runtime wiring.
+        extra_tools: Additional :class:`McpTool` instances to register on top
+            of the 7 built-in OSS tools (e.g. from plugins).
+    """
+    set_server_context(
+        build_server_context(
+            graph_dir,
+            visibility_path=visibility_path,
+            profile=profile,
+            config=config,
+        )
+    )
+
+    registry = _build_oss_registry(graph_dir)
+    for tool in extra_tools or []:
+        registry.register(tool)
+
+    server = Server[object, object](
+        "pretensor",
+        instructions=(
+            "Pretensor graph MCP: discover indexed databases, search metadata, "
+            "and fetch full context for physical tables (Kuzu schema graph)."
+        ),
+    )
+
+    @server.list_tools()
+    async def _list_tools() -> list[types.Tool]:
+        return registry.list_tools()
+
+    @server.call_tool()
+    async def _call_tool(name: str, arguments: dict[str, Any] | None) -> dict[str, Any]:
+        try:
+            return await registry.call_tool(name, arguments)
+        except Exception:
+            correlation_id = uuid.uuid4().hex
+            logger.exception(
+                "Unexpected error dispatching MCP tool %r [correlation_id=%s]",
+                name,
+                correlation_id,
+            )
+            return {
+                "error": "Internal server error",
+                "tool": name,
+                "correlation_id": correlation_id,
+            }
+
+    @server.list_resources()
+    async def _list_resources() -> list[types.Resource]:
+        return [
+            types.Resource(
+                uri=AnyUrl("pretensor://databases"),
+                name="databases",
+                title="All indexed databases",
+                description="Registry overview (markdown)",
+                mimeType="text/markdown",
+            ),
+        ]
+
+    @server.list_resource_templates()
+    async def _list_resource_templates() -> list[types.ResourceTemplate]:
+        return [
+            types.ResourceTemplate(
+                uriTemplate="pretensor://db/{name}/overview",
+                name="db-overview",
+                title="Per-database overview",
+                description="Table count, entity count, staleness (markdown)",
+                mimeType="text/markdown",
+            ),
+            types.ResourceTemplate(
+                uriTemplate="pretensor://db/{name}/clusters",
+                name="db-clusters",
+                title="Per-database domain clusters",
+                description="Leiden clusters and table groupings (markdown)",
+                mimeType="text/markdown",
+            ),
+            types.ResourceTemplate(
+                uriTemplate="pretensor://db/{name}/metrics",
+                name="db-metrics",
+                title="Per-database metric templates",
+                description="MetricTemplate nodes: SQL, validation, dependencies (markdown)",
+                mimeType="text/markdown",
+            ),
+        ]
+
+    @server.read_resource()
+    async def _read_resource(uri: AnyUrl) -> str:
+        return render_resource_markdown(graph_dir, str(uri))
+
+    return server
+
+
+async def _run_async(
+    graph_dir: Path,
+    *,
+    visibility_path: Path | None = None,
+    profile: str | None = None,
+    config: PretensorConfig | None = None,
+) -> None:
+    server = create_server(
+        graph_dir,
+        visibility_path=visibility_path,
+        profile=profile,
+        config=config,
+    )
+    init = server.create_initialization_options(
+        notification_options=NotificationOptions(resources_changed=False)
+    )
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, init)
+
+
+def run_server(
+    graph_dir: Path,
+    *,
+    visibility_path: Path | None = None,
+    profile: str | None = None,
+    config: PretensorConfig | None = None,
+) -> None:
+    """Start the MCP server on stdio (blocking)."""
+    asyncio.run(
+        _run_async(
+            graph_dir,
+            visibility_path=visibility_path,
+            profile=profile,
+            config=config,
+        )
+    )

pretensor/mcp/service.py

@@ -0,0 +1,49 @@
+"""MCP-facing read logic: stable import surface for tools and resources.
+
+Implementation lives in ``pretensor.mcp.tools`` and sibling modules; this module
+re-exports the public API used by ``server.py`` and tests.
+"""
+
+from __future__ import annotations
+
+from pretensor.mcp.config_json import mcp_config_json
+from pretensor.mcp.resources import (
+    clusters_resource_markdown,
+    databases_resource_markdown,
+    db_overview_resource_markdown,
+    metrics_resource_markdown,
+)
+from pretensor.mcp.service_registry import resolve_registry_entry
+from pretensor.mcp.tools.compile_metric import compile_metric_payload
+from pretensor.mcp.tools.consumers import consumers_payload
+from pretensor.mcp.tools.context import context_payload
+from pretensor.mcp.tools.cypher import cypher_payload
+from pretensor.mcp.tools.detect_changes import detect_changes_payload
+from pretensor.mcp.tools.impact import impact_payload
+from pretensor.mcp.tools.list import list_databases_payload
+from pretensor.mcp.tools.schema import schema_payload
+from pretensor.mcp.tools.search import query_payload
+from pretensor.mcp.tools.semantic_search import semantic_search_payload
+from pretensor.mcp.tools.traverse import traverse_payload
+from pretensor.mcp.tools.validate_sql import validate_sql_payload
+
+__all__ = [
+    "list_databases_payload",
+    "query_payload",
+    "semantic_search_payload",
+    "cypher_payload",
+    "context_payload",
+    "traverse_payload",
+    "impact_payload",
+    "consumers_payload",
+    "detect_changes_payload",
+    "compile_metric_payload",
+    "schema_payload",
+    "validate_sql_payload",
+    "databases_resource_markdown",
+    "db_overview_resource_markdown",
+    "metrics_resource_markdown",
+    "clusters_resource_markdown",
+    "resolve_registry_entry",
+    "mcp_config_json",
+]