sqlmesh-mcp 0.1.0__tar.gz

sqlmesh_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: pytest

sqlmesh_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+# Triggered by cutting a GitHub Release (tag it vX.Y.Z to match pyproject.toml's
+# `version`). Uses PyPI Trusted Publishing (OIDC) -- no API token stored in
+# this repo. The corresponding "pending publisher" must be configured once on
+# pypi.org (Account Settings -> Publishing) for the sqlmesh-mcp project,
+# pointing at this repo, this workflow filename, and the `pypi` environment
+# below, before the first release is cut.
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/sqlmesh-mcp/
+    permissions:
+      id-token: write # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

sqlmesh_mcp-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.DS_Store
+
+# SQLMesh runtime artifacts from running the demo project / tests
+*.db
+*.db.wal
+examples/demo_project/.cache/
+examples/demo_project/logs/

sqlmesh_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] - Unreleased
+
+Initial release.
+
+### Added
+
+- `list_models`, `get_model` -- model metadata and rendered queries.
+- `plan`, `apply_plan` -- preview and (with `confirm=true`) apply a plan.
+- `lineage` -- column-level lineage for a model's column.
+- `run_audit`, `run_test` -- run a model's audits / unit tests.
+- `diff_environment`, `list_environments` -- inspect environment state.
+- `run` -- execute due scheduled runs for an environment (requires `confirm=true`).
+- Protocol-level test suite (`tests/test_protocol.py`) spawning the server
+  as a real MCP client would, alongside direct function-call tests.

sqlmesh_mcp-0.1.0/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.

sqlmesh_mcp-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,101 @@
+# 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/TEST_CASES.md

@@ -0,0 +1,58 @@
+# Test cases
+
+Plain-English index of every case the test suite covers, and why it exists.
+Both files run against `examples/demo_project`, a real SQLMesh project
+(generated with `sqlmesh init duckdb`, not hand-written fixtures) backed by
+DuckDB.
+
+Run everything: `pytest`. Run just one file: `pytest tests/test_server.py`.
+
+## `tests/test_server.py` — direct function calls
+
+Calls the tool functions directly, bypassing the MCP protocol layer. Fast,
+and proves our own logic is correct in isolation.
+
+| Test | What it checks |
+|---|---|
+| `test_list_models_returns_the_demo_project_models` | All three demo models are returned, with correct kind and columns |
+| `test_get_model_includes_rendered_query` | Full model detail includes the actual rendered SQL query |
+| `test_get_model_raises_tool_error_with_the_real_message_for_unknown_model` | Looking up a nonexistent model raises `ToolError`, not a generic exception |
+| `test_lineage_traces_column_to_upstream_model` | Column-level lineage correctly traces `full_model.num_orders` back to `incremental_model` |
+| `test_run_test_passes_on_the_untouched_demo_project` | Unit tests run and pass against the unmodified demo project |
+| `test_list_environments_is_empty_before_anything_is_applied` | No environments exist before any plan has been applied |
+| `test_plan_previews_the_initial_environment_without_applying` | `plan()` shows all three models as new, normalizes their names to plain `schema.model` form, and does **not** apply anything |
+| `test_apply_plan_refuses_without_confirm` | `apply_plan()` without `confirm=true` raises `ToolError`, nothing gets applied |
+| `test_apply_plan_rejects_unknown_plan_id` | Applying a `plan_id` that was never previewed raises `ToolError` rather than silently doing nothing |
+| `test_apply_plan_actually_applies_when_confirmed` | With `confirm=true`, the plan is actually applied and removed from the in-memory cache |
+| `test_run_audit_passes_once_the_project_has_been_applied` | Audits pass against real, versioned data (previously **completely untested** — calling this against an unapplied project raises SQLMesh's own `ConfigError`, which the test now confirms is avoided by applying first) |
+| `test_diff_environment_shows_no_diff_immediately_after_apply` | Diffing an environment right after applying it correctly shows no changes |
+| `test_list_environments_shows_the_applied_environment` | Once a plan is applied, the environment shows up in `list_environments()` |
+| `test_run_reports_nothing_to_do_immediately_after_apply` | Running right after `apply_plan` (which already backfilled everything) correctly reports `NOTHING_TO_DO`, not an error |
+| `test_run_refuses_without_confirm` | Same `confirm=true` gate as `apply_plan`, verified independently for `run` |
+
+## `tests/test_protocol.py` — real MCP client over stdio
+
+Spawns the server as a real subprocess and talks to it the way an actual MCP
+client (Claude Desktop, etc.) would — a real JSON-RPC handshake, not a
+Python function call. This is the file that caught the most important bug
+found during development.
+
+| Test | What it checks |
+|---|---|
+| `test_lists_all_ten_tools` | The server advertises exactly the ten tools it should, over the real protocol |
+| `test_mutating_tools_are_flagged_destructive_and_not_read_only` | `apply_plan` and `run` both carry `destructive_hint=True`, `read_only_hint=False` in their MCP tool annotations — the signal a client uses to warn a user before calling them |
+| `test_read_only_tools_are_flagged_read_only` | Every other tool is correctly flagged `read_only_hint=True` |
+| `test_list_models_call_round_trips_real_data` | A real tool call over stdio returns real model data, not just a well-formed empty response |
+| `test_apply_plan_without_confirm_is_a_tool_error_with_the_real_message` | **The regression this file exists to catch.** Without raising `ToolError` specifically, the MCP SDK replaces *any* exception with the generic string `"Error executing tool <name>"` and drops the real message entirely — an agent calling `apply_plan` without `confirm=true` would see no indication of what to fix. This test confirms the actual "confirm=true" guidance reaches the client. |
+| `test_get_model_for_unknown_model_is_a_tool_error_with_the_real_message` | Same check for SQLMesh's own error message ("Cannot find model...") — confirms the `_translate_errors` decorator correctly forwards `SQLMeshError` text instead of it being swallowed |
+| `test_session_survives_a_tool_error_and_keeps_working` | A tool error doesn't crash the server process or corrupt the session — proven by making a real, successful call immediately after two failures |
+
+## Why two files instead of one
+
+Direct-call tests are fast and good at proving logic is right. They are
+*not* sufficient on their own — this project's error-handling bug (tool
+exceptions being silently replaced with a generic message unless they're a
+specific SDK exception type) only exists at the protocol boundary, invisible
+to any test that just calls the Python function and catches the exception
+itself. Both layers are tested because each one catches a different class of
+bug the other cannot see.

sqlmesh_mcp-0.1.0/examples/demo_project/audits/assert_positive_order_ids.sql

@@ -0,0 +1,9 @@
+AUDIT (
+  name assert_positive_order_ids,
+);
+
+SELECT *
+FROM @this_model
+WHERE
+  item_id < 0
+  

sqlmesh_mcp-0.1.0/examples/demo_project/config.yaml

@@ -0,0 +1,42 @@
+# --- Gateway Connection ---
+gateways:
+  duckdb:
+    connection:
+      # For more information on configuring the connection to your execution engine, visit:
+      # https://sqlmesh.readthedocs.io/en/stable/reference/configuration/#connection
+      # https://sqlmesh.readthedocs.io/en/stable/integrations/engines/duckdb/#connection-options
+      type: duckdb
+      database: db.db
+      # concurrent_tasks: 1
+      # register_comments: True
+      # pre_ping: False
+      # pretty_sql: False
+      # schema_differ_overrides: 
+      # catalog_type_overrides: 
+      # catalogs: 
+      # extensions: 
+      # connector_config: 
+      # secrets: 
+      # filesystems: 
+      # token: 
+
+default_gateway: duckdb
+
+# --- Model Defaults ---
+# https://sqlmesh.readthedocs.io/en/stable/reference/model_configuration/#model-defaults
+
+model_defaults:
+  dialect: duckdb
+  start: 2026-09-16 # Start date for backfill history
+  cron: '@daily'    # Run models daily at 12am UTC (can override per model)
+
+# --- Linting Rules ---
+# Enforce standards for your team
+# https://sqlmesh.readthedocs.io/en/stable/guides/linter/
+
+linter:
+  enabled: true
+  rules:
+    - ambiguousorinvalidcolumn
+    - invalidselectstarexpansion
+    - noambiguousprojections

sqlmesh_mcp-0.1.0/examples/demo_project/models/full_model.sql

@@ -0,0 +1,15 @@
+MODEL (
+  name sqlmesh_example.full_model,
+  kind FULL,
+  cron '@daily',
+  grain item_id,
+  audits (assert_positive_order_ids),
+);
+
+SELECT
+  item_id,
+  COUNT(DISTINCT id) AS num_orders,
+FROM
+  sqlmesh_example.incremental_model
+GROUP BY item_id
+  

sqlmesh_mcp-0.1.0/examples/demo_project/models/incremental_model.sql

@@ -0,0 +1,19 @@
+MODEL (
+  name sqlmesh_example.incremental_model,
+  kind INCREMENTAL_BY_TIME_RANGE (
+    time_column event_date
+  ),
+  start '2020-01-01',
+  cron '@daily',
+  grain (id, event_date)
+);
+
+SELECT
+  id,
+  item_id,
+  event_date,
+FROM
+  sqlmesh_example.seed_model
+WHERE
+  event_date BETWEEN @start_date AND @end_date
+  

sqlmesh_mcp-0.1.0/examples/demo_project/models/seed_model.sql

@@ -0,0 +1,13 @@
+MODEL (
+  name sqlmesh_example.seed_model,
+  kind SEED (
+    path '../seeds/seed_data.csv'
+  ),
+  columns (
+    id INTEGER,
+    item_id INTEGER,
+    event_date DATE
+  ),
+  grain (id, event_date)
+);
+  

sqlmesh_mcp-0.1.0/examples/demo_project/seeds/seed_data.csv

@@ -0,0 +1,8 @@
+id,item_id,event_date
+1,2,2020-01-01
+2,1,2020-01-01
+3,3,2020-01-03
+4,1,2020-01-04
+5,1,2020-01-05
+6,1,2020-01-06
+7,1,2020-01-07

sqlmesh_mcp-0.1.0/examples/demo_project/tests/test_full_model.yaml

@@ -0,0 +1,19 @@
+test_example_full_model:
+  model: sqlmesh_example.full_model
+  inputs:
+    sqlmesh_example.incremental_model:
+      rows:
+      - id: 1
+        item_id: 1
+      - id: 2
+        item_id: 1
+      - id: 3
+        item_id: 2
+  outputs:
+    query:
+      rows:
+      - item_id: 1
+        num_orders: 2
+      - item_id: 2
+        num_orders: 1
+  

sqlmesh_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sqlmesh-mcp"
+version = "0.1.0"
+description = "MCP server exposing a SQLMesh project (models, plans, column-level lineage, audits) to LLM agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Zain Ul Abdin" }]
+keywords = ["mcp", "sqlmesh", "data-engineering", "llm", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Database",
+]
+dependencies = [
+    "mcp>=2.0.0",
+    "sqlmesh>=0.236.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "ruff>=0.6"]
+
+[project.scripts]
+sqlmesh-mcp = "sqlmesh_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/Zain-ul-Abdin45/sqlmesh-mcp"
+Issues = "https://github.com/Zain-ul-Abdin45/sqlmesh-mcp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sqlmesh_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]

sqlmesh_mcp-0.1.0/src/sqlmesh_mcp/__init__.py

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

sqlmesh_mcp-0.1.0/src/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-0.1.0/src/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/tests/test_protocol.py

@@ -0,0 +1,126 @@
+"""End-to-end tests through the real MCP protocol, not just direct function calls.
+
+These matter separately from test_server.py: calling the tool functions
+directly and catching a Python exception proves our own logic is right, but
+says nothing about what actually crosses the wire to an agent. This file
+caught a real bug during development -- the MCP SDK silently replaces any
+exception that isn't a ToolError with a generic "Error executing tool <name>"
+(no further detail at all), dropping the actual message -- that no amount of
+direct-call testing would have found. With ToolError, the SDK still prefixes
+"Error executing tool <name>: ", but the real message now follows it.
+
+Spawns the server as a real subprocess and talks to it over stdio, the same
+way a real MCP client (Claude Desktop, etc.) would. Each test opens its own
+session inline (rather than via a fixture) because sharing an async
+generator fixture's stdio_client/ClientSession context managers across
+pytest-asyncio's per-test task boundaries triggers anyio "cancel scope
+exited in a different task" errors on teardown -- opening and closing the
+session within a single test's task avoids that entirely.
+"""
+
+import os
+import sys
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from mcp import ClientSession
+from mcp.client.stdio import StdioServerParameters, stdio_client
+
+DEMO_PROJECT = Path(__file__).parent.parent / "examples" / "demo_project"
+
+
+@asynccontextmanager
+async def open_session():
+    env = os.environ.copy()
+    env["SQLMESH_PROJECT_PATH"] = str(DEMO_PROJECT)
+    params = StdioServerParameters(
+        command=sys.executable, args=["-m", "sqlmesh_mcp.server"], env=env
+    )
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            yield session
+
+
+async def test_lists_all_ten_tools():
+    async with open_session() as session:
+        tools = await session.list_tools()
+        names = {t.name for t in tools.tools}
+        assert names == {
+            "list_models",
+            "get_model",
+            "plan",
+            "apply_plan",
+            "lineage",
+            "run_audit",
+            "run_test",
+            "diff_environment",
+            "list_environments",
+            "run",
+        }
+
+
+async def test_mutating_tools_are_flagged_destructive_and_not_read_only():
+    async with open_session() as session:
+        tools = {t.name: t for t in (await session.list_tools()).tools}
+        for name in ["apply_plan", "run"]:
+            assert tools[name].annotations.read_only_hint is False
+            assert tools[name].annotations.destructive_hint is True
+
+
+async def test_read_only_tools_are_flagged_read_only():
+    async with open_session() as session:
+        tools = {t.name: t for t in (await session.list_tools()).tools}
+        for name in [
+            "list_models",
+            "get_model",
+            "plan",
+            "lineage",
+            "run_audit",
+            "run_test",
+            "diff_environment",
+            "list_environments",
+        ]:
+            assert tools[name].annotations.read_only_hint is True
+
+
+async def test_list_models_call_round_trips_real_data():
+    async with open_session() as session:
+        result = await session.call_tool("list_models", {})
+        assert result.is_error is not True
+        assert "sqlmesh_example.full_model" in str(result.content)
+
+
+async def test_apply_plan_without_confirm_is_a_tool_error_with_the_real_message():
+    """The regression this file exists to catch: without ToolError, this would
+    come back as only the generic "Error executing tool apply_plan" with no
+    further detail -- instead of that prefix followed by the actual "Refusing
+    to apply without confirm=true..." message the agent needs to see.
+    """
+    async with open_session() as session:
+        result = await session.call_tool("apply_plan", {"plan_id": "fake", "confirm": False})
+        assert result.is_error is True
+        text = str(result.content)
+        assert "confirm=true" in text
+        assert "changes real data in the target warehouse" in text
+
+
+async def test_get_model_for_unknown_model_is_a_tool_error_with_the_real_message():
+    async with open_session() as session:
+        result = await session.call_tool("get_model", {"model_name": "does.not_exist"})
+        assert result.is_error is True
+        text = str(result.content)
+        assert "does.not_exist" in text or "does_not_exist" in text
+        assert "Cannot find model" in text
+
+
+async def test_session_survives_a_tool_error_and_keeps_working():
+    """A tool error must not take down the server process or the session --
+    confirmed by making a real, successful call right after two failures.
+    """
+    async with open_session() as session:
+        await session.call_tool("apply_plan", {"plan_id": "fake", "confirm": False})
+        await session.call_tool("get_model", {"model_name": "does.not_exist"})
+
+        result = await session.call_tool("list_models", {})
+        assert result.is_error is not True

sqlmesh_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,192 @@
+"""Integration tests against the real demo SQLMesh project in examples/demo_project.
+
+These call the underlying tool functions directly (not through the MCP
+protocol layer -- see test_protocol.py for that) to keep them fast and
+focused on our own logic.
+
+See TEST_CASES.md for a plain-English index of every case covered here and
+in test_protocol.py.
+"""
+
+from pathlib import Path
+
+import pytest
+from mcp.server.mcpserver.exceptions import ToolError
+
+DEMO_PROJECT = Path(__file__).parent.parent / "examples" / "demo_project"
+
+
+@pytest.fixture(autouse=True)
+def project_env(monkeypatch):
+    monkeypatch.setenv("SQLMESH_PROJECT_PATH", str(DEMO_PROJECT))
+    # get_context() is lru_cache'd; make sure each test gets a fresh Context
+    # bound to the env var set above rather than a stale cached one.
+    from sqlmesh_mcp.context import get_context
+
+    get_context.cache_clear()
+    yield
+    get_context.cache_clear()
+
+
+# ---------------------------------------------------------------------------
+# Read-only tools that don't require a prior plan/apply
+# ---------------------------------------------------------------------------
+
+
+def test_list_models_returns_the_demo_project_models():
+    from sqlmesh_mcp.server import list_models
+
+    models = list_models()
+    names = {m["name"] for m in models}
+    assert "sqlmesh_example.full_model" in names
+    assert "sqlmesh_example.incremental_model" in names
+    assert "sqlmesh_example.seed_model" in names
+
+    full_model = next(m for m in models if m["name"] == "sqlmesh_example.full_model")
+    assert full_model["kind"] == "FULL"
+    assert "num_orders" in full_model["columns"]
+
+
+def test_get_model_includes_rendered_query():
+    from sqlmesh_mcp.server import get_model
+
+    model = get_model("sqlmesh_example.incremental_model")
+    assert model["kind"] == "INCREMENTAL_BY_TIME_RANGE"
+    assert "seed_model" in model["query"]
+
+
+def test_get_model_raises_tool_error_with_the_real_message_for_unknown_model():
+    from sqlmesh_mcp.server import get_model
+
+    with pytest.raises(ToolError, match="does_not_exist"):
+        get_model("sqlmesh_example.does_not_exist")
+
+
+def test_lineage_traces_column_to_upstream_model():
+    from sqlmesh_mcp.server import lineage
+
+    deps = lineage("sqlmesh_example.full_model", "num_orders")
+    # num_orders = COUNT(DISTINCT id) from incremental_model -- id should show up
+    # somewhere in the dependency map's values.
+    all_upstream_cols = {col for cols in deps.values() for col in cols}
+    assert any("id" in col for col in all_upstream_cols) or any(
+        "incremental_model" in key for key in deps
+    )
+
+
+def test_run_test_passes_on_the_untouched_demo_project():
+    from sqlmesh_mcp.server import run_test
+
+    result = run_test()
+    assert result["success"] is True
+    assert result["tests_run"] >= 1
+    assert result["failures"] == []
+    assert result["errors"] == []
+
+
+def test_list_environments_is_empty_before_anything_is_applied():
+    from sqlmesh_mcp.server import list_environments
+
+    assert list_environments() == []
+
+
+# ---------------------------------------------------------------------------
+# plan() / apply_plan() -- the two-step preview/confirm flow
+# ---------------------------------------------------------------------------
+
+
+def test_plan_previews_the_initial_environment_without_applying():
+    from sqlmesh_mcp.server import _PLAN_CACHE, plan
+
+    result = plan(environment="dev")
+    assert result["plan_id"]
+    assert result["environment"] == "dev"
+    # A brand new project planned against a fresh env should show every model as new,
+    # normalized to the same plain 'schema.model' form list_models/get_model use.
+    assert set(result["added_models"]) >= {
+        "sqlmesh_example.full_model",
+        "sqlmesh_example.incremental_model",
+        "sqlmesh_example.seed_model",
+    }
+    # Nothing should have been applied -- the plan is only cached, not run.
+    assert result["plan_id"] in _PLAN_CACHE
+
+
+def test_apply_plan_refuses_without_confirm():
+    from sqlmesh_mcp.server import apply_plan, plan
+
+    p = plan(environment="dev_confirm_check")
+    with pytest.raises(ToolError, match="confirm=true"):
+        apply_plan(p["plan_id"], confirm=False)
+
+
+def test_apply_plan_rejects_unknown_plan_id():
+    from sqlmesh_mcp.server import apply_plan
+
+    with pytest.raises(ToolError, match="No cached plan"):
+        apply_plan("not-a-real-plan-id", confirm=True)
+
+
+def test_apply_plan_actually_applies_when_confirmed():
+    from sqlmesh_mcp.server import _PLAN_CACHE, apply_plan, plan
+
+    p = plan(environment="dev_apply_check")
+    result = apply_plan(p["plan_id"], confirm=True)
+    assert result["applied"] is True
+    assert p["plan_id"] not in _PLAN_CACHE
+
+
+# ---------------------------------------------------------------------------
+# Tools that only make sense once a plan has actually been applied --
+# run_audit and diff_environment were previously completely untested; calling
+# either against an unversioned project raises a SQLMeshError (confirmed
+# manually: "Cannot audit ... it has not been versioned yet. Apply a plan
+# first."), so these fixtures apply a real plan before exercising them.
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def applied_prod_env():
+    """Plans and applies against 'prod' so audits/diffs/runs have real, versioned data."""
+    from sqlmesh_mcp.server import apply_plan, plan
+
+    p = plan(environment="prod")
+    apply_plan(p["plan_id"], confirm=True)
+    return "prod"
+
+
+def test_run_audit_passes_once_the_project_has_been_applied(applied_prod_env):
+    from sqlmesh_mcp.server import run_audit
+
+    result = run_audit()
+    assert result["passed"] is True
+
+
+def test_diff_environment_shows_no_diff_immediately_after_apply(applied_prod_env):
+    from sqlmesh_mcp.server import diff_environment
+
+    result = diff_environment(applied_prod_env)
+    assert result == {"environment": "prod", "has_diff": False}
+
+
+def test_list_environments_shows_the_applied_environment(applied_prod_env):
+    from sqlmesh_mcp.server import list_environments
+
+    envs = list_environments()
+    names = {e["name"] for e in envs}
+    assert "prod" in names
+
+
+def test_run_reports_nothing_to_do_immediately_after_apply(applied_prod_env):
+    """apply_plan already backfilled every interval, so a run right after has nothing due."""
+    from sqlmesh_mcp.server import run
+
+    result = run(environment=applied_prod_env, confirm=True)
+    assert result["status"] == "NOTHING_TO_DO"
+
+
+def test_run_refuses_without_confirm(applied_prod_env):
+    from sqlmesh_mcp.server import run
+
+    with pytest.raises(ToolError, match="confirm=true"):
+        run(environment=applied_prod_env, confirm=False)