sqlmesh-mcp 0.1.0__py3-none-any.whl

sqlmesh_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sqlmesh_mcp/context.py

@@ -0,0 +1,23 @@
+"""Lazily-created, cached SQLMesh Context for the configured project."""
+
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+
+from sqlmesh.core.context import Context
+
+
+class ProjectNotConfiguredError(RuntimeError):
+    pass
+
+
+@lru_cache(maxsize=1)
+def get_context() -> Context:
+    path = os.environ.get("SQLMESH_PROJECT_PATH")
+    if not path:
+        raise ProjectNotConfiguredError(
+            "SQLMESH_PROJECT_PATH is not set. Point it at a directory containing "
+            "a SQLMesh config.py/config.yaml."
+        )
+    return Context(paths=path)

sqlmesh_mcp/server.py

@@ -0,0 +1,232 @@
+"""sqlmesh-mcp: exposes a SQLMesh project to LLM agents via MCP.
+
+Every tool here is read-only except apply_plan, which is the one tool that
+changes real data in whatever warehouse the project points at.
+"""
+
+from __future__ import annotations
+
+import functools
+from typing import Any
+
+import sqlglot
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp_types import ToolAnnotations
+from sqlmesh.core.lineage import column_dependencies
+from sqlmesh.utils.errors import SQLMeshError
+
+from .context import get_context
+
+server = MCPServer("sqlmesh-mcp")
+
+# Plans previewed via `plan` are cached here so `apply_plan` can apply exactly
+# what was shown, keyed by Plan.plan_id. Plan objects aren't JSON-serializable
+# and re-running plan() at apply time could compute something different if the
+# project changed in between preview and apply.
+_PLAN_CACHE: dict[str, Any] = {}
+
+
+def _translate_errors(fn):
+    """Without this, the MCP SDK treats any exception that isn't a ToolError as
+    a crash: the agent sees only the generic "Error executing tool <name>" and
+    the real message (e.g. SQLMesh's "Apply a plan first") is dropped, visible
+    only in server-side logs. SQLMeshError covers every error the underlying
+    library itself raises intentionally, so translating it is always safe to
+    show the agent -- it's exactly the informative half of the message.
+    """
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except SQLMeshError as e:
+            raise ToolError(str(e)) from e
+
+    return wrapper
+
+
+def _snapshot_model_name(snapshot_id: Any) -> str:
+    """SnapshotId.name is a quoted, catalog-qualified identifier (e.g.
+    '"db"."sqlmesh_example"."seed_model"') -- normalize to the plain
+    'schema.model' form every other tool here uses.
+    """
+    t = sqlglot.exp.to_table(snapshot_id.name)
+    return f"{t.db}.{t.name}" if t.db else t.name
+
+
+def _model_summary(model: Any) -> dict:
+    return {
+        "name": model.name,
+        "kind": str(model.kind.name),
+        "description": model.description,
+        "owner": model.owner,
+        "tags": list(model.tags or []),
+        "columns": {col: str(dtype) for col, dtype in (model.columns_to_types or {}).items()},
+    }
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=True))
+@_translate_errors
+def list_models() -> list[dict]:
+    """List every model in the SQLMesh project with its kind, columns, owner, and description."""
+    ctx = get_context()
+    return [_model_summary(m) for m in ctx.models.values()]
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=True))
+@_translate_errors
+def get_model(model_name: str) -> dict:
+    """Full detail for one model: rendered query, columns, kind, owner, tags, description."""
+    ctx = get_context()
+    model = ctx.get_model(model_name, raise_if_missing=True)
+    summary = _model_summary(model)
+    summary["query"] = model.render_query_or_raise().sql(dialect=model.dialect, pretty=True)
+    return summary
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=True))
+@_translate_errors
+def plan(environment: str | None = None, select_models: list[str] | None = None) -> dict:
+    """Preview what a plan against an environment would change. Does not apply anything.
+
+    Returns a plan_id -- pass it to apply_plan to actually apply this exact plan.
+    """
+    ctx = get_context()
+    p = ctx.plan(
+        environment=environment,
+        select_models=select_models,
+        no_prompts=True,
+        auto_apply=False,
+    )
+    _PLAN_CACHE[p.plan_id] = p
+    diff = p.context_diff
+    return {
+        "plan_id": p.plan_id,
+        "environment": p.environment_naming_info.name,
+        "has_changes": diff.has_changes,
+        "requires_backfill": p.requires_backfill,
+        "added_models": sorted(_snapshot_model_name(s) for s in diff.added),
+        "removed_models": sorted(_snapshot_model_name(s) for s in diff.removed_snapshots),
+        "modified_models": sorted(diff.modified_snapshots),
+    }
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=False, destructive_hint=True))
+@_translate_errors
+def apply_plan(plan_id: str, confirm: bool = False) -> dict:
+    """Apply a previously-previewed plan. THIS CHANGES REAL DATA in the target warehouse.
+
+    Requires confirm=true. plan_id must come from a plan() call in this same session --
+    plans aren't kept across server restarts.
+    """
+    if not confirm:
+        raise ToolError(
+            "Refusing to apply without confirm=true -- this changes real data "
+            "in the target warehouse."
+        )
+    p = _PLAN_CACHE.get(plan_id)
+    if p is None:
+        raise ToolError(
+            f"No cached plan with id {plan_id!r}. Call plan() again in this session first."
+        )
+    ctx = get_context()
+    ctx.apply(p)
+    del _PLAN_CACHE[plan_id]
+    return {"applied": True, "plan_id": plan_id}
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=True))
+@_translate_errors
+def lineage(model_name: str, column: str) -> dict:
+    """Column-level lineage: which upstream models/columns does this column depend on."""
+    ctx = get_context()
+    deps = column_dependencies(ctx, model_name, column)
+    return {k: sorted(v) for k, v in deps.items()}
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=True))
+@_translate_errors
+def run_audit(
+    model_name: str | None = None,
+    start: str | None = None,
+    end: str | None = None,
+) -> dict:
+    """Run audits for a model (or all models if omitted). start/end bound the data checked."""
+    ctx = get_context()
+    passed = ctx.audit(start=start, end=end, models=[model_name] if model_name else None)
+    return {"passed": passed, "model": model_name}
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=True))
+@_translate_errors
+def run_test(model_name: str | None = None) -> dict:
+    """Run unit tests for a model (or all tests if omitted)."""
+    ctx = get_context()
+    result = ctx.test(model_names=[model_name] if model_name else None)
+    return {
+        "success": result.wasSuccessful(),
+        "tests_run": result.testsRun,
+        "failures": [str(f[0]) for f in result.failures],
+        "errors": [str(e[0]) for e in result.errors],
+    }
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=True))
+@_translate_errors
+def diff_environment(environment: str) -> dict:
+    """Diff the current context against a target environment."""
+    ctx = get_context()
+    has_diff = ctx.diff(environment=environment)
+    return {"environment": environment, "has_diff": has_diff}
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=True))
+@_translate_errors
+def list_environments() -> list[dict]:
+    """List every environment that exists in this project's state (e.g. prod, dev, ...)."""
+    ctx = get_context()
+    envs = ctx.state_reader.get_environments()
+    return [
+        {
+            "name": e.name,
+            "plan_id": e.plan_id,
+            "start_at": str(e.start_at) if e.start_at else None,
+            "end_at": str(e.end_at) if e.end_at else None,
+            "finalized_ts": e.finalized_ts,
+            "expiration_ts": e.expiration_ts,
+        }
+        for e in envs
+    ]
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=False, destructive_hint=True))
+@_translate_errors
+def run(
+    environment: str | None = None,
+    confirm: bool = False,
+    start: str | None = None,
+    end: str | None = None,
+) -> dict:
+    """Execute scheduled/due model runs for an environment. THIS CHANGES REAL DATA.
+
+    Distinct from plan/apply_plan: this runs already-promoted models for their
+    due intervals (what a cron trigger would do), rather than previewing or
+    promoting structural changes. Requires confirm=true.
+    """
+    if not confirm:
+        raise ToolError(
+            "Refusing to run without confirm=true -- this changes real data "
+            "in the target warehouse."
+        )
+    ctx = get_context()
+    status = ctx.run(environment=environment, start=start, end=end)
+    return {"status": status.name, "environment": environment}
+
+
+def main() -> None:
+    server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

sqlmesh_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: sqlmesh-mcp
+Version: 0.1.0
+Summary: MCP server exposing a SQLMesh project (models, plans, column-level lineage, audits) to LLM agents
+Project-URL: Homepage, https://github.com/Zain-ul-Abdin45/sqlmesh-mcp
+Project-URL: Issues, https://github.com/Zain-ul-Abdin45/sqlmesh-mcp/issues
+Author: Zain Ul Abdin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,data-engineering,llm,mcp,sqlmesh
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Requires-Dist: mcp>=2.0.0
+Requires-Dist: sqlmesh>=0.236.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sqlmesh-mcp
+
+[![CI](https://github.com/Zain-ul-Abdin45/sqlmesh-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Zain-ul-Abdin45/sqlmesh-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/sqlmesh-mcp.svg)](https://pypi.org/project/sqlmesh-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/sqlmesh-mcp.svg)](https://pypi.org/project/sqlmesh-mcp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+MCP server exposing a [SQLMesh](https://github.com/SQLMesh/sqlmesh) project to LLM agents: model metadata, plan previews, column-level lineage, audits/tests, and environment diffs.
+
+Not officially affiliated with SQLMesh or Tobiko Data.
+
+## Why
+
+SQLMesh's standout feature is column-level lineage, which is exactly the kind of question an agent is good at answering interactively ("where does `revenue` in `finance.daily_summary` come from?") that a CLI isn't. As of writing, the only prior MCP server for SQLMesh ([`sherman94062/sqlmesh-mcp`](https://github.com/sherman94062/sqlmesh-mcp)) is a small unmaintained side project — this one aims to be documented, tested, and kept current with SQLMesh's API.
+
+## Install
+
+```bash
+pip install sqlmesh-mcp
+```
+
+## Usage
+
+Point it at a SQLMesh project directory:
+
+```json
+{
+  "mcpServers": {
+    "sqlmesh": {
+      "command": "sqlmesh-mcp",
+      "env": { "SQLMESH_PROJECT_PATH": "/path/to/your/sqlmesh/project" }
+    }
+  }
+}
+```
+
+## Example
+
+Calling `list_models` against [`examples/demo_project`](examples/demo_project) (a stock `sqlmesh init duckdb` project) returns:
+
+```json
+[
+  {
+    "name": "sqlmesh_example.full_model",
+    "kind": "FULL",
+    "description": null,
+    "owner": null,
+    "tags": [],
+    "columns": { "item_id": "INT", "num_orders": "BIGINT" }
+  },
+  {
+    "name": "sqlmesh_example.incremental_model",
+    "kind": "INCREMENTAL_BY_TIME_RANGE",
+    "description": null,
+    "owner": null,
+    "tags": [],
+    "columns": { "id": "INT", "item_id": "INT", "event_date": "DATE" }
+  },
+  {
+    "name": "sqlmesh_example.seed_model",
+    "kind": "SEED",
+    "description": null,
+    "owner": null,
+    "tags": [],
+    "columns": { "id": "INT", "item_id": "INT", "event_date": "DATE" }
+  }
+]
+```
+
+From there, `lineage("sqlmesh_example.full_model", "num_orders")` traces that column back to `incremental_model.id` — the kind of question this server exists for.
+
+## Tools
+
+| Tool | Read-only? | Description |
+|---|---|---|
+| `list_models` | Yes | List all models in the project with kind, columns, description |
+| `get_model` | Yes | Full detail for one model |
+| `plan` | Yes | Preview what a plan against an environment would change |
+| `apply_plan` | **No** | Apply a previously-previewed plan. Requires `confirm=true`. |
+| `lineage` | Yes | Column-level lineage for a model's column |
+| `run_audit` | Yes | Run a model's audits |
+| `run_test` | Yes | Run a model's unit tests |
+| `diff_environment` | Yes | Diff two environments |
+| `list_environments` | Yes | List every environment that exists in the project's state |
+| `run` | **No** | Execute scheduled/due model runs for an environment (what a cron trigger would do). Requires `confirm=true`. |
+
+`apply_plan` and `run` are the two tools that change real data in whatever warehouse the project points at. Every other tool is read-only. Both are marked `destructiveHint`/non-`readOnlyHint` in their MCP tool annotations so clients can warn a user before calling them.
+
+One server process is scoped to a single SQLMesh project, set once via `SQLMESH_PROJECT_PATH` (the context is cached for the life of the process). Point a client at multiple projects by running multiple server instances, one per `SQLMESH_PROJECT_PATH`.
+
+### Not yet covered
+
+SQLMesh's `table_diff` and `format` commands aren't exposed as tools yet — planned, not forgotten. Contributions welcome.
+
+## Testing
+
+See [`TEST_CASES.md`](TEST_CASES.md) for a plain-English index of every test case and what it covers, including a real bug the protocol-level tests caught that direct function-call tests couldn't (tool errors getting silently replaced with a generic message unless raised as the SDK's own `ToolError`).
+
+## License
+
+MIT

sqlmesh_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+sqlmesh_mcp/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+sqlmesh_mcp/context.py,sha256=qyx2kSE_XNOp3CfclvgkQ4kq9YHsPFqzKE2K0sQlHEw,585
+sqlmesh_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlmesh_mcp/server.py,sha256=TWeQMqhm8nba2IihZZ9gC64Hs0ksbkFQzxwo0C5arjI,8220
+sqlmesh_mcp-0.1.0.dist-info/METADATA,sha256=GUfVZLo8W5PCbLlreREW2GxQc7v5U5ysIGcIZuXr29c,5100
+sqlmesh_mcp-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+sqlmesh_mcp-0.1.0.dist-info/entry_points.txt,sha256=AwWqV3M1RwsYbprEzgo5scAktXnZHIOWaA3JSdINuHs,56
+sqlmesh_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=cBM1LM6j5rzRZN9debz9be_EGSdSQ6xEBD13QBe0EHU,1070
+sqlmesh_mcp-0.1.0.dist-info/RECORD,,

sqlmesh_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sqlmesh_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sqlmesh-mcp = sqlmesh_mcp.server:main

sqlmesh_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zain Ul Abdin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.