semql-mcp 0.1.0__tar.gz

semql_mcp-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Nikhil Pallamreddy
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

semql_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: semql-mcp
+Version: 0.1.0
+Summary: MCP server that wraps a semql Catalog — compile-only by default, opt-in row execution via a caller-provided executor.
+Author: Nikhil Pallamreddy
+Author-email: Nikhil Pallamreddy <nikhil.pallamreddy+git@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: semql>=0.1.0,<0.2
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/npalladium/semql
+Project-URL: Repository, https://github.com/npalladium/semql
+Project-URL: Issues, https://github.com/npalladium/semql/issues
+Description-Content-Type: text/markdown
+
+# semql-mcp
+
+An MCP server that wraps a [`semql`](../semql) `Catalog` and exposes
+its compiler / validator / prompt-renderer surfaces as tools any MCP
+client can call. Built on [FastMCP](https://github.com/jlowin/fastmcp).
+
+## Two modes
+
+By default the server is **compile-only**. `semql` is a pure compiler —
+no I/O — and this server keeps that contract. Tools return the emitted
+SQL and bound parameters; the caller runs the SQL against whatever
+backend they own.
+
+Pass an `executor` at construction to opt into **exec mode**. A
+`query_execute` tool registers in addition to the compile-only tools;
+it runs the SQL against your executor and returns both the SQL/params
+envelope and the resulting rows.
+
+## Install
+
+```sh
+pip install semql-mcp
+```
+
+## Quick start — compile-only
+
+```python
+from semql import Backend, Catalog, Cube, Dimension, Measure
+from semql_mcp import MCPServer
+
+catalog = Catalog([
+    Cube(
+        name="orders",
+        backend=Backend.POSTGRES,
+        table="orders",
+        alias="o",
+        measures=[Measure(name="revenue", sql="{o}.amount", agg="sum", unit="currency")],
+        dimensions=[Dimension(name="region", sql="{o}.region", type="string")],
+    ),
+])
+
+server = MCPServer(catalog)
+server.run(transport="stdio")  # speak JSON-RPC over stdin/stdout
+```
+
+## Quick start — exec mode
+
+Bring your own database driver and adapt its row shape to a list of
+dicts:
+
+```python
+import psycopg
+from psycopg.rows import dict_row
+
+from semql_mcp import MCPServer
+
+
+def executor(sql: str, params: dict) -> list[dict]:
+    with psycopg.connect("postgresql://...", row_factory=dict_row) as conn:
+        with conn.cursor() as cur:
+            cur.execute(sql, params)
+            return list(cur.fetchall())
+
+
+server = MCPServer(catalog, executor=executor)
+server.run(transport="stdio")
+```
+
+The MCP server never imports a database driver. Whatever you wire in
+is what gets called; semql-mcp just hands it `(sql, params)` and
+expects `list[dict]` back.
+
+## Tools
+
+Always registered:
+
+| Tool | Description |
+|---|---|
+| `query_semantic(spec, context?)` | Compile a SemanticQuery; return `{backend, sql, params, columns}`. |
+| `validate(spec)` | Collect-all static validation; returns `list[ValidationError]`. Empty when the query would compile cleanly. |
+| `explain(spec, context?)` | Compile and return just the SQL string. |
+| `catalog_prompt(only_exposed=True, include_introspection=False)` | Render the planner prompt fragment for the catalogue. |
+
+Registered when `executor` is supplied:
+
+| Tool | Description |
+|---|---|
+| `query_execute(spec, context?)` | Compile + run. Returns the `query_semantic` shape plus `rows: list[dict]`. Errors carry the SQL we tried to run so callers can replay / inspect it. |
+
+### Auto-generated per-cube tools
+
+For each `expose_in_prompt=True` (non-META) cube, the server also
+registers a `query_<cube_name>` tool whose `measures`, `dimensions`,
+`order` (and `time_window.dimension`, when applicable) parameters are
+**`Literal`-typed enums** of the cube's actual fields. The planner
+sees a JSON Schema with explicit allowed values rather than the bare
+`list[str]` `query_semantic` accepts.
+
+Field names are **bare** (no cube prefix); the tool auto-qualifies as
+it builds the `SemanticQuery`:
+
+```jsonc
+// query_orders
+{
+  "measures": ["revenue"],
+  "dimensions": ["region"],
+  "filters": [{"dimension": "status", "op": "eq", "values": ["paid"]}],
+  "time_window": {
+    "dimension": "created_at",
+    "granularity": "day",
+    "range": ["2026-01-01", "2026-02-01"]
+  },
+  "limit": 100
+}
+```
+
+Multi-cube queries (joins across cubes) still go through
+`query_semantic` — the per-cube tools are scoped to a single cube by
+construction. When `executor` is configured, the per-cube tools
+return rows too.
+
+## In-process testing
+
+FastMCP's `Client` connects to a `FastMCP` instance without a transport
+— useful for end-to-end testing of your catalogue + planner together:
+
+```python
+import asyncio
+from fastmcp import Client
+from semql_mcp import MCPServer
+
+server = MCPServer(catalog)
+
+async def smoke() -> None:
+    async with Client(server.mcp) as c:
+        tools = await c.list_tools()
+        print([t.name for t in tools])
+        result = await c.call_tool("explain", {"spec": {"measures": ["orders.revenue"]}})
+        print(result.data)
+
+asyncio.run(smoke())
+```
+
+## Status
+
+Early development. The tool surface is stable.

semql_mcp-0.1.0/README.md

@@ -0,0 +1,146 @@
+# semql-mcp
+
+An MCP server that wraps a [`semql`](../semql) `Catalog` and exposes
+its compiler / validator / prompt-renderer surfaces as tools any MCP
+client can call. Built on [FastMCP](https://github.com/jlowin/fastmcp).
+
+## Two modes
+
+By default the server is **compile-only**. `semql` is a pure compiler —
+no I/O — and this server keeps that contract. Tools return the emitted
+SQL and bound parameters; the caller runs the SQL against whatever
+backend they own.
+
+Pass an `executor` at construction to opt into **exec mode**. A
+`query_execute` tool registers in addition to the compile-only tools;
+it runs the SQL against your executor and returns both the SQL/params
+envelope and the resulting rows.
+
+## Install
+
+```sh
+pip install semql-mcp
+```
+
+## Quick start — compile-only
+
+```python
+from semql import Backend, Catalog, Cube, Dimension, Measure
+from semql_mcp import MCPServer
+
+catalog = Catalog([
+    Cube(
+        name="orders",
+        backend=Backend.POSTGRES,
+        table="orders",
+        alias="o",
+        measures=[Measure(name="revenue", sql="{o}.amount", agg="sum", unit="currency")],
+        dimensions=[Dimension(name="region", sql="{o}.region", type="string")],
+    ),
+])
+
+server = MCPServer(catalog)
+server.run(transport="stdio")  # speak JSON-RPC over stdin/stdout
+```
+
+## Quick start — exec mode
+
+Bring your own database driver and adapt its row shape to a list of
+dicts:
+
+```python
+import psycopg
+from psycopg.rows import dict_row
+
+from semql_mcp import MCPServer
+
+
+def executor(sql: str, params: dict) -> list[dict]:
+    with psycopg.connect("postgresql://...", row_factory=dict_row) as conn:
+        with conn.cursor() as cur:
+            cur.execute(sql, params)
+            return list(cur.fetchall())
+
+
+server = MCPServer(catalog, executor=executor)
+server.run(transport="stdio")
+```
+
+The MCP server never imports a database driver. Whatever you wire in
+is what gets called; semql-mcp just hands it `(sql, params)` and
+expects `list[dict]` back.
+
+## Tools
+
+Always registered:
+
+| Tool | Description |
+|---|---|
+| `query_semantic(spec, context?)` | Compile a SemanticQuery; return `{backend, sql, params, columns}`. |
+| `validate(spec)` | Collect-all static validation; returns `list[ValidationError]`. Empty when the query would compile cleanly. |
+| `explain(spec, context?)` | Compile and return just the SQL string. |
+| `catalog_prompt(only_exposed=True, include_introspection=False)` | Render the planner prompt fragment for the catalogue. |
+
+Registered when `executor` is supplied:
+
+| Tool | Description |
+|---|---|
+| `query_execute(spec, context?)` | Compile + run. Returns the `query_semantic` shape plus `rows: list[dict]`. Errors carry the SQL we tried to run so callers can replay / inspect it. |
+
+### Auto-generated per-cube tools
+
+For each `expose_in_prompt=True` (non-META) cube, the server also
+registers a `query_<cube_name>` tool whose `measures`, `dimensions`,
+`order` (and `time_window.dimension`, when applicable) parameters are
+**`Literal`-typed enums** of the cube's actual fields. The planner
+sees a JSON Schema with explicit allowed values rather than the bare
+`list[str]` `query_semantic` accepts.
+
+Field names are **bare** (no cube prefix); the tool auto-qualifies as
+it builds the `SemanticQuery`:
+
+```jsonc
+// query_orders
+{
+  "measures": ["revenue"],
+  "dimensions": ["region"],
+  "filters": [{"dimension": "status", "op": "eq", "values": ["paid"]}],
+  "time_window": {
+    "dimension": "created_at",
+    "granularity": "day",
+    "range": ["2026-01-01", "2026-02-01"]
+  },
+  "limit": 100
+}
+```
+
+Multi-cube queries (joins across cubes) still go through
+`query_semantic` — the per-cube tools are scoped to a single cube by
+construction. When `executor` is configured, the per-cube tools
+return rows too.
+
+## In-process testing
+
+FastMCP's `Client` connects to a `FastMCP` instance without a transport
+— useful for end-to-end testing of your catalogue + planner together:
+
+```python
+import asyncio
+from fastmcp import Client
+from semql_mcp import MCPServer
+
+server = MCPServer(catalog)
+
+async def smoke() -> None:
+    async with Client(server.mcp) as c:
+        tools = await c.list_tools()
+        print([t.name for t in tools])
+        result = await c.call_tool("explain", {"spec": {"measures": ["orders.revenue"]}})
+        print(result.data)
+
+asyncio.run(smoke())
+```
+
+## Status
+
+Early development. The tool surface is stable.

semql_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "semql-mcp"
+version = "0.1.0"
+description = "MCP server that wraps a semql Catalog — compile-only by default, opt-in row execution via a caller-provided executor."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Nikhil Pallamreddy", email = "nikhil.pallamreddy+git@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "fastmcp>=3.4.2",
+    "semql>=0.1.0,<0.2",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/npalladium/semql"
+Repository = "https://github.com/npalladium/semql"
+Issues = "https://github.com/npalladium/semql/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+semql = { workspace = true, editable = true }

semql_mcp-0.1.0/src/semql_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""Public surface of the semql-mcp package."""
+
+from __future__ import annotations
+
+from semql_mcp.server import Executor, MCPServer
+
+__all__ = ["Executor", "MCPServer"]

semql_mcp-0.1.0/src/semql_mcp/server.py

@@ -0,0 +1,367 @@
+# pyright: reportUnusedFunction=false, reportUnknownParameterType=false, reportUnknownArgumentType=false, reportUnknownVariableType=false, reportMissingParameterType=false, reportUnknownMemberType=false
+# - reportUnusedFunction: FastMCP's @mcp.tool decorators register the
+#   wrapped function with the server; pyright sees the local name as
+#   "unused" because it can't follow the decorator's side effect.
+# - reportUnknownParameterType / Argument / Variable / Missing: the
+#   per-cube tool factory builds dynamic ``Literal[...]`` annotations
+#   at runtime and attaches them via ``__annotations__``; the def
+#   itself intentionally has no static type hints.
+"""MCP server wrapping a ``semql.Catalog``.
+
+The server exposes the compiler / validator / prompt-renderer surfaces
+as MCP tools so an LLM (or any MCP client) can plan and reason about
+semantic queries against the catalogue.
+
+By default the server is **compile-only**: ``semql`` is pure, so is
+this server, and callers run the emitted SQL against whatever backend
+they own. Pass an ``executor`` at construction to opt into row-returning
+mode — a ``query_execute`` tool registers in addition to the
+compile-only tools, runs the SQL against the executor, and returns
+both the SQL and the rows. The executor is the only stateful surface
+the server owns; everything else stays pure.
+
+Tools always registered:
+- ``query_semantic(spec, context?)`` — compile a SemanticQuery, return
+  ``{sql, params, columns, backend}``.
+- ``validate(spec)`` — collect-all static validation; returns a list
+  of ``ValidationError`` records.
+- ``explain(spec, context?)`` — same as ``query_semantic`` but returns
+  just the SQL string.
+- ``catalog_prompt(only_exposed=True, include_introspection=False)`` —
+  planner prompt fragment.
+
+Registered only when ``executor`` is supplied:
+- ``query_execute(spec, context?)`` — compile + run; returns the
+  ``query_semantic`` shape plus ``rows: list[dict]``.
+
+Transports: stdio (FastMCP default) plus anything FastMCP supports
+out of the box. Use ``server.run(transport="stdio")`` for a
+CLI-launched process, or pass ``server.mcp`` to a custom transport.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import asdict
+from typing import Any, Literal
+
+from fastmcp import FastMCP
+from semql import Catalog
+from semql.model import Cube
+from semql.spec import Filter, SemanticQuery, TimeWindow
+from semql.validate import ValidationError
+from semql.validate import validate as validate_query
+
+Transport = Literal["stdio", "http", "sse", "streamable-http"]
+"""FastMCP transport identifiers."""
+
+Executor = Callable[[str, dict[str, Any]], list[dict[str, Any]]]
+"""``(sql, params) -> rows`` — sync executor surface.
+
+Callers provide their own database driver (psycopg, clickhouse-connect,
+DuckDB, ...) and adapt its row shape to a list of dicts. The MCP
+server never imports a database driver itself."""
+
+
+class MCPServer:
+    """An MCP server exposing a SemQL ``Catalog`` to MCP clients.
+
+    The ``mcp`` attribute is the underlying ``FastMCP`` instance — pass
+    it to a ``fastmcp.Client`` for in-process testing, or call
+    ``server.run(transport=...)`` to launch a real transport."""
+
+    def __init__(
+        self,
+        catalog: Catalog,
+        *,
+        executor: Executor | None = None,
+        name: str = "semql",
+    ) -> None:
+        self.catalog = catalog
+        self.executor = executor
+        self.mcp = FastMCP(name=name)
+        self._register_tools()
+        self._register_per_cube_tools()
+
+    def _register_tools(self) -> None:
+        catalog = self.catalog
+        executor = self.executor
+
+        @self.mcp.tool(
+            name="query_semantic",
+            description=(
+                "Compile a SemanticQuery against the catalogue and return "
+                "the emitted SQL, the bound parameters, and the output "
+                "column names. Pass ``context`` for ``{schema}`` / "
+                "``{ctx.X}`` substitution at compile time."
+            ),
+        )
+        def query_semantic(
+            spec: SemanticQuery,
+            context: dict[str, str] | None = None,
+        ) -> dict[str, Any]:
+            try:
+                compiled = catalog.compile(spec, context=context)
+            except Exception as exc:
+                return _error_payload(exc)
+            return {
+                "backend": compiled.backend.value,
+                "sql": compiled.sql,
+                "params": compiled.params,
+                "columns": compiled.columns,
+            }
+
+        @self.mcp.tool(
+            name="validate",
+            description=(
+                "Run collect-all static validation. Returns a list of "
+                "structured ValidationError records — empty when the "
+                "query would compile cleanly."
+            ),
+        )
+        def validate(spec: SemanticQuery) -> list[dict[str, Any]]:
+            errors: list[ValidationError] = validate_query(spec, catalog)
+            return [asdict(e) for e in errors]
+
+        @self.mcp.tool(
+            name="explain",
+            description=(
+                "Compile a SemanticQuery and return just the SQL string. "
+                "Equivalent to ``query_semantic(...).sql`` — handy for "
+                "debugging 'what would you have run' without the params "
+                "envelope."
+            ),
+        )
+        def explain(
+            spec: SemanticQuery,
+            context: dict[str, str] | None = None,
+        ) -> str:
+            try:
+                compiled = catalog.compile(spec, context=context)
+            except Exception as exc:
+                return f"-- compile failed: {exc}"
+            return compiled.sql
+
+        @self.mcp.tool(
+            name="catalog_prompt",
+            description=(
+                "Render the planner prompt fragment for this catalogue — "
+                "what an LLM planner would see to learn the catalogue's "
+                "vocabulary and the SemanticQuery contract."
+            ),
+        )
+        def catalog_prompt(
+            only_exposed: bool = True,
+            include_introspection: bool = False,
+        ) -> str:
+            return catalog.prompt(
+                only_exposed=only_exposed,
+                include_introspection=include_introspection,
+            )
+
+        if executor is not None:
+
+            @self.mcp.tool(
+                name="query_execute",
+                description=(
+                    "Compile a SemanticQuery, execute it against the "
+                    "configured database, and return both the SQL/params "
+                    "envelope and the resulting rows. Available only when "
+                    "the server was constructed with an ``executor``. "
+                    "Errors from compile or execute surface as a "
+                    "structured ``{error}`` payload."
+                ),
+            )
+            def query_execute(
+                spec: SemanticQuery,
+                context: dict[str, str] | None = None,
+            ) -> dict[str, Any]:
+                try:
+                    compiled = catalog.compile(spec, context=context)
+                except Exception as exc:
+                    return _error_payload(exc)
+                try:
+                    rows = executor(compiled.sql, compiled.params)
+                except Exception as exc:
+                    return _error_payload(exc) | {
+                        "sql": compiled.sql,
+                        "params": compiled.params,
+                    }
+                return {
+                    "backend": compiled.backend.value,
+                    "sql": compiled.sql,
+                    "params": compiled.params,
+                    "columns": compiled.columns,
+                    "rows": rows,
+                }
+
+    def _register_per_cube_tools(self) -> None:
+        """For each exposed, non-META cube, register a ``query_<cube>``
+        tool whose ``measures`` / ``dimensions`` / ``time_window.dimension``
+        parameters are ``Literal``-typed enums of the cube's actual
+        fields. Hidden cubes (``expose_in_prompt=False``) and META
+        reflection cubes are skipped — multi-cube and introspection
+        queries go through ``query_semantic``."""
+        from semql import iter_cubes
+
+        catalog = self.catalog
+        executor = self.executor
+        for cube in iter_cubes(catalog, only_exposed=True):
+            self.mcp.add_tool(_make_query_cube_tool(cube, catalog, executor))
+
+    def run(self, transport: Transport = "stdio", **kwargs: Any) -> None:  # noqa: ANN401
+        """Launch the server on ``transport``.
+
+        Defaults to stdio so a parent process can spawn the server and
+        speak JSON-RPC over its stdin/stdout. Forwards remaining kwargs
+        to FastMCP."""
+        self.mcp.run(transport=transport, **kwargs)
+
+
+def _error_payload(exc: Exception) -> dict[str, Any]:
+    """Turn an exception into a structured tool response.
+
+    The MCP client should be able to surface the failure mode to the
+    planner; raising would just crash the tool call. ``code`` matches
+    SemQL's error-leaf class names so callers can branch on them
+    without parsing the message."""
+    return {
+        "error": {
+            "code": type(exc).__name__,
+            "message": str(exc),
+        }
+    }
+
+
+def _make_query_cube_tool(
+    cube: Cube,
+    catalog: Catalog,
+    executor: Executor | None,
+) -> Callable[..., dict[str, Any]]:
+    """Build a per-cube ``query_<cube>`` tool function.
+
+    The returned function has ``__name__`` set to ``query_<cube_name>``,
+    ``__doc__`` set to the cube's description, and ``__annotations__``
+    set to typed signatures whose ``measures`` / ``dimensions`` /
+    ``time_window.dimension`` are ``Literal``-typed enums of the cube's
+    actual field names. FastMCP reads those via ``inspect.signature``
+    to generate a JSON Schema with the enum constraint.
+
+    The body auto-prefixes the bare field names with ``cube.name.`` so
+    the planner doesn't have to repeat the cube name."""
+    cube_name = cube.name
+    measure_names = tuple(m.name for m in cube.measures)
+    dimension_names = tuple(d.name for d in cube.dimensions)
+    time_dim_names = tuple(td.name for td in cube.time_dimensions)
+    field_names = (*measure_names, *dimension_names, *time_dim_names)
+
+    # Build Literal types at runtime. ``Literal[("a", "b")]`` syntax is
+    # supported in Python 3.11+ via the subscription protocol. The
+    # types are attached to the function's ``__annotations__`` below —
+    # the ``def`` itself can't reference them directly because this
+    # module uses ``from __future__ import annotations`` (annotations
+    # would be unresolvable string forms).
+    measure_t = list[Literal[measure_names]] if measure_names else list[str]  # type: ignore[valid-type]
+    dim_t = list[Literal[dimension_names]] if dimension_names else list[str]  # type: ignore[valid-type]
+    field_t = Literal[field_names] if field_names else str
+    order_t = list[tuple[field_t, Literal["asc", "desc"]]]  # type: ignore[valid-type]
+
+    def query_cube_fn(  # type: ignore[no-untyped-def]  # noqa: ANN202 — signature attached via __annotations__ below
+        measures=None,  # noqa: ANN001
+        dimensions=None,  # noqa: ANN001
+        filters=None,  # noqa: ANN001
+        time_window=None,  # noqa: ANN001
+        having=None,  # noqa: ANN001
+        order=None,  # noqa: ANN001
+        limit=None,  # noqa: ANN001
+        offset=None,  # noqa: ANN001
+        ungrouped=False,  # noqa: ANN001
+        context=None,  # noqa: ANN001
+    ):
+        try:
+            spec = SemanticQuery(
+                measures=[f"{cube_name}.{m}" for m in (measures or [])],
+                dimensions=[f"{cube_name}.{d}" for d in (dimensions or [])],
+                filters=[
+                    Filter(
+                        dimension=_prefix(f.dimension, cube_name),
+                        op=f.op,
+                        values=f.values,
+                    )
+                    for f in (filters or [])
+                ],
+                time_dimension=_prefix_time_window(time_window, cube_name),
+                having=[
+                    Filter(dimension=h.dimension, op=h.op, values=h.values) for h in (having or [])
+                ],
+                order=[(o[0], o[1]) for o in (order or [])],
+                limit=limit,
+                offset=offset,
+                ungrouped=ungrouped,
+            )
+        except Exception as exc:
+            return _error_payload(exc)
+        try:
+            compiled = catalog.compile(spec, context=context)
+        except Exception as exc:
+            return _error_payload(exc)
+        envelope: dict[str, Any] = {
+            "backend": compiled.backend.value,
+            "sql": compiled.sql,
+            "params": compiled.params,
+            "columns": compiled.columns,
+        }
+        if executor is None:
+            return envelope
+        try:
+            envelope["rows"] = executor(compiled.sql, compiled.params)
+        except Exception as exc:
+            return _error_payload(exc) | envelope
+        return envelope
+
+    query_cube_fn.__name__ = f"query_{cube_name}"
+    query_cube_fn.__doc__ = (cube.description or f"Query the {cube_name} cube.") + (
+        f"\n\nMeasures: {', '.join(measure_names) or '(none)'}."
+        f"\nDimensions: {', '.join(dimension_names) or '(none)'}."
+        + (f"\nTime dimensions: {', '.join(time_dim_names)}." if time_dim_names else "")
+        + "\n\nField names are bare (no cube prefix); the tool "
+        "auto-qualifies them as it builds the SemanticQuery."
+    )
+    query_cube_fn.__annotations__ = {
+        "measures": measure_t | None,
+        "dimensions": dim_t | None,
+        "filters": list[Filter] | None,
+        "time_window": TimeWindow | None,
+        "having": list[Filter] | None,
+        "order": order_t | None,
+        "limit": int | None,
+        "offset": int | None,
+        "ungrouped": bool,
+        "context": dict[str, str] | None,
+        "return": dict[str, Any],
+    }
+    return query_cube_fn
+
+
+def _prefix(name: str, cube_name: str) -> str:
+    """Auto-prefix a bare field name with the cube name.
+
+    If the caller already qualified the name (``orders.region``), pass
+    it through unchanged so cross-cube references in filters/having
+    still work."""
+    if "." in name:
+        return name
+    return f"{cube_name}.{name}"
+
+
+def _prefix_time_window(tw: TimeWindow | None, cube_name: str) -> TimeWindow | None:
+    if tw is None:
+        return None
+    return TimeWindow(
+        dimension=_prefix(tw.dimension, cube_name),
+        granularity=tw.granularity,
+        range=tw.range,
+    )
+
+
+__all__ = ["Executor", "MCPServer"]