mcp-claimcheck 0.1.0a1__tar.gz

mcp_claimcheck-0.1.0a1/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Environments
+.venv/
+venv/
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Runtime output (later phases write traces and baselines; never commit real data)
+*.jsonl
+.mcp-claimcheck/

mcp_claimcheck-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roydon Sequeira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_claimcheck-0.1.0a1/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: mcp-claimcheck
+Version: 0.1.0a1
+Summary: Pre-alpha: runtime semantic verification for MCP tool calls. It will check whether a tool actually satisfied the operation it reported as successful.
+Author: Roydon Sequeira
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,contracts,mcp,model-context-protocol,verification
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# mcp-claimcheck
+
+> **Status: pre-alpha, under construction.** Phases 1 to 3 of 15 are done:
+>
+> - a transparent passthrough proxy (`mcp-claimcheck run -- <server command>`) that
+>   forwards MCP traffic unchanged;
+> - which reads each tool result and logs what it saw (`--log-level info`);
+> - and contracts, which can now be written and validated (`mcp-claimcheck check`).
+>   The format is described in `docs/CONTRACTS.md` in the source repository, which is
+>   not public yet.
+>
+> **Nothing is verified against a contract yet**: contracts are read and checked for
+> being well formed, and no tool call is judged against one. The rest of this README
+> describes the goal, not current behaviour.
+
+Your agent called the tool.
+The tool returned success.
+Did the operation actually succeed?
+
+`mcp-claimcheck` is a runtime semantic verification layer for MCP tool calls. It
+will sit between an MCP client and an upstream MCP server, check each `tools/call`
+result against declared contracts and built-in heuristics, and report when a
+result does not satisfy the operation it claims to have completed.
+
+## What it will not do
+
+- **It cannot block execution.** It inspects responses, so by the time it sees a
+  result the upstream tool has already run. What it can do is stop the agent
+  from reporting a success that did not happen.
+- **It cannot see inside MCP servers.** It only sees MCP JSON-RPC traffic. If a
+  server hides a backend failure and returns an empty result, that empty result
+  is reported as unverifiable, not as a failure.
+
+## License
+
+MIT. The full text ships with the package as `LICENSE`.

mcp_claimcheck-0.1.0a1/README.md

@@ -0,0 +1,36 @@
+# mcp-claimcheck
+
+> **Status: pre-alpha, under construction.** Phases 1 to 3 of 15 are done:
+>
+> - a transparent passthrough proxy (`mcp-claimcheck run -- <server command>`) that
+>   forwards MCP traffic unchanged;
+> - which reads each tool result and logs what it saw (`--log-level info`);
+> - and contracts, which can now be written and validated (`mcp-claimcheck check`).
+>   The format is described in `docs/CONTRACTS.md` in the source repository, which is
+>   not public yet.
+>
+> **Nothing is verified against a contract yet**: contracts are read and checked for
+> being well formed, and no tool call is judged against one. The rest of this README
+> describes the goal, not current behaviour.
+
+Your agent called the tool.
+The tool returned success.
+Did the operation actually succeed?
+
+`mcp-claimcheck` is a runtime semantic verification layer for MCP tool calls. It
+will sit between an MCP client and an upstream MCP server, check each `tools/call`
+result against declared contracts and built-in heuristics, and report when a
+result does not satisfy the operation it claims to have completed.
+
+## What it will not do
+
+- **It cannot block execution.** It inspects responses, so by the time it sees a
+  result the upstream tool has already run. What it can do is stop the agent
+  from reporting a success that did not happen.
+- **It cannot see inside MCP servers.** It only sees MCP JSON-RPC traffic. If a
+  server hides a backend failure and returns an empty result, that empty result
+  is reported as unverifiable, not as a failure.
+
+## License
+
+MIT. The full text ships with the package as `LICENSE`.

mcp_claimcheck-0.1.0a1/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+# 1.27 is the first release whose default core metadata is 2.4, the version that
+# carries PEP 639 License-Expression and License-File (hatchling changelog, 1.27.0).
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-claimcheck"
+dynamic = ["version"]
+description = "Pre-alpha: runtime semantic verification for MCP tool calls. It will check whether a tool actually satisfied the operation it reported as successful."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Roydon Sequeira" }]
+keywords = ["mcp", "model-context-protocol", "verification", "contracts", "ai-agents"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+# Every dependency is install friction. Add one only in the phase that needs it.
+dependencies = [
+    "click>=8.1", # Phase 0: the command line
+    # Phase 3: contracts are YAML (DECISIONS D-013). The standard library has no YAML
+    # parser, and `compose` gives the line and column numbers that contract errors must
+    # name. Only `safe_load`/`compose` are ever used: never `load`, which can construct
+    # arbitrary Python objects.
+    "pyyaml>=6.0",
+    # Phase 3: meta-validating a contract's JSON Schema (`check_schema`). Phase 4
+    # validates payloads against those schemas with the same library, so the dialect
+    # a contract is checked against is the dialect it is later enforced with.
+    "jsonschema>=4.21",
+]
+
+[project.scripts]
+mcp-claimcheck = "mcp_claimcheck.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    # A hung test must fail, not stall CI: hangs are the bug class a proxy is prone to.
+    "pytest-timeout>=2.3",
+    "ruff>=0.13",
+    "mypy>=1.18",
+    "mcp==2.2.0",
+    # Type stubs only, so they stay out of the installed package. Phase 3.
+    "types-PyYAML>=6.0",
+    "types-jsonschema>=4.21",
+]
+
+[tool.hatch.version]
+path = "src/mcp_claimcheck/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_claimcheck"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "LICENSE", "README.md", "pyproject.toml"]
+
+# ---------------------------------------------------------------- ruff
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W",   # pycodestyle
+    "F",        # pyflakes
+    "I",        # isort
+    "B",        # bugbear
+    "UP",       # pyupgrade
+    "SIM",      # simplify
+    "RUF",      # ruff-specific
+    "T10",      # debugger calls (pdb writes to stdout)
+    "T20",      # Rule 5: print / pprint
+    "S102",     # Rule 3: exec
+    "S307",     # Rule 3: eval
+]
+
+[tool.ruff.lint.isort]
+# Test helper imported from the tests directory, not an installed package.
+known-local-folder = ["stdout_guard"]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests may print freely; they never run on the proxy's stdio transport.
+# The adversarial snippets in the stdout guard test are strings, not calls.
+"tests/**" = ["T20"]
+
+# ---------------------------------------------------------------- mypy
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+files = ["src", "tests"]
+
+# ---------------------------------------------------------------- pytest
+[tool.pytest.ini_options]
+minversion = "8.3"
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+xfail_strict = true
+filterwarnings = ["error"]
+timeout = 120

mcp_claimcheck-0.1.0a1/src/mcp_claimcheck/__init__.py

@@ -0,0 +1,3 @@
+"""mcp-claimcheck: runtime semantic verification for MCP tool calls."""
+
+__version__ = "0.1.0a1"

mcp_claimcheck-0.1.0a1/src/mcp_claimcheck/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m mcp_claimcheck``."""
+
+from mcp_claimcheck.cli import main
+
+if __name__ == "__main__":
+    main()

mcp_claimcheck-0.1.0a1/src/mcp_claimcheck/cli.py

@@ -0,0 +1,151 @@
+"""Command-line entrypoint.
+
+Rule 5: this module must never write to stdout itself. ``--version`` and ``--help``
+are written to stdout by click's built-in options. Both are one-shot informational
+commands that exit immediately, so they can never run on the proxy's stdio transport.
+Usage errors go to stderr (click's default).
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from mcp_claimcheck import __version__
+from mcp_claimcheck import log as logsetup
+from mcp_claimcheck.config import Config, ConfigError, from_command_line, load
+
+LOG_LEVELS = ["debug", "info", "warning", "error"]
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, "-V", "--version", prog_name="mcp-claimcheck")
+def main() -> None:
+    """Runtime semantic verification for MCP tool calls."""
+
+
+@main.command(
+    context_settings={"allow_interspersed_args": False},
+    short_help="Run an MCP server behind the proxy.",
+)
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="TOML config file naming the upstream server (instead of a command).",
+)
+@click.option(
+    "--shutdown-timeout",
+    type=click.FloatRange(min=0.0, max=600.0),
+    default=5.0,
+    show_default=True,
+    help="Seconds to wait for the upstream to exit before forcing it.",
+)
+@click.option(
+    "--log-level",
+    type=click.Choice(LOG_LEVELS, case_sensitive=False),
+    default="warning",
+    show_default=True,
+    help="How much to log to stderr.",
+)
+@click.argument("command", nargs=-1, type=click.UNPROCESSED)
+def run(
+    config_path: Path | None,
+    shutdown_timeout: float,
+    log_level: str,
+    command: tuple[str, ...],
+) -> None:
+    """Start an MCP server and relay traffic between it and the MCP client.
+
+    Give the server either as a command after `--`:
+
+        mcp-claimcheck run -- npx -y @modelcontextprotocol/server-everything
+
+    or in a config file:
+
+        mcp-claimcheck run --config claimcheck.toml
+
+    The MCP client launches mcp-claimcheck instead of the server itself. stdout
+    carries only MCP messages; diagnostics go to stderr.
+    """
+    config = _resolve_config(config_path, command)
+    handler = logsetup.configure(log_level)
+    # Imported here so `--version` and `--help` stay fast and import nothing else.
+    from mcp_claimcheck.proxy.process import UpstreamSpawnError
+    from mcp_claimcheck.proxy.stdio import StdioProxy
+
+    try:
+        exit_code = StdioProxy(config.upstream, shutdown_timeout=shutdown_timeout).run()
+    except UpstreamSpawnError as exc:
+        handler.shutdown()
+        raise click.ClickException(str(exc)) from exc
+    handler.shutdown()
+    sys.exit(exit_code)
+
+
+@main.command(short_help="Validate contract files.")
+@click.option(
+    "--contracts",
+    "contracts_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=Path("contracts"),
+    show_default=True,
+    help="Directory of contract files to validate.",
+)
+def check(contracts_dir: Path) -> None:
+    """Validate every contract in a directory and report what is wrong.
+
+    Exit codes are meant for CI:
+
+    \b
+      0  every contract is valid (or the directory holds none yet)
+      1  at least one contract has a problem
+      2  the command itself was used wrongly
+
+    The report goes to stderr, because Rule 5 reserves stdout for MCP traffic and the
+    same binary serves both purposes. Redirect with `2>` to capture it.
+    """
+    # Imported here so `--version` and `--help` do not pay for yaml and jsonschema.
+    from mcp_claimcheck.contracts.loader import find_files, read_directory
+
+    contracts, problems = read_directory(contracts_dir)
+    for problem in sorted(problems):
+        click.echo(str(problem), err=True)
+
+    if problems:
+        counted = _count(len(problems), "problem")
+        click.echo(f"\n{counted} found in {contracts_dir}", err=True)
+        sys.exit(1)
+
+    if not contracts:
+        # Not a failure. A project that has not written contracts yet is a legitimate
+        # state, and failing CI for it would punish adopting the tool gradually. The
+        # message is explicit so a mistyped directory is not mistaken for success.
+        found = len(find_files(contracts_dir)) if contracts_dir.is_dir() else 0
+        detail = "no contract files" if not found else f"{_count(found, 'file')} but no contracts"
+        click.echo(f"{detail} in {contracts_dir}", err=True)
+        return
+
+    click.echo(f"{_count(len(contracts), 'contract')} in {contracts_dir}: all valid", err=True)
+
+
+def _count(number: int, noun: str) -> str:
+    return f"{number} {noun}" if number == 1 else f"{number} {noun}s"
+
+
+def _resolve_config(config_path: Path | None, command: tuple[str, ...]) -> Config:
+    if config_path is not None and command:
+        raise click.UsageError("give either --config or a server command after '--', not both")
+    try:
+        if config_path is not None:
+            return load(config_path)
+        if not command:
+            raise click.UsageError(
+                "no upstream server given: use 'mcp-claimcheck run -- <command> [args...]' "
+                "or 'mcp-claimcheck run --config <file>'"
+            )
+        return from_command_line(command)
+    except ConfigError as exc:
+        raise click.UsageError(str(exc)) from exc

mcp_claimcheck-0.1.0a1/src/mcp_claimcheck/config.py

@@ -0,0 +1,165 @@
+"""Configuration: which upstream MCP server to launch, and how.
+
+Two ways to say it, and exactly one must be used:
+
+* On the command line: ``mcp-claimcheck run -- <command> [args...]``.
+* In a TOML file: ``mcp-claimcheck run --config claimcheck.toml``::
+
+      [upstream]
+      command = "npx"                       # required
+      args = ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
+      cwd = "."                              # optional; relative to this file
+      [upstream.env]                         # optional; merged over our own env
+      API_TOKEN = "..."
+
+``args`` are passed to the server exactly as written; only ``cwd`` is resolved
+relative to the config file.
+
+Validation is strict. Unknown keys are errors, not silently ignored, because a
+misspelt key that is ignored becomes a setting the user believes is active. Every
+error names the file and the key.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+class ConfigError(ValueError):
+    """The configuration is invalid. The message is written for a human."""
+
+
+@dataclass(frozen=True)
+class UpstreamConfig:
+    command: str
+    args: tuple[str, ...] = ()
+    env: Mapping[str, str] = field(default_factory=dict)
+    cwd: Path | None = None
+
+    @property
+    def argv(self) -> list[str]:
+        return [self.command, *self.args]
+
+
+@dataclass(frozen=True)
+class Config:
+    upstream: UpstreamConfig
+    source: Path | None = None  # None when built from the command line
+
+
+_TOP_LEVEL_KEYS = frozenset({"upstream"})
+_UPSTREAM_KEYS = frozenset({"command", "args", "env", "cwd"})
+
+
+def from_command_line(argv: Sequence[str]) -> Config:
+    """Build a config from ``<command> [args...]`` given after ``--``."""
+    if not argv:
+        raise ConfigError("no upstream server command given")
+    command, *args = argv
+    if not command.strip():
+        raise ConfigError("the upstream server command is empty")
+    return Config(UpstreamConfig(command=command, args=tuple(args)))
+
+
+def load(path: Path) -> Config:
+    """Read and validate a TOML config file."""
+    try:
+        raw = path.read_bytes()
+    except OSError as exc:
+        raise ConfigError(f"{path}: cannot read config file: {exc.strerror or exc}") from exc
+    try:
+        data = tomllib.loads(raw.decode("utf-8"))
+    except UnicodeDecodeError as exc:
+        raise ConfigError(f"{path}: config file is not valid UTF-8 ({exc.reason})") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{path}: invalid TOML: {exc}") from exc
+    return _parse(data, path)
+
+
+def _parse(data: dict[str, Any], path: Path) -> Config:
+    _reject_unknown(data, _TOP_LEVEL_KEYS, path, prefix="")
+    if "upstream" not in data:
+        raise ConfigError(f"{path}: missing required table [upstream]")
+    upstream = data["upstream"]
+    if not isinstance(upstream, dict):
+        raise ConfigError(f"{path}: 'upstream' must be a table ([upstream])")
+    _reject_unknown(upstream, _UPSTREAM_KEYS, path, prefix="upstream.")
+
+    command = upstream.get("command")
+    if not isinstance(command, str):
+        if command is None:
+            raise ConfigError(f"{path}: missing required key upstream.command")
+        raise ConfigError(f"{path}: upstream.command must be a string, got {_type(command)}")
+    if not command.strip():
+        raise ConfigError(f"{path}: upstream.command is empty")
+
+    args = upstream.get("args", [])
+    if not isinstance(args, list):
+        raise ConfigError(f"{path}: upstream.args must be an array of strings, got {_type(args)}")
+    for index, arg in enumerate(args):
+        if not isinstance(arg, str):
+            raise ConfigError(
+                f"{path}: upstream.args[{index}] must be a string, got {_type(arg)}"
+                f"{_quote_hint(arg)}"
+            )
+
+    env = upstream.get("env", {})
+    if not isinstance(env, dict):
+        raise ConfigError(f"{path}: upstream.env must be a table, got {_type(env)}")
+    for key, value in env.items():
+        if not isinstance(value, str):
+            raise ConfigError(
+                f"{path}: upstream.env.{key} must be a string, got {_type(value)};"
+                f" environment values are text{_quote_hint(value, key)}"
+            )
+
+    cwd_value = upstream.get("cwd")
+    cwd: Path | None = None
+    if cwd_value is not None:
+        if not isinstance(cwd_value, str) or not cwd_value.strip():
+            raise ConfigError(f"{path}: upstream.cwd must be a non-empty string")
+        cwd = Path(cwd_value)
+        if not cwd.is_absolute():
+            cwd = (path.parent / cwd).resolve()
+        if not cwd.is_dir():
+            raise ConfigError(f"{path}: upstream.cwd is not a directory: {cwd}")
+
+    return Config(
+        UpstreamConfig(command=command, args=tuple(args), env=dict(env), cwd=cwd),
+        source=path,
+    )
+
+
+def _reject_unknown(
+    table: dict[str, Any], allowed: frozenset[str], path: Path, prefix: str
+) -> None:
+    unknown = sorted(set(table) - allowed)
+    if unknown:
+        known = ", ".join(sorted(allowed))
+        names = ", ".join(f"{prefix}{key}" for key in unknown)
+        raise ConfigError(f"{path}: unknown key(s): {names} (allowed here: {known})")
+
+
+_TYPE_NAMES: dict[type, str] = {
+    bool: "a boolean",
+    int: "an integer",
+    float: "a number",
+    list: "an array",
+    dict: "a table",
+}
+
+
+def _type(value: object) -> str:
+    return _TYPE_NAMES.get(type(value), type(value).__name__)
+
+
+def _quote_hint(value: object, key: str | None = None) -> str:
+    """Suggest quoting, but only for scalars, where quoting is the likely fix."""
+    if not isinstance(value, bool | int | float):
+        return ""
+    text = str(value).lower() if isinstance(value, bool) else str(value)
+    return f' (quote it: {key} = "{text}")' if key else f' (quote it: "{text}")'

mcp_claimcheck-0.1.0a1/src/mcp_claimcheck/contracts/__init__.py

@@ -0,0 +1,17 @@
+"""Contracts as data: the model, the loader, and the expression syntax gate.
+
+Phase 3 only reads and validates contracts. Nothing here verifies a tool call: schema
+validation is Phase 4 and expression evaluation is Phase 5.
+"""
+
+from mcp_claimcheck.contracts.model import Contract, ContractSet, Mode
+from mcp_claimcheck.contracts.problems import ContractError, Position, Problem
+
+__all__ = [
+    "Contract",
+    "ContractError",
+    "ContractSet",
+    "Mode",
+    "Position",
+    "Problem",
+]