dataforge-07-mcp 0.1.0__py3-none-any.whl

dataforge_07_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: dataforge_07_mcp
+Version: 0.1.0
+Summary: Model Context Protocol server for DataForge data-quality tools.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Aegis15/dataforge
+Project-URL: Repository, https://github.com/Aegis15/dataforge
+Project-URL: Documentation, https://dataforge.praneshrajan15.workers.dev/playground
+Keywords: data-quality,dataforge,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: dataforge_07<0.2,>=0.1.0
+Requires-Dist: mcp>=1.27
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+
+# dataforge-mcp
+
+`dataforge-mcp` exposes DataForge's shipped CSV profiling, detection, repair,
+verification, and transaction-revert paths as Model Context Protocol tools.
+
+```bash
+cd dataforge-mcp
+python -m pip install -e ".[dev]"
+dataforge-mcp serve --allowed-root /path/to/csv/workspace
+```
+
+For local development from this repository:
+
+```bash
+cd dataforge-mcp
+python -m pip install -e ".[dev]"
+dataforge-mcp serve --allowed-root ..
+```
+
+The default transport is stdio, which is what local desktop MCP clients expect.
+For local Streamable HTTP experiments:
+
+```bash
+dataforge-mcp serve --transport streamable-http --host 127.0.0.1 --port 8000
+```
+
+`dry_run` is the safe default. To allow file mutation through MCP, start the
+server with an explicit allowed root and `--enable-apply`:
+
+```bash
+dataforge-mcp serve --allowed-root /path/to/csv/workspace --enable-apply
+```
+
+## Tools
+
+- `dataforge_profile(path: str)` - summarize CSV shape plus detected issues.
+- `dataforge_detect_errors(path: str)` - return detected issues only.
+- `dataforge_verify_fix(fix_spec: dict)` - run one candidate fix through stale
+  value checks, safety, and verification.
+- `dataforge_apply_repairs(path: str, mode: "dry_run" | "apply")` - propose
+  verified repairs and optionally write a reversible transaction.
+- `dataforge_revert(txn_id: str)` - restore a transaction's original bytes.
+
+## Client Configuration
+
+Use the same server command for Claude Desktop, Cursor, Windsurf, or any local
+MCP client that supports stdio servers:
+
+```json
+{
+  "mcpServers": {
+    "dataforge": {
+      "command": "dataforge-mcp",
+      "args": ["serve", "--allowed-root", "/path/to/csv/workspace"]
+    }
+  }
+}
+```
+
+If your client cannot resolve the console script, replace `command` with the
+absolute path returned by your shell:
+
+```bash
+which dataforge-mcp
+```
+
+On Windows PowerShell:
+
+```powershell
+Get-Command dataforge-mcp
+```
+
+Before describing a build as agent-ready, run an MCP Inspector smoke check
+against a fixture directory and confirm the profile, detect, verify, dry-run
+apply, and disabled-apply paths:
+
+```bash
+npx @modelcontextprotocol/inspector dataforge-mcp serve --allowed-root /path/to/csv/workspace
+```
+
+## Safety Model
+
+`apply` mode uses DataForge's detector -> repairer -> SafetyFilter ->
+SMTVerifier -> transaction-log path. The tool writes the transaction journal and
+source snapshot before mutating the CSV, and `dataforge_revert` restores the
+snapshot only when the current file still matches the recorded post-state hash.
+
+The MCP server does not enable live LLM repair fallback by default. It does not
+send CSV contents to any external model provider. It also rejects CSV and schema
+paths outside the configured allowed roots, and `apply` mode is disabled unless
+the server is started with `--enable-apply` or `DATAFORGE_MCP_ENABLE_APPLY=1`.
+
+## Release
+
+The package is intended to release independently from the nested
+`dataforge-mcp/` source directory as the `dataforge_07_mcp` distribution, but
+it is not published yet. After PyPI Trusted Publishing is configured, the
+workflow will build on tags matching:
+
+```text
+dataforge-mcp-v*
+```
+
+The package depends on `dataforge_07` and the official Python `mcp` SDK; it does
+not vendor DataForge or add MCP dependencies to the core package.

dataforge_07_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+dataforge_mcp/__init__.py,sha256=xrA7h1skAaR7PfGWfTJNg2m55Oo-SBodhePb0Sk7T20,122
+dataforge_mcp/server.py,sha256=9UYf_gpY-vgvnnBrdnS9K8VNYI4TgOm4aeWjdaYdgN0,3281
+dataforge_mcp/tools.py,sha256=dHDLtOf3dfNSKhCbdqQ3yrSKpWs8faUD2u0YZ1ilpAY,13099
+dataforge_07_mcp-0.1.0.dist-info/METADATA,sha256=DEQqzsdS9h-E5jS9L9uLRtV61B2NqFmS2_NtrQqzrG0,4062
+dataforge_07_mcp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+dataforge_07_mcp-0.1.0.dist-info/entry_points.txt,sha256=xO8EZXxkmDLk_tN9W466LImLzqzwRZctLlADJjXIco4,104
+dataforge_07_mcp-0.1.0.dist-info/top_level.txt,sha256=Vz7dtKc20dZhoqKzpFhVlHdcnpIUOccjEq720DroSlM,14
+dataforge_07_mcp-0.1.0.dist-info/RECORD,,

dataforge_07_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dataforge_07_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+dataforge-mcp = dataforge_mcp.server:main
+dataforge15-mcp = dataforge_mcp.server:main

dataforge_07_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dataforge_mcp

dataforge_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""DataForge MCP server package."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

dataforge_mcp/server.py

@@ -0,0 +1,104 @@
+"""Executable MCP server for DataForge."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Literal
+
+from mcp.server.fastmcp import FastMCP
+
+from dataforge_mcp.tools import (
+    configure_mcp_security,
+    dataforge_apply_repairs,
+    dataforge_detect_errors,
+    dataforge_profile,
+    dataforge_revert,
+    dataforge_verify_fix,
+)
+
+TransportLiteral = Literal["stdio", "streamable-http"]
+
+
+def create_server(*, host: str = "127.0.0.1", port: int = 8000) -> FastMCP:
+    """Create a FastMCP server with all DataForge tools registered."""
+    mcp = FastMCP(
+        "DataForge",
+        instructions=(
+            "DataForge profiles CSVs, detects data-quality issues, proposes "
+            "verified repairs, applies reversible transactions, and reverts them."
+        ),
+        host=host,
+        port=port,
+        stateless_http=True,
+        json_response=True,
+    )
+    mcp.tool(name="dataforge_profile")(dataforge_profile)
+    mcp.tool(name="dataforge_detect_errors")(dataforge_detect_errors)
+    mcp.tool(name="dataforge_verify_fix")(dataforge_verify_fix)
+    mcp.tool(name="dataforge_apply_repairs")(dataforge_apply_repairs)
+    mcp.tool(name="dataforge_revert")(dataforge_revert)
+    return mcp
+
+
+def serve(
+    *,
+    transport: TransportLiteral = "stdio",
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    enable_apply: bool = False,
+    allowed_roots: list[str] | None = None,
+) -> None:
+    """Run the DataForge MCP server."""
+    configure_mcp_security(enable_apply=enable_apply, allowed_roots=allowed_roots)
+    server = create_server(host=host, port=port)
+    server.run(transport=transport)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the command-line parser for the console script."""
+    parser = argparse.ArgumentParser(prog="dataforge-mcp")
+    subparsers = parser.add_subparsers(dest="command")
+    serve_parser = subparsers.add_parser("serve", help="Start the MCP server.")
+    serve_parser.add_argument(
+        "--transport",
+        choices=("stdio", "streamable-http"),
+        default="stdio",
+        help="MCP transport to use.",
+    )
+    serve_parser.add_argument("--host", default="127.0.0.1", help="HTTP host.")
+    serve_parser.add_argument("--port", default=8000, type=int, help="HTTP port.")
+    serve_parser.add_argument(
+        "--enable-apply",
+        action="store_true",
+        help="Allow MCP clients to mutate CSV files through reversible transactions.",
+    )
+    serve_parser.add_argument(
+        "--allowed-root",
+        action="append",
+        dest="allowed_roots",
+        help="Filesystem root that MCP tools may read or mutate. May be repeated.",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Console entry point for ``dataforge-mcp``."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        raise SystemExit(0)
+    if args.command == "serve":
+        serve(
+            transport=args.transport,
+            host=args.host,
+            port=args.port,
+            enable_apply=args.enable_apply,
+            allowed_roots=args.allowed_roots,
+        )
+        return
+    parser.error(f"Unknown command: {args.command}")
+
+
+if __name__ == "__main__":
+    main()

dataforge_mcp/tools.py

@@ -0,0 +1,396 @@
+"""Structured MCP tool functions backed by DataForge's public API."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from dataforge import (
+    CONTRACT_VERSION,
+    CellFix,
+    Issue,
+    ProposedFix,
+    RepairPipelineRequest,
+    SafetyContext,
+    SafetyFilter,
+    SafetyVerdict,
+    Schema,
+    SMTVerifier,
+    TransactionLogError,
+    VerificationVerdict,
+    VerifiedFix,
+    load_schema,
+    read_csv,
+    revert_transaction,
+    run_all_detectors,
+    run_repair_pipeline,
+)
+
+_APPLY_ENABLED = False
+_ALLOWED_ROOTS: tuple[Path, ...] | None = None
+
+
+class IssueResult(BaseModel):
+    """MCP-safe representation of a DataForge issue."""
+
+    row: int
+    column: str
+    issue_type: str
+    severity: str
+    confidence: float
+    expected: str | None
+    actual: str
+    reason: str
+
+
+class FixResult(BaseModel):
+    """MCP-safe representation of an accepted repair proposal."""
+
+    row: int
+    column: str
+    old_value: str
+    new_value: str
+    detector_id: str
+    operation: str
+    reason: str
+    confidence: float
+    provenance: str
+
+
+class ProfileResult(BaseModel):
+    """Structured result returned by the profile tool."""
+
+    path: str
+    rows: int
+    columns: int
+    column_names: list[str]
+    total_issues: int
+    issues: list[IssueResult]
+
+
+class VerifyFixResult(BaseModel):
+    """Structured result returned by the fix verifier tool."""
+
+    accept: bool
+    reason: str
+    safety_verdict: str | None = None
+    verifier_verdict: str | None = None
+    unsat_core: list[str] = Field(default_factory=list)
+
+
+class TxnReceipt(BaseModel):
+    """Structured receipt returned by the repair tool."""
+
+    path: str
+    schema_version: Literal["repair_receipt_v1"] = "repair_receipt_v1"
+    receipt_version: Literal["repair_receipt_v1"] = "repair_receipt_v1"
+    mode: Literal["dry_run", "apply"]
+    contract_version: str = CONTRACT_VERSION
+    applied: bool
+    txn_id: str | None
+    reversible: bool
+    source_sha256: str
+    post_sha256: str | None = None
+    safety_verdict: str
+    verifier_verdict: str
+    patch_plan_sha256: str | None = None
+    revert_command: str | None = None
+    allowed_columns: list[str]
+    valid_rows: list[int]
+    root_causes: list[dict[str, Any]] = Field(default_factory=list)
+    candidate_repairs: list[dict[str, Any]] = Field(default_factory=list)
+    proof_obligations: list[dict[str, Any]] = Field(default_factory=list)
+    limitations: list[str] = Field(default_factory=list)
+    issues_count: int
+    fixes_count: int
+    reason: str
+    fixes: list[FixResult]
+
+
+class RevertReceipt(BaseModel):
+    """Structured receipt returned by the revert tool."""
+
+    txn_id: str
+    source_path: str
+    restored: bool
+    reverted_at: str | None
+    reason: str
+
+
+def configure_mcp_security(
+    *,
+    enable_apply: bool = False,
+    allowed_roots: Sequence[str | Path] | None = None,
+) -> None:
+    """Configure process-wide MCP path and apply safety settings."""
+    global _APPLY_ENABLED, _ALLOWED_ROOTS
+    _APPLY_ENABLED = enable_apply
+    if allowed_roots is None:
+        _ALLOWED_ROOTS = None
+        return
+    _ALLOWED_ROOTS = tuple(Path(root).expanduser().resolve() for root in allowed_roots)
+
+
+def _env_flag_enabled(name: str) -> bool:
+    """Return whether an environment flag is truthy."""
+    return os.environ.get(name, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _apply_is_enabled() -> bool:
+    """Return whether MCP apply mode is explicitly enabled."""
+    return _APPLY_ENABLED or _env_flag_enabled("DATAFORGE_MCP_ENABLE_APPLY")
+
+
+def _allowed_roots() -> tuple[Path, ...]:
+    """Return configured allowed filesystem roots for MCP file access."""
+    raw_roots = os.environ.get("DATAFORGE_MCP_ALLOWED_ROOTS", "")
+    if raw_roots.strip():
+        return tuple(
+            Path(root).expanduser().resolve()
+            for root in raw_roots.split(os.pathsep)
+            if root.strip()
+        )
+    if _ALLOWED_ROOTS is not None:
+        return _ALLOWED_ROOTS
+    return (Path.cwd().resolve(),)
+
+
+def _ensure_under_allowed_root(path: Path) -> Path:
+    """Reject paths outside the configured MCP allowlist."""
+    resolved = path.expanduser().resolve()
+    roots = _allowed_roots()
+    if not roots:
+        raise ValueError("At least one MCP allowed root must be configured.")
+    for root in roots:
+        if resolved == root or resolved.is_relative_to(root):
+            return resolved
+    allowed = ", ".join(str(root) for root in roots)
+    raise ValueError(
+        f"Path is outside configured MCP allowed roots: {resolved}. Allowed: {allowed}"
+    )
+
+
+def _resolve_csv_path(path: str) -> Path:
+    """Resolve and validate a CSV path supplied by an MCP client."""
+    resolved = _ensure_under_allowed_root(Path(path))
+    if not resolved.exists():
+        raise ValueError(f"CSV file does not exist: {resolved}")
+    if not resolved.is_file():
+        raise ValueError(f"CSV path is not a file: {resolved}")
+    return resolved
+
+
+def _load_optional_schema(raw_path: object) -> Schema | None:
+    """Load an optional schema path from an untrusted payload."""
+    if raw_path is None:
+        return None
+    schema_path = _ensure_under_allowed_root(Path(str(raw_path)))
+    if not schema_path.exists():
+        raise ValueError(f"Schema file does not exist: {schema_path}")
+    return load_schema(schema_path)
+
+
+def _issue_to_result(issue: Issue) -> IssueResult:
+    """Convert a DataForge issue into a stable MCP payload."""
+    return IssueResult(
+        row=issue.row,
+        column=issue.column,
+        issue_type=issue.issue_type,
+        severity=issue.severity.value,
+        confidence=issue.confidence,
+        expected=issue.expected,
+        actual=issue.actual,
+        reason=issue.reason,
+    )
+
+
+def _fix_to_result(proposed_fix: ProposedFix) -> FixResult:
+    """Convert a proposed fix into a stable MCP payload."""
+    fix = proposed_fix.fix
+    return FixResult(
+        row=fix.row,
+        column=fix.column,
+        old_value=fix.old_value,
+        new_value=fix.new_value,
+        detector_id=fix.detector_id,
+        operation=fix.operation,
+        reason=proposed_fix.reason,
+        confidence=proposed_fix.confidence,
+        provenance=proposed_fix.provenance,
+    )
+
+
+def _verified_fix_to_result(verified_fix: VerifiedFix) -> FixResult:
+    """Convert a public engine verified fix into a stable MCP payload."""
+    return FixResult(
+        row=verified_fix.row,
+        column=verified_fix.column,
+        old_value=verified_fix.old_value,
+        new_value=verified_fix.new_value,
+        detector_id=verified_fix.detector_id,
+        operation=verified_fix.operation,
+        reason=verified_fix.reason,
+        confidence=verified_fix.confidence,
+        provenance=verified_fix.provenance,
+    )
+
+
+def _run_detection(path: Path, schema: Schema | None = None) -> tuple[Any, list[Issue]]:
+    """Read a CSV and run all DataForge detectors."""
+    df = read_csv(path)
+    return df, run_all_detectors(df, schema)
+
+
+def _proposed_fix_from_spec(fix_spec: dict[str, Any]) -> tuple[Path, Schema | None, ProposedFix]:
+    """Parse a verifier payload into a CSV path, optional schema, and fix."""
+    raw_path = fix_spec.get("path")
+    if not raw_path:
+        raise ValueError("fix_spec must include a CSV 'path'.")
+    path = _resolve_csv_path(str(raw_path))
+    schema = _load_optional_schema(fix_spec.get("schema_path"))
+    raw_fix = fix_spec.get("fix")
+    if not isinstance(raw_fix, dict):
+        raw_fix = {
+            key: value
+            for key, value in fix_spec.items()
+            if key in {"row", "column", "old_value", "new_value", "detector_id", "operation"}
+        }
+    cell_fix = CellFix.model_validate(raw_fix)
+    proposed = ProposedFix(
+        fix=cell_fix,
+        reason=str(fix_spec.get("reason", "MCP-provided candidate fix.")),
+        confidence=float(fix_spec.get("confidence", 1.0)),
+        provenance=fix_spec.get("provenance", "deterministic"),
+    )
+    return path, schema, proposed
+
+
+def dataforge_profile(path: str) -> ProfileResult:
+    """Profile a CSV file and return detected DataForge issues."""
+    csv_path = _resolve_csv_path(path)
+    df, issues = _run_detection(csv_path)
+    return ProfileResult(
+        path=str(csv_path),
+        rows=len(df.index),
+        columns=len(df.columns),
+        column_names=[str(column) for column in df.columns],
+        total_issues=len(issues),
+        issues=[_issue_to_result(issue) for issue in issues],
+    )
+
+
+def dataforge_detect_errors(path: str) -> list[IssueResult]:
+    """Detect data-quality errors in a CSV file."""
+    csv_path = _resolve_csv_path(path)
+    _df, issues = _run_detection(csv_path)
+    return [_issue_to_result(issue) for issue in issues]
+
+
+def dataforge_verify_fix(fix_spec: dict[str, Any]) -> VerifyFixResult:
+    """Verify whether one candidate fix may be accepted by DataForge gates."""
+    path, schema, proposed = _proposed_fix_from_spec(fix_spec)
+    df = read_csv(path)
+    fix = proposed.fix
+    if fix.column not in df.columns:
+        return VerifyFixResult(accept=False, reason=f"Column '{fix.column}' does not exist.")
+    if fix.row < 0 or fix.row >= len(df.index):
+        return VerifyFixResult(accept=False, reason=f"Row {fix.row} is out of bounds.")
+    current_value = str(df.at[fix.row, fix.column])
+    if current_value != fix.old_value:
+        return VerifyFixResult(
+            accept=False,
+            reason=(
+                f"Refusing stale fix for row {fix.row}, column '{fix.column}': "
+                f"expected '{fix.old_value}', found '{current_value}'."
+            ),
+        )
+
+    safety_result = SafetyFilter().evaluate(proposed, schema, SafetyContext())
+    if safety_result.verdict != SafetyVerdict.ALLOW:
+        return VerifyFixResult(
+            accept=False,
+            reason=safety_result.reason,
+            safety_verdict=safety_result.verdict.value,
+        )
+
+    verifier_result = SMTVerifier().verify(df, [proposed], schema)
+    return VerifyFixResult(
+        accept=verifier_result.verdict == VerificationVerdict.ACCEPT,
+        reason=verifier_result.reason,
+        safety_verdict=safety_result.verdict.value,
+        verifier_verdict=verifier_result.verdict.value,
+        unsat_core=list(verifier_result.unsat_core),
+    )
+
+
+def dataforge_apply_repairs(path: str, mode: Literal["dry_run", "apply"]) -> TxnReceipt:
+    """Detect, verify, and optionally apply DataForge repairs to a CSV file."""
+    csv_path = _resolve_csv_path(path)
+    if mode not in {"dry_run", "apply"}:
+        raise ValueError("mode must be 'dry_run' or 'apply'.")
+    if mode == "apply" and not _apply_is_enabled():
+        raise ValueError(
+            "MCP apply mode is disabled. Start the server with --enable-apply or set "
+            "DATAFORGE_MCP_ENABLE_APPLY=1."
+        )
+
+    result = run_repair_pipeline(
+        RepairPipelineRequest(
+            source_path=csv_path,
+            mode=mode,
+            schema=None,
+            allow_llm=False,
+        )
+    )
+    receipt = result.receipt
+    return TxnReceipt(
+        path=str(csv_path),
+        mode=mode,
+        applied=receipt.applied,
+        txn_id=receipt.txn_id,
+        reversible=receipt.reversible,
+        source_sha256=receipt.source_sha256,
+        post_sha256=receipt.post_sha256,
+        safety_verdict=receipt.safety_verdict,
+        verifier_verdict=receipt.verifier_verdict,
+        patch_plan_sha256=receipt.patch_plan_sha256,
+        revert_command=receipt.revert_command,
+        allowed_columns=receipt.allowed_columns,
+        valid_rows=receipt.valid_rows,
+        root_causes=[item.model_dump() for item in receipt.root_causes],
+        candidate_repairs=[item.model_dump() for item in receipt.candidate_repairs],
+        proof_obligations=[item.model_dump() for item in receipt.proof_obligations],
+        limitations=receipt.limitations,
+        issues_count=receipt.issues_count,
+        fixes_count=receipt.fixes_count,
+        reason=receipt.reason,
+        fixes=[_verified_fix_to_result(fix) for fix in result.fixes],
+    )
+
+
+def dataforge_revert(txn_id: str) -> RevertReceipt:
+    """Revert a previously applied DataForge repair transaction."""
+    transaction = None
+    last_error: Exception | None = None
+    for root in _allowed_roots():
+        try:
+            transaction = revert_transaction(txn_id, search_root=root)
+            break
+        except TransactionLogError as exc:
+            last_error = exc
+            continue
+    if transaction is None:
+        if last_error is not None:
+            raise ValueError(str(last_error)) from last_error
+        raise ValueError(f"Could not find transaction '{txn_id}' under configured allowed roots.")
+    return RevertReceipt(
+        txn_id=transaction.txn_id,
+        source_path=transaction.source_path,
+        restored=transaction.reverted_at is not None,
+        reverted_at=transaction.reverted_at.isoformat() if transaction.reverted_at else None,
+        reason="Source restored successfully.",
+    )