sqlguard-ninja 0.3.0__tar.gz → 0.4.0__tar.gz

{sqlguard_ninja-0.3.0 → sqlguard_ninja-0.4.0}/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes are documented here. The project follows
 [Semantic Versioning](https://semver.org/); before 1.0, minor versions may change the API.
 
+## [0.4.0] — 2026-10-24
+
+### Added
+* **MCP server** (`sqlninja mcp`, `sqlguard_ninja.mcp_server`, extra `[mcp]` on the official
+  MCP Python SDK 2.x). Tools: `validate_sql`, `explain_policy_decision`,
+  `inspect_query_cost`, `get_policy_capabilities`. The role and tenant are fixed server-side,
+  there is no execution and no database connection, internal detail is withheld, ungranted
+  tables and columns are not disclosed, input is size-capped, and calls are rate-limited.
+* An end-to-end test drives the real server over stdio with the SDK's `ClientSession`.
+* Docs: `docs/guides/MCP_INTEGRATION.md`; threat model T17.
+
 ## [0.3.0] — 2026-10-24
 
 ### Added

{sqlguard_ninja-0.3.0 → sqlguard_ninja-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlguard-ninja
-Version: 0.3.0
+Version: 0.4.0
 Summary: Security testing, policy enforcement, agent integration, privacy analysis and CI benchmarking for LLM-generated SQL.
 Project-URL: Homepage, https://github.com/Pratik653/SQLGuard_Ninjapy
 Project-URL: Documentation, https://github.com/Pratik653/SQLGuard_Ninjapy/tree/main/docs
@@ -29,6 +29,7 @@ Provides-Extra: all
 Requires-Dist: fastapi>=0.110; extra == 'all'
 Requires-Dist: langchain-core>=0.3; extra == 'all'
 Requires-Dist: langgraph>=0.2; extra == 'all'
+Requires-Dist: mcp<3,>=2.3; extra == 'all'
 Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == 'dev'
@@ -37,6 +38,7 @@ Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: hypothesis>=6.100; extra == 'dev'
 Requires-Dist: langchain-core>=0.3; extra == 'dev'
 Requires-Dist: langgraph>=0.2; extra == 'dev'
+Requires-Dist: mcp<3,>=2.3; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: psycopg[binary]>=3.1; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
@@ -50,6 +52,8 @@ Requires-Dist: langchain-core>=0.3; extra == 'langchain'
 Provides-Extra: langgraph
 Requires-Dist: langchain-core>=0.3; extra == 'langgraph'
 Requires-Dist: langgraph>=0.2; extra == 'langgraph'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
 Description-Content-Type: text/markdown
@@ -263,6 +267,20 @@ Optional: `SQLCheckpoint(..., rewrite_tenant_filters=True)` adds missing tenant
 through the AST and executes only the re-validated rewrite. See
 [POLICY_AS_CODE.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_AS_CODE.md).
 
+## MCP server
+
+Let MCP-compatible agents check SQL against your policy before running it anywhere:
+
+```bash
+python -m pip install "sqlguard-ninja[mcp]"
+sqlninja mcp --policy builtin:retail_saas --role support_analyst --tenant 1
+```
+
+The four tools are `validate_sql`, `explain_policy_decision`, `inspect_query_cost` and
+`get_policy_capabilities`. The role and tenant are fixed server-side, the server never connects
+to a database, and it exposes no execution tool. Tested with the official MCP Python SDK
+client over stdio. See [MCP_INTEGRATION.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/MCP_INTEGRATION.md).
+
 ## Query cost analysis
 
 Every validation includes an explainable static score that uses the catalog's
@@ -358,6 +376,7 @@ writes, more tested dialects, and SARIF output. Details in [ROADMAP.md](https://
 
 * [Policy reference](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_REFERENCE.md)
 * [Policy as code](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_AS_CODE.md)
+* [MCP integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/MCP_INTEGRATION.md)
 * [Agent integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/AGENT_INTEGRATION.md)
 * [Query cost](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/QUERY_COST.md)
 * [CI integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/CI_INTEGRATION.md)

{sqlguard_ninja-0.3.0 → sqlguard_ninja-0.4.0}/README.md

@@ -207,6 +207,20 @@ Optional: `SQLCheckpoint(..., rewrite_tenant_filters=True)` adds missing tenant
 through the AST and executes only the re-validated rewrite. See
 [POLICY_AS_CODE.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_AS_CODE.md).
 
+## MCP server
+
+Let MCP-compatible agents check SQL against your policy before running it anywhere:
+
+```bash
+python -m pip install "sqlguard-ninja[mcp]"
+sqlninja mcp --policy builtin:retail_saas --role support_analyst --tenant 1
+```
+
+The four tools are `validate_sql`, `explain_policy_decision`, `inspect_query_cost` and
+`get_policy_capabilities`. The role and tenant are fixed server-side, the server never connects
+to a database, and it exposes no execution tool. Tested with the official MCP Python SDK
+client over stdio. See [MCP_INTEGRATION.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/MCP_INTEGRATION.md).
+
 ## Query cost analysis
 
 Every validation includes an explainable static score that uses the catalog's
@@ -302,6 +316,7 @@ writes, more tested dialects, and SARIF output. Details in [ROADMAP.md](https://
 
 * [Policy reference](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_REFERENCE.md)
 * [Policy as code](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_AS_CODE.md)
+* [MCP integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/MCP_INTEGRATION.md)
 * [Agent integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/AGENT_INTEGRATION.md)
 * [Query cost](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/QUERY_COST.md)
 * [CI integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/CI_INTEGRATION.md)

{sqlguard_ninja-0.3.0 → sqlguard_ninja-0.4.0}/docs/development/IMPLEMENTATION_PROGRESS.md

@@ -8,4 +8,5 @@
 | 2a Role inheritance (sticky denies), revision/fingerprint, decision ids, audit fields | VERIFIED (local) | 2f1919c | test_policy_inheritance (11) | |
 | 2b Policy diff/simulate/explain/templates CLI | VERIFIED (local) | e64859a | test_policy_tools (21) | |
 | 2c Opt-in AST tenant-filter rewrite + checkpoint | VERIFIED (local) | b0b5ade | test_tenant_rewrite (32, executes on SQLite, tenants 1-3) | |
-| 2d Docs, ADR-011/012, v0.3.0 bump | VERIFIED (local) | see PR | full gate 1,804 passed, 94% | |
+| 2d Docs, ADR-011/012, v0.3.0 bump | RELEASED v0.3.0 | 198a308 | full gate 1,804 passed, 94% | |
+| 3 MCP server (stdio, validation-only) | VERIFIED (local) | see PR | 9 tests incl. real SDK client | released as v0.4.0 (version targets adapted) |

sqlguard_ninja-0.4.0/docs/development/NEXT_ACTIONS.md

@@ -0,0 +1,6 @@
+# Next actions (development program)
+
+1. Merge the v0.4.0 (MCP) PR, tag, release, verify PyPI and a fresh install including the `[mcp]` extra and a stdio session.
+2. Phase 4 (v0.5.0): make MySQL a tested dialect against a MySQL 8 service container in CI (#11); SQL Server and Oracle parser-level experimental only; publish a compatibility matrix.
+3. Phase 5: OpenTelemetry/Prometheus extras, SARIF output (#14), Grafana dashboard JSON.
+4. Phases 6-8: playground UI on the FastAPI backend, Docker/Kubernetes reference, public demo (hosting needs maintainer authorization).

{sqlguard_ninja-0.3.0 → sqlguard_ninja-0.4.0}/docs/development/TEST_EVIDENCE.md

@@ -10,3 +10,6 @@
 | 2026-10-24 | v0.2.0 publish | release.yml run 40108113801 | build + publish success; wheel and sdist with PEP 740 provenance; 0.1.0 and 0.1.1 unchanged |
 | 2026-10-24 | v0.2.0 fresh install | `pip install --no-cache-dir --index-url https://pypi.org/simple sqlguard-ninja==0.2.0` (Python 3.13, outside repo) | import from site-packages; lineage allow/deny and tenant push-down via CLI; bundled benchmark 1,044 evaluations with CSV, tiers, 14 file hashes |
 | 2026-10-24 | v0.3.0 candidate | full gate | 1,804 passed, 94%; build + twine PASSED; 3 templates in wheel |
+| 2026-10-24 | v0.3.0 release | PR #19 12/12; main CI on 198a308 success; release.yml run 40115952065 success | PyPI files with provenance |
+| 2026-10-24 | v0.3.0 fresh install | pip from PyPI, Python 3.13, outside repo (3rd attempt; CDN lag) | templates, policy check/explain (inheritance), tenant rewrite, decision metadata OK |
+| 2026-10-24 | v0.4.0 candidate (MCP) | tests/integration/test_mcp_server.py | 9 passed, including a real stdio ClientSession |

{sqlguard_ninja-0.3.0 → sqlguard_ninja-0.4.0}/docs/development/progress.json

@@ -38,21 +38,24 @@
     {
       "id": 3,
       "name": "Policy-as-code and multitenancy",
-      "status": "VERIFIED",
+      "status": "RELEASED",
       "release": "v0.3.0",
       "issues": [],
       "evidence": [
-        "inheritance, diff/simulate/explain/templates, tenant rewrite, audit metadata; 1,804 tests pass locally"
+        "inheritance, diff/simulate/explain/templates, tenant rewrite, audit metadata; 1,804 tests pass locally",
+        "v0.3.0 on PyPI; fresh install verified"
       ],
       "blockers": []
     },
     {
       "id": 4,
       "name": "MCP server",
-      "status": "NOT_STARTED",
-      "release": "v0.3.0",
+      "status": "VERIFIED",
+      "release": "v0.4.0",
       "issues": [],
-      "evidence": [],
+      "evidence": [
+        "stdio server; 9 tests incl. official SDK ClientSession"
+      ],
       "blockers": []
     },
     {

sqlguard_ninja-0.4.0/docs/guides/MCP_INTEGRATION.md

@@ -0,0 +1,77 @@
+# MCP integration
+
+SQLGuard Ninja ships a [Model Context Protocol](https://modelcontextprotocol.io/) server that
+lets MCP-compatible agents check SQL against your policy **before** they run it anywhere.
+
+```bash
+python -m pip install "sqlguard-ninja[mcp]"
+sqlninja mcp --policy policy.yaml --role support --tenant 42          # stdio transport
+```
+
+Built on the official MCP Python SDK (`mcp` 2.x, `MCPServer`). The bundled reference policy
+works out of the box: `--policy builtin:retail_saas --role support_analyst --tenant 1`.
+
+## Tools
+
+| Tool | Arguments | Returns |
+|---|---|---|
+| `validate_sql` | `sql`, optional `dialect` (`postgres` or `sqlite`) | `decision` (allow/review/deny), findings (rule id, action, message, remediation), `decision_id`, policy revision |
+| `explain_policy_decision` | `sql`, optional `dialect` | the decision plus per-finding lineage (base column, JSON path, labels) and how-to-fix hints |
+| `inspect_query_cost` | `sql`, optional `dialect` | static cost score, thresholds and factors (no execution plan, no database) |
+| `get_policy_capabilities` | — | the tables and columns this identity may use, their access mode (`allow`, `aggregate_only`, `review`), required tenant filter, limits, supported dialects |
+
+No tool accepts a role, a tenant, credentials or a connection string. The server has **no
+execution tool** and never connects to a database.
+
+## Security model
+
+* **Identity is server-side.** `--role` and `--tenant` are fixed when the server starts, by
+  whoever writes the client configuration. A model cannot choose its own permissions. Extra
+  arguments such as `role` are rejected or ignored, and the end-to-end test checks this.
+* **Least disclosure.** `get_policy_capabilities` lists only tables and columns the role may
+  use. Denied tables and columns are not revealed. Internal finding detail is never returned,
+  and with `disclosure: generic` lineage is omitted as well.
+* **Limits.** A hard cap of 100,000 characters applies before parsing, the policy's own length
+  and AST-size limits still apply, and a per-process rate limit (120 calls per minute by
+  default) is enforced. Errors are structured (`{"error": ..., "message": ...}`) and carry no
+  stack traces.
+* **Fail closed.** A tenant-scoped role started without `--tenant` gets every tenant-table
+  query denied.
+* The server is a validation service. Running the SQL remains your application's job, with a
+  least-privilege, read-only database role and row-level security.
+
+## Client configuration (stdio)
+
+Most MCP clients accept a JSON server definition of this shape. Adapt the command path to
+your environment:
+
+```json
+{
+  "mcpServers": {
+    "sqlguard-ninja": {
+      "command": "sqlninja",
+      "args": ["mcp", "--policy", "/absolute/path/policy.yaml", "--role", "support", "--tenant", "42"]
+    }
+  }
+}
+```
+
+One server process serves one identity. To give different users different permissions, start
+one server per identity from your trusted configuration. Never let the model write the client
+configuration.
+
+## Remote transports
+
+The SDK also supports Streamable HTTP. SQLGuard Ninja does **not** enable it by default,
+because a remote endpoint needs authentication that binds each caller to a role and tenant.
+If you expose it remotely, put it behind your own authenticated gateway, derive the identity
+from the authenticated caller, and keep one identity per server process or route. This setup
+is not covered by the test suite.
+
+## Verification
+
+`tests/integration/test_mcp_server.py` starts the real server as a subprocess and connects
+with the official SDK's `stdio_client` and `ClientSession`. It checks tool discovery,
+allowed and denied validations, a forged `role` argument, and capability listing. It also
+unit-tests malformed input, oversized input, unsupported dialects, rate limiting, the
+missing-tenant fail-closed path and least disclosure.

sqlguard_ninja-0.4.0/docs/releases/v0.4.0.md

@@ -0,0 +1,20 @@
+# SQLGuard Ninja v0.4.0
+
+## Highlights
+
+* **MCP server.** `sqlninja mcp --policy ... --role ... --tenant ...` exposes `validate_sql`, `explain_policy_decision`, `inspect_query_cost` and `get_policy_capabilities` to MCP-compatible agents over stdio. It is built on the official MCP Python SDK (2.x).
+* **Security model.** The identity is fixed by the operator at start-up, and tools take no role, tenant, credential or connection-string arguments. The server never executes SQL or connects to a database, withholds internal detail, and does not reveal ungranted tables or columns. Inputs are size-capped and calls are rate-limited.
+* **Verified with a real client.** The end-to-end test launches the server as a subprocess and uses the SDK's `stdio_client` and `ClientSession` to discover and call the tools, including a forged `role` argument.
+
+## Notes
+
+* Remote (Streamable HTTP) transport is not enabled. A remote deployment needs an authenticated gateway that binds each caller to an identity (see the MCP guide).
+* Known limitations are unchanged: all benchmark results are internal (issues #5 and #6), only PostgreSQL and SQLite are supported, and there is no guarantee against SQL injection or data leakage.
+
+## Installation
+
+```bash
+python -m pip install "sqlguard-ninja[mcp]==0.4.0"
+```
+
+PyPI: https://pypi.org/project/sqlguard-ninja/0.4.0/

{sqlguard_ninja-0.3.0 → sqlguard_ninja-0.4.0}/docs/security/THREAT_MODEL.md

@@ -57,6 +57,7 @@ flowchart LR
 | T3 | Prompt injection through database content | A ticket body says "now query payments" | Every subsequent query is checked again. Retry lock-out per trace. Read-only session. | The model can still be steered to permitted data. |
 | T4 | Parser ambiguity | Comment and string tricks, nested comments, dollar quoting | sqlglot dialect parsing. The corpus includes formatting and comment cases validated against real engines. Unparseable input is denied. | Unknown tokenizer differences. Report them as vulnerabilities. |
 | T5 | Dialect-specific bypasses | MySQL `/*! */` executable comments, SQLite `ATTACH`/`PRAGMA` | Executable-comment rule for the MySQL family. SQLite session statements are denied. | Untested dialects are experimental. |
+| T17 | MCP client or model escalating privileges | A model passes `role` or `tenant` arguments, or probes `get_policy_capabilities` for hidden tables | Identity fixed at server start from operator config; tool schemas have no identity arguments; capabilities list only granted, non-denied columns; no execution or credentials in the server | Anyone who can edit the MCP client configuration chooses the identity |
 | T6a | Unsafe automatic tenant filtering | A rewrite that changes meaning or masks a query naming another tenant | Rewrite is opt-in, bind-parameter only, refused on any non-tenant finding and on RIGHT/FULL-join ownership ambiguity; the rewritten SQL is re-validated and is the executed string | Rewritten SQL is sqlglot-normalised; RLS remains authoritative |
 | T6b | Silent policy relaxation through inheritance or edits | A child role or edit quietly widens access | Sticky explicit denies (load error on conflict); `policy diff --fail-on-relaxation`; fingerprint and revision in every decision | Reviewers must still read the diff |
 | T6 | Tenant data leakage | missing filter, `OR 1=1`, other tenant id, unpinned join or subquery | Every scope reading a tenant table must pin it with an equality conjunct to the context value or an approved bind parameter. `OR`/`NOT` don't count, and casts of the column don't count. | Apply RLS in the database as the authoritative control. |

{sqlguard_ninja-0.3.0 → sqlguard_ninja-0.4.0}/pyproject.toml

@@ -36,8 +36,10 @@ dependencies = [
 langchain = ["langchain-core>=0.3"]
 langgraph = ["langgraph>=0.2", "langchain-core>=0.3"]
 fastapi = ["fastapi>=0.110"]
+# Official MCP Python SDK; 2.x renamed FastMCP to MCPServer.
+mcp = ["mcp>=2.3,<3"]
 postgres = ["psycopg[binary]>=3.1"]
-all = ["sqlguard-ninja[langchain,langgraph,fastapi,postgres]"]
+all = ["sqlguard-ninja[langchain,langgraph,fastapi,postgres,mcp]"]
 dev = [
     "sqlguard-ninja[all]",
     "pytest>=8.0",
@@ -118,5 +120,5 @@ exclude = ["src/sqlguard_ninja/benchmarking/workers/"]
 plugins = ["pydantic.mypy"]
 
 [[tool.mypy.overrides]]
-module = ["langgraph.*", "langchain_core.*", "psycopg.*", "pgserver.*"]
+module = ["langgraph.*", "langchain_core.*", "psycopg.*", "pgserver.*", "mcp.*"]
 ignore_missing_imports = true

sqlguard_ninja-0.4.0/src/sqlguard_ninja/_version.py

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

{sqlguard_ninja-0.3.0 → sqlguard_ninja-0.4.0}/src/sqlguard_ninja/cli/main.py

@@ -273,6 +273,19 @@ def cmd_policy_explain(args: argparse.Namespace) -> int:
     return EXIT_OK
 
 
+def cmd_mcp(args: argparse.Namespace) -> int:  # pragma: no cover - blocks on stdio
+    try:
+        from sqlguard_ninja.mcp_server import ServerIdentity, serve  # noqa: PLC0415
+    except ImportError as exc:
+        raise CLIError('the MCP server needs: pip install "sqlguard-ninja[mcp]"') from exc
+    policy = _load_policy(args.policy)
+    try:
+        serve(policy, ServerIdentity(role=args.role, tenant=args.tenant), args.dialect)
+    except ValueError as exc:
+        raise CLIError(str(exc)) from exc
+    return EXIT_OK
+
+
 def cmd_init(args: argparse.Namespace) -> int:
     root = Path(args.directory)
     existing = [name for name in FILES if (root / name).exists()]
@@ -558,6 +571,13 @@ def build_parser() -> argparse.ArgumentParser:
     bb.add_argument("--i-understand-this-is-ci", action="store_true", help=argparse.SUPPRESS)
     bb.set_defaults(func=cmd_benchmark_baseline)
 
+    mcp = sub.add_parser("mcp", help="run the MCP server (stdio) for a fixed role and tenant")
+    mcp.add_argument("--policy", required=True, help="policy file or builtin:<name>")
+    mcp.add_argument("--role", required=True, help="trusted role for every request")
+    mcp.add_argument("--tenant", help="trusted tenant for every request")
+    mcp.add_argument("--dialect")
+    mcp.set_defaults(func=cmd_mcp)
+
     rep = sub.add_parser("report", help="reports").add_subparsers(dest="report_cmd", required=True)
     rg = rep.add_parser("generate", help="render a Markdown report from a result JSON")
     rg.add_argument("--result", required=True)

sqlguard_ninja-0.4.0/src/sqlguard_ninja/mcp_server.py

@@ -0,0 +1,287 @@
+"""Model Context Protocol (MCP) server exposing SQLGuard Ninja as a validation service.
+
+Security model:
+
+* **Identity is server-side.** The role and tenant are fixed when the server starts, from the
+  operator's configuration (for example an MCP client config). No tool accepts a role, a
+  tenant or an approval, so a model cannot choose its own permissions.
+* **No execution, no credentials.** The server never connects to a database. It has no
+  connection-string arguments and no filesystem tools. It only validates and explains SQL.
+* **Agent-safe output.** Tools return the agent-facing messages and remediations. Internal
+  detail is omitted, and lineage only names columns the role is allowed to know about.
+* **Resource limits.** A hard input-size cap applies before parsing, plus a per-process rate
+  limit.
+
+Run: ``sqlninja mcp --policy policy.yaml --role support --tenant 42`` (stdio transport).
+Requires ``pip install "sqlguard-ninja[mcp]"``.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass
+from typing import Any
+
+from sqlguard_ninja._version import __version__
+from sqlguard_ninja.core.analysis import SUPPORTED_DIALECTS, analyse
+from sqlguard_ninja.core.findings import ValidationResult
+from sqlguard_ninja.core.guard import Guard
+from sqlguard_ninja.policy.model import Access, Disclosure, Policy
+from sqlguard_ninja.privacy.rules import resolve_column_access
+from sqlguard_ninja.query_cost.static import analyse_static_cost
+
+HARD_MAX_SQL_CHARS = 100_000
+
+
+@dataclass(frozen=True)
+class ServerIdentity:
+    """Trusted request identity, configured by the operator, never by the model."""
+
+    role: str
+    tenant: str | None = None
+    principal: str = "mcp-client"
+
+
+class RateLimiter:
+    """Sliding-window limiter: at most ``limit`` calls per ``window_s`` seconds."""
+
+    def __init__(self, limit: int = 120, window_s: float = 60.0) -> None:
+        self.limit = limit
+        self.window_s = window_s
+        self._calls: deque[float] = deque()
+        self._lock = threading.Lock()
+
+    def allow(self) -> bool:
+        now = time.monotonic()
+        with self._lock:
+            while self._calls and now - self._calls[0] > self.window_s:
+                self._calls.popleft()
+            if len(self._calls) >= self.limit:
+                return False
+            self._calls.append(now)
+            return True
+
+
+class SQLGuardService:
+    """Transport-independent tool implementations (unit-testable without MCP)."""
+
+    def __init__(
+        self,
+        policy: Policy,
+        identity: ServerIdentity,
+        *,
+        dialect: str | None = None,
+        rate_limiter: RateLimiter | None = None,
+    ) -> None:
+        if policy.roles and policy.effective_role(identity.role) is None:
+            raise ValueError(f"role {identity.role!r} is not defined in the policy")
+        self.policy = policy
+        self.guard = Guard(policy)
+        self.identity = identity
+        self.dialect = (dialect or policy.dialect).lower()
+        self.rate_limiter = rate_limiter or RateLimiter()
+
+    # ------------------------------------------------------------------ helpers
+    def _context(self) -> dict[str, Any]:
+        if self.identity.tenant is None:
+            return {}
+        return {self.policy.tenant.context_key: self.identity.tenant}
+
+    def _precheck(self, sql: Any, dialect: str | None) -> tuple[str, str] | dict[str, Any]:
+        if not self.rate_limiter.allow():
+            return {"error": "rate_limited", "message": "Too many requests; try again shortly."}
+        if not isinstance(sql, str):
+            return {"error": "invalid_input", "message": "sql must be a string."}
+        if len(sql) > HARD_MAX_SQL_CHARS:
+            return {"error": "invalid_input", "message": "sql is too large."}
+        chosen = (dialect or self.dialect).lower()
+        if chosen not in SUPPORTED_DIALECTS:
+            return {
+                "error": "unsupported_dialect",
+                "message": f"Supported dialects: {', '.join(SUPPORTED_DIALECTS)}.",
+            }
+        return sql, chosen
+
+    def _validate(self, sql: str, dialect: str) -> ValidationResult:
+        return self.guard.validate(
+            sql, role=self.identity.role, dialect=dialect, context=self._context()
+        )
+
+    def _public_findings(
+        self, result: ValidationResult, with_lineage: bool
+    ) -> list[dict[str, Any]]:
+        out = []
+        generic = self.policy.disclosure == Disclosure.GENERIC
+        for f in result.findings:
+            item: dict[str, Any] = {
+                "rule_id": f.rule_id,
+                "action": f.action.value,
+                "category": f.category.value,
+                "message": f.message,
+            }
+            if f.remediation:
+                item["remediation"] = f.remediation
+            if with_lineage and not generic and f.metadata.get("lineage"):
+                lineage = f.metadata["lineage"]
+                item["lineage"] = {
+                    "base_column": lineage.get("base_column"),
+                    "json_path": lineage.get("json_path"),
+                    "labels": lineage.get("labels"),
+                }
+            out.append(item)
+        return out
+
+    # -------------------------------------------------------------------- tools
+    def validate_sql(self, sql: Any, dialect: str | None = None) -> dict[str, Any]:
+        checked = self._precheck(sql, dialect)
+        if isinstance(checked, dict):
+            return checked
+        result = self._validate(*checked)
+        return {
+            "decision": result.decision.value,
+            "allowed": result.allowed,
+            "findings": self._public_findings(result, with_lineage=False),
+            "decision_id": result.decision_id,
+            "policy_revision": result.policy_revision,
+            "note": "Validation only: this server never executes SQL. Database permissions "
+            "remain authoritative.",
+        }
+
+    def explain_policy_decision(self, sql: Any, dialect: str | None = None) -> dict[str, Any]:
+        checked = self._precheck(sql, dialect)
+        if isinstance(checked, dict):
+            return checked
+        result = self._validate(*checked)
+        return {
+            "decision": result.decision.value,
+            "decision_id": result.decision_id,
+            "role": self.identity.role,
+            "tenant_scoped": bool(self.identity.tenant),
+            "policy": {"name": result.policy_name, "revision": result.policy_revision},
+            "findings": self._public_findings(result, with_lineage=True),
+            "how_to_fix": [f.remediation for f in result.findings if f.remediation],
+        }
+
+    def inspect_query_cost(self, sql: Any, dialect: str | None = None) -> dict[str, Any]:
+        checked = self._precheck(sql, dialect)
+        if isinstance(checked, dict):
+            return checked
+        text, chosen = checked
+        limits = self.policy.effective_limits(self.policy.role(self.identity.role)[1])
+        analysis = analyse(text, chosen, self.policy.catalog, max_nodes=limits.max_ast_nodes)
+        if not analysis.ok or analysis.qualified is None:
+            return {"error": "unanalysable", "message": "The query could not be analysed."}
+        report = analyse_static_cost(analysis, self.policy)
+        return {
+            "static_score": report.score,
+            "review_threshold": self.policy.cost.review_score,
+            "deny_threshold": self.policy.cost.deny_score,
+            "factors": [
+                {"code": f.code, "points": f.points, "explanation": f.explanation}
+                for f in report.factors
+            ],
+            "note": "Static heuristic only; no execution plan is requested from any database.",
+        }
+
+    def get_policy_capabilities(self) -> dict[str, Any]:
+        """What this identity may query: permitted tables/columns and how they may be used."""
+        if not self.rate_limiter.allow():
+            return {"error": "rate_limited", "message": "Too many requests; try again shortly."}
+        role = self.policy.effective_role(self.identity.role) if self.policy.roles else None
+        tables: dict[str, Any] = {}
+        for tname, tdef in self.policy.catalog.tables.items():
+            grant = role.tables.get(tname) if role is not None else None
+            if role is not None and grant is None:
+                continue  # do not reveal tables the role cannot use
+            columns = {}
+            for cname in tdef.columns:
+                listed = grant is None or grant.columns == "*" or cname in grant.columns
+                if not listed or (grant is not None and cname in grant.deny_columns):
+                    continue
+                access = resolve_column_access(self.policy, role, tname, cname).strongest
+                if access is Access.DENY:
+                    continue
+                columns[cname] = access.value
+            needs_pin = bool(tdef.tenant_column) and (role is None or role.tenant_scoped)
+            tables[tname] = {
+                "columns": columns,
+                "tenant_filter_required": tdef.tenant_column if needs_pin else None,
+            }
+        limits = self.policy.effective_limits(role)
+        return {
+            "role": self.identity.role,
+            "policy": {"name": self.policy.name, "revision": self.policy.revision},
+            "dialects": list(SUPPORTED_DIALECTS),
+            "default_dialect": self.dialect,
+            "read_only": True,
+            "tenant_bind_parameter": self.policy.tenant.parameter_names[0]
+            if self.policy.tenant.parameter_names
+            else None,
+            "limits": {"max_limit": limits.max_limit, "max_joins": limits.max_joins},
+            "tables": tables,
+            "column_access_values": {
+                "allow": "may be selected and filtered",
+                "aggregate_only": "only inside COUNT/SUM/AVG-style aggregates",
+                "review": "requires human approval",
+            },
+        }
+
+
+def build_server(service: SQLGuardService) -> Any:
+    """Create the MCP server with the four tools bound to ``service``."""
+    from mcp.server.mcpserver import MCPServer  # noqa: PLC0415 - optional dependency
+
+    server = MCPServer(
+        name="sqlguard-ninja",
+        version=__version__,
+        instructions=(
+            "Validate SQL before running it. The server enforces a fixed role and tenant "
+            "chosen by the operator; you cannot change them. It never executes SQL."
+        ),
+    )
+
+    @server.tool(description="Validate one SQL statement against the configured policy.")
+    def validate_sql(sql: str, dialect: str | None = None) -> dict[str, Any]:
+        return service.validate_sql(sql, dialect)
+
+    @server.tool(description="Explain why a SQL statement is allowed, denied or needs review.")
+    def explain_policy_decision(sql: str, dialect: str | None = None) -> dict[str, Any]:
+        return service.explain_policy_decision(sql, dialect)
+
+    @server.tool(description="Estimate query cost risk with static heuristics (no execution).")
+    def inspect_query_cost(sql: str, dialect: str | None = None) -> dict[str, Any]:
+        return service.inspect_query_cost(sql, dialect)
+
+    @server.tool(description="List the tables, columns and rules available to this identity.")
+    def get_policy_capabilities() -> dict[str, Any]:
+        return service.get_policy_capabilities()
+
+    return server
+
+
+def serve(
+    policy: Policy, identity: ServerIdentity, dialect: str | None = None
+) -> None:  # pragma: no cover - exercised through the stdio integration test
+    build_server(SQLGuardService(policy, identity, dialect=dialect)).run("stdio")
+
+
+def main(argv: list[str] | None = None) -> int:  # pragma: no cover - thin CLI wrapper
+    import argparse  # noqa: PLC0415
+
+    from sqlguard_ninja.benchmarking.builtin import resolve  # noqa: PLC0415
+
+    p = argparse.ArgumentParser(prog="sqlguard-ninja-mcp")
+    p.add_argument("--policy", required=True)
+    p.add_argument("--role", required=True)
+    p.add_argument("--tenant")
+    p.add_argument("--dialect")
+    args = p.parse_args(argv)
+    policy = Policy.from_file(resolve(args.policy, "policy"))
+    serve(policy, ServerIdentity(role=args.role, tenant=args.tenant), args.dialect)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())