mcp-validation-server 0.1.0__py3-none-any.whl

mcp_validation_server/__init__.py

@@ -0,0 +1,85 @@
+"""mcp-validation-server — deterministic data-validation tools over MCP.
+
+A Model Context Protocol server that exposes four checks a model cannot argue
+with: contract validation with quarantine, arithmetic reconciliation, distinct
+entity counting, and duplicate reporting for human review.
+
+The design rule: **a validation failure is a result, not an exception.** Every
+tool returns structured findings with stable codes and row/column locators, so a
+calling model can report what failed and recover. Only malformed tool arguments
+raise.
+
+The tool functions are importable and callable directly, which is how the unit
+tests exercise them without an MCP client:
+
+    >>> from mcp_validation_server import validate_rows
+    >>> result = validate_rows([{"amount": "-5"}], [{"name": "amount", "type": "number", "min": 0}])
+    >>> result["ok"], result["summary"]["quarantined"]
+    (False, 1)
+"""
+
+from __future__ import annotations
+
+from .app import SERVER_NAME, SERVER_VERSION, mcp
+from .contract import (
+    ColumnSpecError,
+    Field,
+    Max,
+    Min,
+    NotBlank,
+    OneOf,
+    Pattern,
+    Range,
+    RowContract,
+    Rule,
+    ValidationOutcome,
+    parse_columns,
+)
+from .entities import (
+    DistinctOutcome,
+    DuplicateGroup,
+    DuplicateOutcome,
+    count_distinct_rows,
+    find_duplicate_groups,
+    normalise_key,
+)
+from .findings import Finding, Locator, envelope
+from .reconcile import Movement, ReconcileOutcome, reconcile_arithmetic
+from .tools import count_distinct, duplicate_report, reconcile, validate_rows
+
+__version__ = SERVER_VERSION
+
+__all__ = [
+    "ColumnSpecError",
+    "DistinctOutcome",
+    "DuplicateGroup",
+    "DuplicateOutcome",
+    "Field",
+    "Finding",
+    "Locator",
+    "Max",
+    "Min",
+    "Movement",
+    "NotBlank",
+    "OneOf",
+    "Pattern",
+    "Range",
+    "ReconcileOutcome",
+    "RowContract",
+    "Rule",
+    "SERVER_NAME",
+    "SERVER_VERSION",
+    "ValidationOutcome",
+    "__version__",
+    "count_distinct",
+    "count_distinct_rows",
+    "duplicate_report",
+    "envelope",
+    "find_duplicate_groups",
+    "mcp",
+    "normalise_key",
+    "parse_columns",
+    "reconcile",
+    "reconcile_arithmetic",
+    "validate_rows",
+]

mcp_validation_server/__main__.py

@@ -0,0 +1,8 @@
+"""Run the server with ``python3 -m mcp_validation_server``."""
+
+from __future__ import annotations
+
+from .server import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mcp_validation_server/app.py

@@ -0,0 +1,39 @@
+"""The server instance.
+
+Kept in its own module so that :mod:`mcp_validation_server.tools` can import it
+and register tools with the ``@mcp.tool()`` decorator without a circular import.
+"""
+
+from __future__ import annotations
+
+from mcp.server.mcpserver import MCPServer
+
+SERVER_NAME = "mcp-validation-server"
+SERVER_VERSION = "0.1.0"
+
+INSTRUCTIONS = """\
+Deterministic data-validation tools. Use these when a claim about a dataset needs
+to be checked rather than asserted: to validate rows against a column contract, to
+confirm that a period of arithmetic closes, to count distinct entities rather than
+rows, or to surface suspected duplicates for review.
+
+Every tool returns a JSON result with the same envelope: `ok`, `verdict`,
+`findings`, and `guidance`. A validation failure is a RESULT, not an error. When a
+tool returns `ok: false` the call succeeded — the data failed. Read the `findings`
+array, which gives a stable `code`, a human-readable `message`, and a `locator`
+naming the exact row (and column) for each problem. The `guidance` field says what
+to do next.
+
+Nothing here drops, merges, repairs, or overwrites data. Rows that fail are
+quarantined and reported; suspected duplicates are returned for a human to decide.
+Do not describe a dataset as validated unless the tool returned `ok: true`.
+"""
+
+mcp = MCPServer(
+    name=SERVER_NAME,
+    title="Data Validation",
+    version=SERVER_VERSION,
+    instructions=INSTRUCTIONS,
+)
+
+__all__ = ["INSTRUCTIONS", "SERVER_NAME", "SERVER_VERSION", "mcp"]