lakelogic-mcp 0.1.0__tar.gz

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

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+# A pushed `v*` tag builds, tests and publishes. PyPI Trusted Publishing (OIDC): no stored token.
+# PyPI must have a trusted publisher for (owner=LakeLogic, repo=lakelogic-mcp,
+# workflow=publish.yml, environment=pypi); add it as a "pending publisher" before the first release.
+
+on:
+    push:
+        tags:
+            - "v*"
+
+permissions:
+    contents: read
+    id-token: write
+
+jobs:
+    pypi-publish:
+        runs-on: ubuntu-latest
+        environment: pypi
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                  python-version: "3.12"
+            - name: Tag matches the version
+              run: |
+                  v=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+                  test "v$v" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} != pyproject v$v"; exit 1; }
+            - run: pip install -e ".[dev]" build
+            - run: pytest -q
+            - run: python -m build
+            - uses: pypa/gh-action-pypi-publish@release/v1

lakelogic_mcp-0.1.0/.github/workflows/test.yml

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

lakelogic_mcp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

lakelogic_mcp-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 LakeLogic
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

lakelogic_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: lakelogic-mcp
+Version: 0.1.0
+Summary: A local MCP server that lets AI assistants validate, lint and explain Open Lakehouse Contracts.
+License: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: lakelogic>=1.78.0
+Requires-Dist: mcp>=1.2
+Requires-Dist: open-lakehouse-contract>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lakelogic-mcp
+
+A **local** MCP server that lets AI assistants (Claude Code, Claude Desktop, Cursor and any MCP client)
+check the Open Lakehouse Contracts (OLC) they write, using LakeLogic itself instead of guessing.
+
+- Runs on your machine over stdio. **No network, no account, no telemetry.**
+- **Never touches a platform.** Two tools act locally: `generate_test_data` writes a data file and
+  `run_contract` runs a contract on it with Polars or DuckDB. Nothing is written to a contract's target.
+- Reads and writes only inside the project folder it was started in.
+
+## Tools
+
+| Tool | Answers |
+|---|---|
+| `validate_contract` | Is this a legal OLC contract? Each error's location and problem |
+| `lint_contract` | Is it a good one? Governance findings from `lakelogic lint`, each with its fix |
+| `explain_rule` | Why does a lint rule exist? What it checks, why it matters, a failing and a fixed contract |
+| `contract_reference` | How is one part of a contract written? (`anatomy`, `quality`, `materialization`, …) |
+| `export_odcs` | The contract as an Open Data Contract Standard document |
+| `generate_test_data` | Synthetic data shaped by the contract, with a share of rows that deliberately break its rules |
+| `run_contract` | How many rows pass, how many are quarantined, and why (Polars or DuckDB, local only) |
+
+## Install
+
+```bash
+claude mcp add lakelogic -- uvx lakelogic-mcp
+```
+
+## Try it locally (development checkout)
+
+```bash
+cd C:\_Personal\_SaaS\lakelogic-mcp
+uv venv .venv
+uv pip install --python .venv\Scripts\python.exe "mcp>=1.2" pytest -e ..\open-lakehouse-contract -e ..\lakelogic
+uv pip install --python .venv\Scripts\python.exe --no-deps -e .
+.venv\Scripts\python.exe -m pytest
+```
+
+### Register it with Claude Code
+
+From the project whose contracts you want checked:
+
+```bash
+claude mcp add lakelogic -- C:\_Personal\_SaaS\lakelogic-mcp\.venv\Scripts\lakelogic-mcp.exe
+```
+
+Then ask, for example:
+
+- "Lint the contracts in this folder and fix what you find."
+- "Why is KEY-002 flagged on silver_trips.yaml?"
+- "Write a silver contract for orders and check it before you show me."
+
+### Claude Desktop / Cursor
+
+Add to the client's MCP settings (`claude_desktop_config.json`, or Cursor's `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "lakelogic": {
+      "command": "C:\\_Personal\\_SaaS\\lakelogic-mcp\\.venv\\Scripts\\lakelogic-mcp.exe",
+      "args": ["--root", "C:\\path\\to\\your\\contracts\\project"]
+    }
+  }
+}
+```
+
+## Once published
+
+```bash
+uvx lakelogic-mcp            # Claude Code: claude mcp add lakelogic -- uvx lakelogic-mcp
+```

lakelogic_mcp-0.1.0/README.md

@@ -0,0 +1,72 @@
+# lakelogic-mcp
+
+A **local** MCP server that lets AI assistants (Claude Code, Claude Desktop, Cursor and any MCP client)
+check the Open Lakehouse Contracts (OLC) they write, using LakeLogic itself instead of guessing.
+
+- Runs on your machine over stdio. **No network, no account, no telemetry.**
+- **Never touches a platform.** Two tools act locally: `generate_test_data` writes a data file and
+  `run_contract` runs a contract on it with Polars or DuckDB. Nothing is written to a contract's target.
+- Reads and writes only inside the project folder it was started in.
+
+## Tools
+
+| Tool | Answers |
+|---|---|
+| `validate_contract` | Is this a legal OLC contract? Each error's location and problem |
+| `lint_contract` | Is it a good one? Governance findings from `lakelogic lint`, each with its fix |
+| `explain_rule` | Why does a lint rule exist? What it checks, why it matters, a failing and a fixed contract |
+| `contract_reference` | How is one part of a contract written? (`anatomy`, `quality`, `materialization`, …) |
+| `export_odcs` | The contract as an Open Data Contract Standard document |
+| `generate_test_data` | Synthetic data shaped by the contract, with a share of rows that deliberately break its rules |
+| `run_contract` | How many rows pass, how many are quarantined, and why (Polars or DuckDB, local only) |
+
+## Install
+
+```bash
+claude mcp add lakelogic -- uvx lakelogic-mcp
+```
+
+## Try it locally (development checkout)
+
+```bash
+cd C:\_Personal\_SaaS\lakelogic-mcp
+uv venv .venv
+uv pip install --python .venv\Scripts\python.exe "mcp>=1.2" pytest -e ..\open-lakehouse-contract -e ..\lakelogic
+uv pip install --python .venv\Scripts\python.exe --no-deps -e .
+.venv\Scripts\python.exe -m pytest
+```
+
+### Register it with Claude Code
+
+From the project whose contracts you want checked:
+
+```bash
+claude mcp add lakelogic -- C:\_Personal\_SaaS\lakelogic-mcp\.venv\Scripts\lakelogic-mcp.exe
+```
+
+Then ask, for example:
+
+- "Lint the contracts in this folder and fix what you find."
+- "Why is KEY-002 flagged on silver_trips.yaml?"
+- "Write a silver contract for orders and check it before you show me."
+
+### Claude Desktop / Cursor
+
+Add to the client's MCP settings (`claude_desktop_config.json`, or Cursor's `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "lakelogic": {
+      "command": "C:\\_Personal\\_SaaS\\lakelogic-mcp\\.venv\\Scripts\\lakelogic-mcp.exe",
+      "args": ["--root", "C:\\path\\to\\your\\contracts\\project"]
+    }
+  }
+}
+```
+
+## Once published
+
+```bash
+uvx lakelogic-mcp            # Claude Code: claude mcp add lakelogic -- uvx lakelogic-mcp
+```

lakelogic_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "lakelogic-mcp"
+version = "0.1.0"
+description = "A local MCP server that lets AI assistants validate, lint and explain Open Lakehouse Contracts."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+dependencies = [
+    "mcp>=1.2",  # 1.x (FastMCP) and 2.x (MCPServer) both supported
+    "lakelogic>=1.78.0",  # the lint rule catalogue (explain_rule) ships in 1.78.0
+    "open-lakehouse-contract>=0.24.0",
+]
+
+[project.scripts]
+lakelogic-mcp = "lakelogic_mcp.server:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lakelogic_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

lakelogic_mcp-0.1.0/src/lakelogic_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""lakelogic-mcp: Open Lakehouse Contract tools for AI assistants, over MCP (stdio, local only)."""
+
+__version__ = "0.1.0"

lakelogic_mcp-0.1.0/src/lakelogic_mcp/server.py

@@ -0,0 +1,111 @@
+"""The MCP server: the tools over stdio. Local only: no network, no account, no telemetry.
+
+    lakelogic-mcp                 # serve the current folder
+    lakelogic-mcp --root <folder> # serve another folder
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any, Dict, Optional
+
+try:  # MCP SDK 2.x
+    from mcp.server.mcpserver import MCPServer as _Server
+except ImportError:  # MCP SDK 1.x
+    from mcp.server.fastmcp import FastMCP as _Server
+from mcp.types import ToolAnnotations
+
+from lakelogic_mcp import tools
+
+#: Writes files inside the project and runs code on them; never touches a platform.
+_LOCAL_WRITE = ToolAnnotations(readOnlyHint=False, destructiveHint=False, idempotentHint=False, openWorldHint=False)
+
+#: These tools only read and checks: clients may call them without asking each time.
+_READ_ONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False)
+
+mcp = _Server(
+    "lakelogic",
+    instructions=(
+        "Tools for Open Lakehouse Contracts (OLC). After writing or changing a contract, call "
+        "validate_contract (is it legal OLC?) and then lint_contract (is it a good one?), and fix what "
+        "they report before showing it. Use explain_rule to learn why a lint rule exists, and "
+        "contract_reference to read how a part of the contract is written. To show a contract working, "
+        "call generate_test_data and then run_contract on the file it wrote."
+    ),
+)
+
+
+def _call(fn, *args, **kwargs) -> Dict[str, Any]:
+    try:
+        return fn(*args, **kwargs)
+    except tools.ToolError as exc:
+        return {"error": str(exc)}
+
+
+@mcp.tool(annotations=_READ_ONLY)
+def validate_contract(path: Optional[str] = None, contract_yaml: Optional[str] = None) -> Dict[str, Any]:
+    """Check whether a contract is LEGAL Open Lakehouse Contract (OLC): known keys, right shapes, required
+    fields. Use it after writing or editing a contract. Give `path` (a file in this project) or
+    `contract_yaml` (the text). Returns `valid` and, if not, each error's location and problem."""
+    return _call(tools.validate_contract, path=path, contract_yaml=contract_yaml)
+
+
+@mcp.tool(annotations=_READ_ONLY)
+def lint_contract(path: Optional[str] = None, contract_yaml: Optional[str] = None) -> Dict[str, Any]:
+    """Check whether a contract is a GOOD one: governance gaps such as a merge with no key, unordered
+    deduplication, untagged personal data, a step no engine runs. Use it after validate_contract passes.
+    Returns `clean` and findings, each with its rule code, severity and fix."""
+    return _call(tools.lint_contract, path=path, contract_yaml=contract_yaml)
+
+
+@mcp.tool(annotations=_READ_ONLY)
+def explain_rule(code: str) -> Dict[str, Any]:
+    """Explain one lint rule (e.g. KEY-002): what it checks, why it matters, a failing contract and the
+    fixed contract. Use it when a lint finding is unclear."""
+    return _call(tools.explain_rule, code)
+
+
+@mcp.tool(annotations=_READ_ONLY)
+def contract_reference(topic: str) -> Dict[str, Any]:
+    """Read the OLC reference for one part of a contract. Topics include anatomy (every key),
+    quality, transformation, materialization, ingestion, security, slo, execution-order."""
+    return _call(tools.contract_reference, topic)
+
+
+@mcp.tool(annotations=_READ_ONLY)
+def export_odcs(path: str) -> Dict[str, Any]:
+    """Convert a contract file in this project to an Open Data Contract Standard (ODCS) document."""
+    return _call(tools.export_odcs, path)
+
+
+@mcp.tool(annotations=_LOCAL_WRITE)
+def generate_test_data(
+    path: str, rows: int = 100, invalid_ratio: float = 0.1, seed: Optional[int] = None, output: Optional[str] = None
+) -> Dict[str, Any]:
+    """Write synthetic test data for a contract (default test_data/<contract>.csv): right types,
+    accepted values and ranges, with `invalid_ratio` of rows deliberately breaking the quality rules
+    so a run shows quarantine working. Follow with run_contract."""
+    return _call(tools.generate_test_data, path, rows=rows, invalid_ratio=invalid_ratio, seed=seed, output=output)
+
+
+@mcp.tool(annotations=_LOCAL_WRITE)
+def run_contract(
+    path: str, source: str, engine: str = "polars", sample: int = 10, write_outputs: bool = False
+) -> Dict[str, Any]:
+    """Run a contract on a local data file (CSV/Parquet) with Polars or DuckDB: good rows,
+    quarantined rows, and each quarantine reason with its count. Writes nothing to the contract's
+    target. `write_outputs` saves good/bad rows under runs/."""
+    return _call(tools.run_contract, path, source, engine=engine, sample=sample, write_outputs=write_outputs)
+
+
+def main(argv: Optional[list[str]] = None) -> None:
+    parser = argparse.ArgumentParser(prog="lakelogic-mcp")
+    parser.add_argument("--root", help="the project folder tools may read (default: the current folder)")
+    args = parser.parse_args(argv)
+    if args.root:
+        tools.set_root(args.root)
+    mcp.run()  # stdio
+
+
+if __name__ == "__main__":
+    main()

lakelogic_mcp-0.1.0/src/lakelogic_mcp/tools.py

@@ -0,0 +1,302 @@
+"""The tools, as plain functions. Thin adapters over LakeLogic Core and OLC: any real logic
+belongs in Core or OLC, never here.
+
+Most tools READ and CHECK. Two act: `generate_test_data` writes a data file and `run_contract`
+runs a contract on one, locally (Polars or DuckDB), so an assistant can show a contract working
+before it goes near a platform. Paths are confined to the folder the server
+was started in (``ROOT``), so an assistant cannot read files outside the project it was opened on.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+#: The only folder tools may read from. Set by the server at start (``--root``, default: cwd).
+ROOT = Path(os.environ.get("LAKELOGIC_MCP_ROOT") or os.getcwd()).resolve()
+
+REFERENCE_TOPICS = (
+    "anatomy",
+    "execution-order",
+    "ingestion",
+    "lifecycle",
+    "quality",
+    "security",
+    "compliance",
+    "transformation",
+    "external-logic",
+    "materialization",
+    "server",
+    "lineage",
+    "data-products",
+    "slo",
+    "notifications",
+    "extraction",
+    "conformance",
+    "cli",
+    "schema",
+)
+
+
+class ToolError(ValueError):
+    """A request the tool refuses, with a message the assistant can act on."""
+
+
+def set_root(path: str | Path) -> Path:
+    global ROOT
+    ROOT = Path(path).resolve()
+    return ROOT
+
+
+def _resolve(path: str) -> Path:
+    """``path`` inside ROOT, or a refusal. Relative paths are relative to ROOT."""
+    candidate = Path(path)
+    full = (candidate if candidate.is_absolute() else ROOT / candidate).resolve()
+    if full != ROOT and ROOT not in full.parents:
+        raise ToolError(
+            f"'{path}' is outside the project folder this server was started in ({ROOT}). "
+            "Only files inside it can be read."
+        )
+    if not full.is_file():
+        raise ToolError(f"No contract file at '{path}' (looked in {full}).")
+    return full
+
+
+def _resolve_output(path: str) -> Path:
+    """Where a tool may WRITE: inside ROOT, parent folders created."""
+    candidate = Path(path)
+    full = (candidate if candidate.is_absolute() else ROOT / candidate).resolve()
+    if ROOT not in full.parents:
+        raise ToolError(f"'{path}' is outside the project folder ({ROOT}). Files can only be written inside it.")
+    full.parent.mkdir(parents=True, exist_ok=True)
+    return full
+
+
+def _resolve_data(path: str) -> Path:
+    full = _resolve_output(path)
+    if not full.is_file():
+        raise ToolError(f"No data file at '{path}' (looked in {full}).")
+    return full
+
+
+def _parse(contract_yaml: str) -> Any:
+    from olc.validate import load_contract_yaml
+
+    try:
+        doc = load_contract_yaml(contract_yaml)
+    except Exception as exc:  # noqa: BLE001 - reported to the assistant as findings
+        raise ToolError(f"Not valid YAML: {exc}") from None
+    if not isinstance(doc, dict):
+        raise ToolError("A contract is a YAML mapping (key: value pairs) at the top level.")
+    return doc
+
+
+def _contract_text(path: Optional[str], contract_yaml: Optional[str]) -> tuple[str, str]:
+    if bool(path) == bool(contract_yaml):
+        raise ToolError("Give exactly one of `path` (a contract file) or `contract_yaml` (the contract text).")
+    if path:
+        full = _resolve(path)
+        return full.read_text(encoding="utf-8"), str(full.relative_to(ROOT))
+    return contract_yaml or "", "inline contract"
+
+
+# ── tools ────────────────────────────────────────────────────────────────────────────────────
+
+
+def validate_contract(path: Optional[str] = None, contract_yaml: Optional[str] = None) -> Dict[str, Any]:
+    """Is this a LEGAL OLC contract? Checks it against the strict OLC model."""
+    from olc.models import load_strict
+
+    text, source = _contract_text(path, contract_yaml)
+    doc = _parse(text)
+    try:
+        load_strict(doc)
+    except Exception as exc:  # noqa: BLE001 - pydantic's errors, flattened for the assistant
+        errors = getattr(exc, "errors", None)
+        found: List[Dict[str, str]] = []
+        if callable(errors):
+            for e in errors():
+                found.append({"location": ".".join(str(p) for p in e.get("loc", ())) or "<root>", "problem": e.get("msg", "")})
+        else:
+            found.append({"location": "<root>", "problem": str(exc)})
+        return {"contract": source, "valid": False, "errors": found}
+    return {"contract": source, "valid": True, "errors": []}
+
+
+def lint_contract(path: Optional[str] = None, contract_yaml: Optional[str] = None) -> Dict[str, Any]:
+    """Is this a GOOD contract? Governance findings from `lakelogic lint`, each with its fix.
+
+    With `path`, the contract's domain and system settings (`_domain.yaml` / `_system.yaml`
+    above it) are taken into account, exactly as `lakelogic lint` does.
+    """
+    from lakelogic.core.contract_lint import review_contract, review_contract_dict
+
+    if path:
+        full = _resolve(path)
+        findings = review_contract(full)
+        source = str(full.relative_to(ROOT))
+    else:
+        text, source = _contract_text(None, contract_yaml)
+        findings = review_contract_dict(_parse(text), "inline", None)
+    rows = [
+        {
+            "rule": f.check_id,
+            "severity": f.severity,
+            "message": f.message,
+            "field": f.field,
+            "fix": f.suggestion,
+        }
+        for f in findings
+    ]
+    return {
+        "contract": source,
+        "clean": not any(r["severity"] in ("critical", "warning") for r in rows),
+        "findings": rows,
+    }
+
+
+def explain_rule(code: str) -> Dict[str, Any]:
+    """Why a lint rule exists: what it checks, why it matters, a failing and a fixed contract."""
+    from lakelogic.core.contract_lint_catalogue import CATALOGUE
+
+    entry = CATALOGUE.get(code.strip().upper())
+    if entry is None:
+        raise ToolError(f"No lint rule '{code}'. Known rules: {', '.join(sorted(CATALOGUE))}.")
+    return {
+        "rule": entry.code,
+        "title": entry.title,
+        "severity": entry.severity,
+        "checks": entry.checks,
+        "why": entry.why,
+        "failing_example": entry.failing,
+        "fixed_example": entry.fixed,
+        "fixed_example_is_standard_olc": entry.olc_valid,
+    }
+
+
+def contract_reference(topic: str) -> Dict[str, Any]:
+    """The OLC reference page for one part of a contract (e.g. `quality`, `materialization`)."""
+    import olc
+
+    key = topic.strip().lower().replace(" ", "-").replace("_", "-")
+    if key not in REFERENCE_TOPICS:
+        raise ToolError(f"No reference page '{topic}'. Topics: {', '.join(REFERENCE_TOPICS)}.")
+    page = Path(olc.__file__).resolve().parent / "_bundled" / "docs" / "reference" / f"{key}.md"
+    if not page.exists():
+        raise ToolError(f"The installed OLC package has no '{key}' page.")
+    return {"topic": key, "markdown": page.read_text(encoding="utf-8")}
+
+
+def export_odcs(path: str) -> Dict[str, Any]:
+    """The contract as an Open Data Contract Standard (ODCS) document."""
+    from lakelogic.core.models import DataContract
+
+    full = _resolve(path)
+    try:
+        document = DataContract.from_yaml(str(full)).to_odcs()
+    except Exception as exc:  # noqa: BLE001
+        raise ToolError(f"Could not export '{path}': {exc}") from None
+    return {"contract": str(full.relative_to(ROOT)), "odcs": document}
+
+
+RUN_ENGINES = ("polars", "duckdb")
+ERROR_COLUMN = "_lakelogic_errors"
+
+
+def generate_test_data(
+    path: str, rows: int = 100, invalid_ratio: float = 0.1, seed: Optional[int] = None, output: Optional[str] = None
+) -> Dict[str, Any]:
+    """Synthetic data shaped by the contract: its types, nullability, accepted values and ranges.
+    `invalid_ratio` of the rows deliberately break the quality rules, so a run shows quarantine working."""
+    from lakelogic.core.generator import DataGenerator
+
+    full = _resolve(path)
+    if not 1 <= rows <= 100_000:
+        raise ToolError("rows must be between 1 and 100000.")
+    if not 0.0 <= invalid_ratio <= 1.0:
+        raise ToolError("invalid_ratio must be between 0.0 and 1.0.")
+    out = _resolve_output(output or f"test_data/{full.stem}.csv")
+    if out.suffix.lower() not in (".csv", ".parquet"):
+        raise ToolError("output must end in .csv or .parquet.")
+    try:
+        df = DataGenerator(full, seed=seed).generate(rows=rows, invalid_ratio=invalid_ratio, output_format="polars")
+    except Exception as exc:  # noqa: BLE001
+        raise ToolError(f"Could not generate data for '{path}': {exc}") from None
+    df.write_csv(out) if out.suffix.lower() == ".csv" else df.write_parquet(out)
+    return {
+        "contract": str(full.relative_to(ROOT)),
+        "data_file": str(out.relative_to(ROOT)),
+        "rows": df.height,
+        "columns": df.columns,
+        "intended_invalid_rows": round(rows * invalid_ratio),
+    }
+
+
+def run_contract(
+    path: str, source: str, engine: str = "polars", sample: int = 10, write_outputs: bool = False
+) -> Dict[str, Any]:
+    """Run the contract on a local data file: how many rows pass, how many are quarantined, and why.
+    Nothing is materialized to the contract's target; `write_outputs` saves good/bad rows under runs/."""
+    from lakelogic import DataProcessor
+
+    full = _resolve(path)
+    data = _resolve_data(source)
+    if engine not in RUN_ENGINES:
+        raise ToolError(f"engine must be one of {', '.join(RUN_ENGINES)} locally. Spark, Snowflake and BigQuery run on the platform.")
+    try:
+        # Read the file by ITS type and hand the rows to the contract: `run_source` would read it
+        # with the contract's own source/target format (e.g. Delta), which a local file is not.
+        frame = _read_local(data, engine)
+        result = DataProcessor(engine=engine, contract=str(full)).run(frame)
+    except Exception as exc:  # noqa: BLE001 - a failed run is the answer, not a server error
+        return {"contract": str(full.relative_to(ROOT)), "ran": False, "error": f"{type(exc).__name__}: {exc}"}
+    good, bad = _to_polars(result.good), _to_polars(result.bad)
+    reasons: Dict[str, int] = {}
+    if bad is not None and ERROR_COLUMN in bad.columns:
+        for errs in bad[ERROR_COLUMN].to_list():
+            for e in errs if isinstance(errs, list) else [errs]:
+                if e:
+                    reasons[str(e)] = reasons.get(str(e), 0) + 1
+    out: Dict[str, Any] = {
+        "contract": str(full.relative_to(ROOT)),
+        "ran": True,
+        "engine": engine,
+        "good_rows": 0 if good is None else good.height,
+        "quarantined_rows": 0 if bad is None else bad.height,
+        "quarantine_reasons": dict(sorted(reasons.items(), key=lambda kv: -kv[1])),
+        "quarantined_sample": [] if bad is None else bad.head(sample).to_dicts(),
+    }
+    if write_outputs:
+        stem = full.stem
+        for name, df in (("good", good), ("bad", bad)):
+            if df is not None:
+                target = _resolve_output(f"runs/{stem}_{name}.parquet")
+                df.write_parquet(target)
+                out[f"{name}_file"] = str(target.relative_to(ROOT))
+    return out
+
+
+def _read_local(data: Path, engine: str) -> Any:
+    suffix = data.suffix.lower()
+    if suffix not in (".csv", ".parquet"):
+        raise ToolError("source must be a .csv or .parquet file.")
+    import polars as pl
+
+    frame = pl.read_csv(data, infer_schema_length=10_000) if suffix == ".csv" else pl.read_parquet(data)
+    # DuckDB gets Arrow: a relation built on another connection cannot be read by the engine's own.
+    return frame.to_arrow() if engine == "duckdb" else frame
+
+
+def _to_polars(df: Any) -> Any:
+    if df is None:
+        return None
+    import polars as pl
+
+    if isinstance(df, pl.DataFrame):
+        return df
+    if hasattr(df, "pl"):  # DuckDB relation
+        return df.pl()
+    if hasattr(df, "to_pandas") or hasattr(df, "columns"):
+        return pl.from_pandas(df) if not hasattr(df, "pl") else df.pl()
+    raise ToolError(f"Unexpected result type {type(df).__name__}.")

lakelogic_mcp-0.1.0/tests/test_server_over_mcp.py

@@ -0,0 +1,55 @@
+"""End to end: start the real server as a subprocess and talk to it over MCP (stdio), as a client
+such as Claude Code does."""
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+EXPECTED_TOOLS = {
+    "validate_contract", "lint_contract", "explain_rule", "contract_reference", "export_odcs",
+    "generate_test_data", "run_contract",
+}
+
+CONTRACT = """version: 1.0.0
+info: { title: Trips, table_name: trips }
+model:
+  fields:
+    - { name: trip_id, type: string }
+primary_key: [trip_id]
+materialization: { strategy: scd2, format: delta }
+"""
+
+
+async def _session_run(root: Path):
+    params = StdioServerParameters(
+        command=sys.executable, args=["-m", "lakelogic_mcp.server", "--root", str(root)]
+    )
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            listed = await session.list_tools()
+            lint = await session.call_tool("lint_contract", {"path": "trips.yaml"})
+            outside = await session.call_tool("validate_contract", {"path": "../elsewhere.yaml"})
+            return listed, lint, outside
+
+
+def _payload(result):
+    return json.loads(result.content[0].text)
+
+
+def test_the_server_lists_its_tools_and_answers_over_mcp(tmp_path):
+    (tmp_path / "trips.yaml").write_text(CONTRACT, encoding="utf-8")
+    listed, lint, outside = asyncio.run(_session_run(tmp_path))
+
+    tools = {t.name: t for t in listed.tools}
+    assert set(tools) == EXPECTED_TOOLS
+    assert all(t.description for t in tools.values())
+
+    found = _payload(lint)
+    assert found["clean"] is False and [f["rule"] for f in found["findings"]] == ["SCD-001"]
+
+    assert "outside the project folder" in _payload(outside)["error"]

lakelogic_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,146 @@
+"""Each tool against real contracts, and the one boundary that matters: nothing outside the project."""
+
+from pathlib import Path
+
+import pytest
+
+from lakelogic_mcp import tools
+
+GOOD = """version: 1.0.0
+info: { title: Trips, table_name: trips }
+model:
+  fields:
+    - { name: trip_id, type: string, required: true }
+    - { name: updated_at, type: timestamp }
+primary_key: [trip_id]
+transformations:
+  - deduplicate: { on: [trip_id], sort_by: [updated_at], order: desc }
+"""
+
+# Valid OLC, but the dedup sorts by its own key: KEY-002 (only caught once `on:` is read as a
+# field name, not the boolean YAML 1.1 makes of it).
+SORTED_BY_KEY = GOOD.replace("sort_by: [updated_at]", "sort_by: [trip_id]")
+
+INVALID = """version: 1.0.0
+info: { title: Trips }
+model:
+  fields:
+    - { name: trip_id, type: string }
+materialization:
+  primary_key: [trip_id]
+"""
+
+
+@pytest.fixture()
+def project(tmp_path):
+    tools.set_root(tmp_path)
+    (tmp_path / "contracts").mkdir()
+    (tmp_path / "contracts" / "good.yaml").write_text(GOOD, encoding="utf-8")
+    (tmp_path / "contracts" / "sorted_by_key.yaml").write_text(SORTED_BY_KEY, encoding="utf-8")
+    (tmp_path / "contracts" / "invalid.yaml").write_text(INVALID, encoding="utf-8")
+    yield tmp_path
+
+
+def test_validate_accepts_a_legal_contract(project):
+    assert tools.validate_contract(path="contracts/good.yaml") == {
+        "contract": str(Path("contracts/good.yaml")), "valid": True, "errors": []
+    }
+
+
+def test_validate_names_where_an_illegal_contract_is_wrong(project):
+    result = tools.validate_contract(path="contracts/invalid.yaml")
+    assert result["valid"] is False
+    assert any("primary_key" in e["problem"] or "primary_key" in e["location"] for e in result["errors"])
+
+
+def test_validate_takes_inline_text_too(project):
+    assert tools.validate_contract(contract_yaml=GOOD)["valid"] is True
+
+
+def test_lint_is_clean_for_a_good_contract_and_names_the_rule_otherwise(project):
+    assert tools.lint_contract(path="contracts/good.yaml") == {
+        "contract": str(Path("contracts/good.yaml")), "clean": True, "findings": []
+    }
+    result = tools.lint_contract(path="contracts/sorted_by_key.yaml")
+    assert result["clean"] is False
+    assert [f["rule"] for f in result["findings"]] == ["KEY-002"]
+    assert result["findings"][0]["fix"]
+
+
+def test_explain_rule_returns_the_catalogue_entry(project):
+    entry = tools.explain_rule("key-002")
+    assert entry["rule"] == "KEY-002" and entry["why"] and "sort_by" in entry["failing_example"]
+
+
+def test_explain_rule_lists_the_rules_when_the_code_is_unknown(project):
+    with pytest.raises(tools.ToolError, match="Known rules: .*KEY-002"):
+        tools.explain_rule("NOPE-001")
+
+
+def test_contract_reference_reads_the_bundled_page(project):
+    page = tools.contract_reference("Quality")
+    assert page["topic"] == "quality" and len(page["markdown"]) > 200
+
+
+def test_export_odcs(project):
+    out = tools.export_odcs("contracts/good.yaml")
+    assert out["odcs"]
+
+
+@pytest.mark.parametrize("path", ["../outside.yaml", "C:/Windows/win.ini", "/etc/passwd"])
+def test_nothing_outside_the_project_can_be_read(project, path):
+    (project.parent / "outside.yaml").write_text(GOOD, encoding="utf-8")
+    with pytest.raises(tools.ToolError, match="outside the project folder|No contract file"):
+        tools.validate_contract(path=path)
+
+
+def test_exactly_one_input(project):
+    with pytest.raises(tools.ToolError, match="exactly one"):
+        tools.validate_contract()
+    with pytest.raises(tools.ToolError, match="exactly one"):
+        tools.validate_contract(path="contracts/good.yaml", contract_yaml=GOOD)
+
+
+ORDERS = """version: 1.0.0
+info: { title: Orders, table_name: orders }
+model:
+  fields:
+    - { name: order_id, type: string, required: true }
+    - { name: amount, type: double, min: 0 }
+quality:
+  row_rules:
+    - { name: amount_positive, sql: "amount >= 0" }
+"""
+
+
+@pytest.mark.parametrize("engine", ["polars", "duckdb"])
+def test_generate_then_run_quarantines_the_broken_rows(project, engine):
+    (project / "orders.yaml").write_text(ORDERS, encoding="utf-8")
+    made = tools.generate_test_data("orders.yaml", rows=40, invalid_ratio=0.25, seed=7)
+    assert made["rows"] == 40 and (project / made["data_file"]).is_file()
+
+    run = tools.run_contract("orders.yaml", made["data_file"], engine=engine, write_outputs=True)
+    assert run["ran"] is True
+    assert run["good_rows"] + run["quarantined_rows"] == 40
+    assert run["quarantined_rows"] > 0 and run["quarantine_reasons"]
+    assert (project / run["bad_file"]).is_file()
+
+
+def test_run_refuses_platform_engines_and_outside_paths(project):
+    (project / "orders.yaml").write_text(ORDERS, encoding="utf-8")
+    (project / "d.csv").write_text("order_id,amount\na,1\n", encoding="utf-8")
+    with pytest.raises(tools.ToolError, match="engine must be"):
+        tools.run_contract("orders.yaml", "d.csv", engine="spark")
+    with pytest.raises(tools.ToolError, match="outside the project folder"):
+        tools.generate_test_data("orders.yaml", output="../escape.csv")
+
+
+def test_run_reads_the_file_by_its_type_even_when_the_contract_says_delta(project):
+    """Found by a real Claude Code session: a contract with `format: delta` made run_contract open
+    the CSV as a Delta table ("Invalid table location")."""
+    (project / "orders.yaml").write_text(ORDERS + "materialization: { strategy: merge, format: delta }\n", encoding="utf-8")
+    made = tools.generate_test_data("orders.yaml", rows=20, invalid_ratio=0.2, seed=3)
+    for engine in ("polars", "duckdb"):
+        run = tools.run_contract("orders.yaml", made["data_file"], engine=engine)
+        assert run["ran"] is True, run
+        assert run["good_rows"] + run["quarantined_rows"] == 20