jep-mcp-wrapper 0.1.1__tar.gz

jep_mcp_wrapper-0.1.1/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: jep-mcp-wrapper
+Version: 0.1.1
+Summary: Verifiable accountability wrapper for MCP tool execution
+Author: JEP MCP Wrapper Contributors
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: filelock<4,>=3.12
+
+# jep-mcp-wrapper
+
+`jep-mcp-wrapper` adds verifiable accountability semantics to MCP tool execution without changing the MCP protocol. Existing tool callables are wrapped in a side-channel JEP runtime that emits deterministic, append-only events for each execution lifecycle step.
+
+## What it provides
+
+- `JEPMCPWrapper` wraps sync and async MCP tool callables.
+- `MCPExecutionTracer` writes lifecycle events (`requested`, `running`, `succeeded`, `failed`).
+- `ToolDelegationRuntime` tracks the active actor, delegation lineage, parent context, and authority scope across nested tool calls.
+- `ReplayVerifier` replays archived execution chains, verifies lineage, validates deterministic hashes, and detects archive tampering.
+- `AppendOnlyEventArchive` stores JSONL events as an append-only hash chain.
+
+The wrapper records:
+
+- `tool_name`
+- `actor`
+- delegation lineage
+- authority scope
+- execution state
+- parent event linkage
+- deterministic event hash and previous hash
+
+## Quick start
+
+```python
+from pathlib import Path
+from jep_mcp_wrapper import JEPMCPWrapper, ReplayVerifier
+
+archive = "jep-events.jsonl"
+wrapper = JEPMCPWrapper(
+    archive,
+    default_actor="agent:file-reader",
+    default_authority_scope={"filesystem": "read-only"},
+)
+
+def read_file(path: str) -> str:
+    return Path(path).read_text(encoding="utf-8")
+
+read_file = wrapper.wrap_tool("filesystem.read_file", read_file)
+print(read_file("README.md"))
+
+replay = ReplayVerifier(archive).replay()
+assert replay.verified
+```
+
+## Chained delegation
+
+Nested wrapped calls automatically extend lineage. A `search.query` tool that calls a wrapped `browser.fetch` tool produces two execution chains: one with `("search.query",)` and one with `("search.query", "browser.fetch")`.
+
+```python
+from jep_mcp_wrapper import JEPMCPWrapper
+
+wrapper = JEPMCPWrapper("events.jsonl", default_actor="agent:researcher")
+
+def browser_fetch(url: str) -> str:
+    return f"page:{url}"
+
+def search(query: str, fetch) -> str:
+    return fetch(f"https://example.test?q={query}")
+
+fetch = wrapper.wrap_tool("browser.fetch", browser_fetch, authority_scope={"network": "example.test"})
+search = wrapper.wrap_tool("search.query", search, authority_scope={"purpose": "research"})
+search("accountability", fetch=fetch)
+```
+
+## Replay and tamper detection
+
+```python
+from jep_mcp_wrapper import ReplayVerifier
+
+verifier = ReplayVerifier("events.jsonl")
+result = verifier.replay()
+print(result.verified)
+print(result.lineage_by_call)
+print(verifier.detect_tampering())
+```
+
+Replay verification checks:
+
+1. deterministic hash equality for every event,
+2. previous-hash continuity across the append-only archive,
+3. monotonic event sequence numbers,
+4. valid tool lifecycle transitions,
+5. stable lineage for every tool call,
+6. parent/child lineage consistency when parent links are present.
+
+## Examples
+
+- `examples/filesystem_tool.py` wraps a filesystem read tool.
+- `examples/browser_search_chain.py` wraps browser and search tools with chained delegation.
+
+## Non-goals
+
+- It does not modify MCP protocol schemas or wire semantics.
+- It does not implement an orchestration framework.
+- It does not decide whether a tool is authorized; it records the declared authority scope so execution can be audited and replayed.

jep_mcp_wrapper-0.1.1/README.md

@@ -0,0 +1,96 @@
+# jep-mcp-wrapper
+
+`jep-mcp-wrapper` adds verifiable accountability semantics to MCP tool execution without changing the MCP protocol. Existing tool callables are wrapped in a side-channel JEP runtime that emits deterministic, append-only events for each execution lifecycle step.
+
+## What it provides
+
+- `JEPMCPWrapper` wraps sync and async MCP tool callables.
+- `MCPExecutionTracer` writes lifecycle events (`requested`, `running`, `succeeded`, `failed`).
+- `ToolDelegationRuntime` tracks the active actor, delegation lineage, parent context, and authority scope across nested tool calls.
+- `ReplayVerifier` replays archived execution chains, verifies lineage, validates deterministic hashes, and detects archive tampering.
+- `AppendOnlyEventArchive` stores JSONL events as an append-only hash chain.
+
+The wrapper records:
+
+- `tool_name`
+- `actor`
+- delegation lineage
+- authority scope
+- execution state
+- parent event linkage
+- deterministic event hash and previous hash
+
+## Quick start
+
+```python
+from pathlib import Path
+from jep_mcp_wrapper import JEPMCPWrapper, ReplayVerifier
+
+archive = "jep-events.jsonl"
+wrapper = JEPMCPWrapper(
+    archive,
+    default_actor="agent:file-reader",
+    default_authority_scope={"filesystem": "read-only"},
+)
+
+def read_file(path: str) -> str:
+    return Path(path).read_text(encoding="utf-8")
+
+read_file = wrapper.wrap_tool("filesystem.read_file", read_file)
+print(read_file("README.md"))
+
+replay = ReplayVerifier(archive).replay()
+assert replay.verified
+```
+
+## Chained delegation
+
+Nested wrapped calls automatically extend lineage. A `search.query` tool that calls a wrapped `browser.fetch` tool produces two execution chains: one with `("search.query",)` and one with `("search.query", "browser.fetch")`.
+
+```python
+from jep_mcp_wrapper import JEPMCPWrapper
+
+wrapper = JEPMCPWrapper("events.jsonl", default_actor="agent:researcher")
+
+def browser_fetch(url: str) -> str:
+    return f"page:{url}"
+
+def search(query: str, fetch) -> str:
+    return fetch(f"https://example.test?q={query}")
+
+fetch = wrapper.wrap_tool("browser.fetch", browser_fetch, authority_scope={"network": "example.test"})
+search = wrapper.wrap_tool("search.query", search, authority_scope={"purpose": "research"})
+search("accountability", fetch=fetch)
+```
+
+## Replay and tamper detection
+
+```python
+from jep_mcp_wrapper import ReplayVerifier
+
+verifier = ReplayVerifier("events.jsonl")
+result = verifier.replay()
+print(result.verified)
+print(result.lineage_by_call)
+print(verifier.detect_tampering())
+```
+
+Replay verification checks:
+
+1. deterministic hash equality for every event,
+2. previous-hash continuity across the append-only archive,
+3. monotonic event sequence numbers,
+4. valid tool lifecycle transitions,
+5. stable lineage for every tool call,
+6. parent/child lineage consistency when parent links are present.
+
+## Examples
+
+- `examples/filesystem_tool.py` wraps a filesystem read tool.
+- `examples/browser_search_chain.py` wraps browser and search tools with chained delegation.
+
+## Non-goals
+
+- It does not modify MCP protocol schemas or wire semantics.
+- It does not implement an orchestration framework.
+- It does not decide whether a tool is authorized; it records the declared authority scope so execution can be audited and replayed.

jep_mcp_wrapper-0.1.1/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jep-mcp-wrapper"
+version = "0.1.1"
+description = "Verifiable accountability wrapper for MCP tool execution"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["filelock>=3.12,<4"]
+license = { text = "MIT" }
+authors = [{ name = "JEP MCP Wrapper Contributors" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

jep_mcp_wrapper-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jep_mcp_wrapper-0.1.1/src/jep_mcp_wrapper/__init__.py

@@ -0,0 +1,26 @@
+"""JEP accountability semantics for MCP tool execution.
+
+The package wraps existing MCP tool callables without changing the MCP protocol.
+"""
+
+from .archive import AppendOnlyEventArchive, ArchiveTamperError
+from .events import JEPEvent, ToolExecutionState, deterministic_hash
+from .runtime import DelegationContext, ToolDelegationRuntime
+from .tracer import MCPExecutionTracer
+from .verifier import ReplayResult, ReplayVerifier
+from .wrapper import JEPMCPWrapper, ToolCallResult
+
+__all__ = [
+    "AppendOnlyEventArchive",
+    "ArchiveTamperError",
+    "DelegationContext",
+    "JEPEvent",
+    "JEPMCPWrapper",
+    "MCPExecutionTracer",
+    "ReplayResult",
+    "ReplayVerifier",
+    "ToolCallResult",
+    "ToolDelegationRuntime",
+    "ToolExecutionState",
+    "deterministic_hash",
+]

jep_mcp_wrapper-0.1.1/src/jep_mcp_wrapper/archive.py

@@ -0,0 +1,111 @@
+"""Append-only event archive for JEP MCP wrapper events."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from filelock import FileLock
+from typing import Iterable
+
+from .events import JEPEvent
+
+
+class ArchiveTamperError(RuntimeError):
+    """Raised when an archive's existing hash chain is invalid."""
+
+
+class AppendOnlyEventArchive:
+    """JSONL archive that only appends events and validates existing chains."""
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path).resolve()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = FileLock(str(self.path) + ".lock", timeout=30)
+        self._last_hash: str | None = None
+        self._next_sequence = 0
+        with self._lock:
+            self._load_and_validate()
+
+    @property
+    def last_hash(self) -> str | None:
+        return self._last_hash
+
+    @property
+    def next_sequence(self) -> int:
+        return self._next_sequence
+
+    def append_new(self, **fields) -> JEPEvent:
+        """Assign sequence/hash and append under one cross-process lock."""
+        with self._lock:
+            self._load_and_validate()
+            event = JEPEvent.create(sequence=self._next_sequence, prev_hash=self._last_hash, **fields)
+            return self.append(event)
+
+    def append(self, event: JEPEvent) -> JEPEvent:
+        """Append a single event after enforcing sequence and hash continuity."""
+
+        with self._lock:
+            self._load_and_validate()
+            if event.sequence != self._next_sequence:
+                raise ArchiveTamperError(
+                    f"event sequence {event.sequence} does not match next sequence {self._next_sequence}"
+                )
+            if event.prev_hash != self._last_hash:
+                raise ArchiveTamperError("event prev_hash does not match archive tail")
+            sealed = event.with_hash()
+            with self.path.open("a", encoding="utf-8") as stream:
+                stream.write(json.dumps(sealed.to_record(), sort_keys=True, ensure_ascii=False) + "\n")
+            self._last_hash = sealed.event_hash
+            self._next_sequence += 1
+            return sealed
+
+    def read_events(self) -> list[JEPEvent]:
+        """Read all events from the archive."""
+
+        with self._lock:
+            return self._read_events()
+
+    def _read_events(self) -> list[JEPEvent]:
+        if not self.path.exists():
+            return []
+        events: list[JEPEvent] = []
+        with self.path.open("r", encoding="utf-8") as stream:
+            for line_number, line in enumerate(stream, start=1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    events.append(JEPEvent.from_record(json.loads(line)))
+                except (KeyError, TypeError, json.JSONDecodeError, ValueError) as exc:
+                    raise ArchiveTamperError(f"invalid archive record at line {line_number}") from exc
+        return events
+
+    def _load_and_validate(self) -> None:
+        previous_hash: str | None = None
+        expected_sequence = 0
+        for event in self.read_events():
+            _validate_event(event, expected_sequence, previous_hash)
+            previous_hash = event.event_hash
+            expected_sequence += 1
+        self._last_hash = previous_hash
+        self._next_sequence = expected_sequence
+
+
+def _validate_event(event: JEPEvent, expected_sequence: int, previous_hash: str | None) -> None:
+    if event.sequence != expected_sequence:
+        raise ArchiveTamperError(
+            f"event sequence {event.sequence} does not match expected sequence {expected_sequence}"
+        )
+    if event.prev_hash != previous_hash:
+        raise ArchiveTamperError("event prev_hash breaks archive hash chain")
+    if event.event_hash != event.compute_hash():
+        raise ArchiveTamperError("event_hash does not match deterministic event payload")
+
+
+def validate_events(events: Iterable[JEPEvent]) -> None:
+    """Validate sequence numbers, event hashes, and hash-chain continuity."""
+
+    previous_hash: str | None = None
+    for expected_sequence, event in enumerate(events):
+        _validate_event(event, expected_sequence, previous_hash)
+        previous_hash = event.event_hash

jep_mcp_wrapper-0.1.1/src/jep_mcp_wrapper/events.py

@@ -0,0 +1,152 @@
+"""Deterministic JEP event model and hashing utilities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+import hashlib
+import json
+from typing import Any, Mapping
+from uuid import uuid4
+
+
+class ToolExecutionState(str, Enum):
+    """Lifecycle states recorded for MCP tool execution."""
+
+    REQUESTED = "requested"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    DELEGATED = "delegated"
+
+
+def _canonical_json(payload: Mapping[str, Any]) -> str:
+    """Serialize a mapping into deterministic JSON for stable event hashes."""
+
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def deterministic_hash(payload: Mapping[str, Any]) -> str:
+    """Return a SHA-256 digest for a canonical JSON payload."""
+
+    return hashlib.sha256(_canonical_json(payload).encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class JEPEvent:
+    """Append-only accountability event for an MCP tool execution step."""
+
+    event_id: str
+    tool_name: str
+    actor: str
+    delegation_lineage: tuple[str, ...]
+    authority_scope: Mapping[str, Any]
+    execution_state: ToolExecutionState
+    sequence: int
+    prev_hash: str | None = None
+    parent_event_id: str | None = None
+    call_id: str = field(default_factory=lambda: uuid4().hex)
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+    event_hash: str | None = None
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        tool_name: str,
+        actor: str,
+        delegation_lineage: tuple[str, ...],
+        authority_scope: Mapping[str, Any],
+        execution_state: ToolExecutionState,
+        sequence: int,
+        prev_hash: str | None,
+        parent_event_id: str | None = None,
+        call_id: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> "JEPEvent":
+        """Create an event and deterministically seal it with an event hash."""
+
+        event = cls(
+            event_id=uuid4().hex,
+            tool_name=tool_name,
+            actor=actor,
+            delegation_lineage=delegation_lineage,
+            authority_scope=dict(authority_scope),
+            execution_state=execution_state,
+            sequence=sequence,
+            prev_hash=prev_hash,
+            parent_event_id=parent_event_id,
+            call_id=call_id or uuid4().hex,
+            metadata=dict(metadata or {}),
+        )
+        return event.with_hash()
+
+    def hash_payload(self) -> dict[str, Any]:
+        """Return the exact event fields covered by the deterministic hash."""
+
+        return {
+            "actor": self.actor,
+            "authority_scope": dict(self.authority_scope),
+            "call_id": self.call_id,
+            "delegation_lineage": list(self.delegation_lineage),
+            "event_id": self.event_id,
+            "execution_state": self.execution_state.value,
+            "metadata": dict(self.metadata),
+            "parent_event_id": self.parent_event_id,
+            "prev_hash": self.prev_hash,
+            "sequence": self.sequence,
+            "tool_name": self.tool_name,
+        }
+
+    def compute_hash(self) -> str:
+        """Compute this event's deterministic hash."""
+
+        return deterministic_hash(self.hash_payload())
+
+    def with_hash(self) -> "JEPEvent":
+        """Return a copy with its event_hash populated from sealed fields."""
+
+        return JEPEvent(
+            event_id=self.event_id,
+            tool_name=self.tool_name,
+            actor=self.actor,
+            delegation_lineage=self.delegation_lineage,
+            authority_scope=dict(self.authority_scope),
+            execution_state=self.execution_state,
+            sequence=self.sequence,
+            prev_hash=self.prev_hash,
+            parent_event_id=self.parent_event_id,
+            call_id=self.call_id,
+            metadata=dict(self.metadata),
+            event_hash=self.compute_hash(),
+        )
+
+    def to_record(self) -> dict[str, Any]:
+        """Serialize this event for JSONL archive storage."""
+
+        event_hash = self.event_hash or self.compute_hash()
+        return {**self.hash_payload(), "event_hash": event_hash}
+
+    @classmethod
+    def from_record(cls, record: Mapping[str, Any]) -> "JEPEvent":
+        """Deserialize an event record from JSONL archive storage."""
+
+        if not isinstance(record, Mapping) or type(record.get("sequence")) is not int:
+            raise ValueError("invalid archive event type")
+        for field in ("event_id", "tool_name", "actor", "call_id"):
+            if not isinstance(record.get(field), str):
+                raise ValueError("invalid archive string field")
+        return cls(
+            event_id=record["event_id"],
+            tool_name=str(record["tool_name"]),
+            actor=str(record["actor"]),
+            delegation_lineage=tuple(record.get("delegation_lineage", ())),
+            authority_scope=dict(record.get("authority_scope", {})),
+            execution_state=ToolExecutionState(record["execution_state"]),
+            sequence=record["sequence"],
+            prev_hash=record.get("prev_hash"),
+            parent_event_id=record.get("parent_event_id"),
+            call_id=str(record["call_id"]),
+            metadata=dict(record.get("metadata", {})),
+            event_hash=record.get("event_hash"),
+        )

jep_mcp_wrapper-0.1.1/src/jep_mcp_wrapper/runtime.py

@@ -0,0 +1,85 @@
+"""Delegation context runtime for accountable MCP tool calls."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Any, Iterator, Mapping
+
+
+@dataclass(frozen=True)
+class DelegationContext:
+    """Actor, lineage, and authority scope active for a tool call."""
+
+    actor: str
+    delegation_lineage: tuple[str, ...] = field(default_factory=tuple)
+    authority_scope: Mapping[str, Any] = field(default_factory=dict)
+    parent_event_id: str | None = None
+
+
+_current_context: ContextVar[DelegationContext | None] = ContextVar("jep_mcp_delegation_context", default=None)
+
+
+class ToolDelegationRuntime:
+    """Maintains nested tool delegation lineage without changing MCP payloads."""
+
+    def __init__(self, *, default_actor: str = "mcp-client", default_authority_scope: Mapping[str, Any] | None = None):
+        self.default_actor = default_actor
+        self.default_authority_scope = dict(default_authority_scope or {})
+
+    def current(self) -> DelegationContext:
+        """Return active context or a default root context."""
+
+        context = _current_context.get()
+        if context is not None:
+            return context
+        return DelegationContext(actor=self.default_actor, authority_scope=self.default_authority_scope)
+
+    @contextmanager
+    def as_actor(
+        self,
+        actor: str,
+        *,
+        authority_scope: Mapping[str, Any] | None = None,
+        parent_event_id: str | None = None,
+    ) -> Iterator[DelegationContext]:
+        """Run code under a root actor context."""
+
+        context = DelegationContext(
+            actor=actor,
+            authority_scope=dict(authority_scope or self.default_authority_scope),
+            parent_event_id=parent_event_id,
+        )
+        token = _current_context.set(context)
+        try:
+            yield context
+        finally:
+            _current_context.reset(token)
+
+    @contextmanager
+    def delegate(
+        self,
+        tool_name: str,
+        *,
+        actor: str | None = None,
+        authority_scope: Mapping[str, Any] | None = None,
+        parent_event_id: str | None = None,
+    ) -> Iterator[DelegationContext]:
+        """Enter a nested delegation context for chained tool execution."""
+
+        parent = self.current()
+        delegated_actor = actor or parent.actor
+        delegated_scope = dict(parent.authority_scope)
+        delegated_scope.update(dict(authority_scope or {}))
+        context = DelegationContext(
+            actor=delegated_actor,
+            delegation_lineage=(*parent.delegation_lineage, tool_name),
+            authority_scope=delegated_scope,
+            parent_event_id=parent_event_id or parent.parent_event_id,
+        )
+        token = _current_context.set(context)
+        try:
+            yield context
+        finally:
+            _current_context.reset(token)

jep_mcp_wrapper-0.1.1/src/jep_mcp_wrapper/tracer.py

@@ -0,0 +1,41 @@
+"""Event tracer for MCP tool execution."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .archive import AppendOnlyEventArchive
+from .events import JEPEvent, ToolExecutionState
+from .runtime import DelegationContext, ToolDelegationRuntime
+
+
+class MCPExecutionTracer:
+    """Creates JEP events for tool lifecycle transitions."""
+
+    def __init__(self, archive: AppendOnlyEventArchive, runtime: ToolDelegationRuntime):
+        self.archive = archive
+        self.runtime = runtime
+
+    def record(
+        self,
+        *,
+        tool_name: str,
+        state: ToolExecutionState,
+        context: DelegationContext | None = None,
+        call_id: str | None = None,
+        parent_event_id: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> JEPEvent:
+        """Create and append a lifecycle event to the archive."""
+
+        active = context or self.runtime.current()
+        return self.archive.append_new(
+            tool_name=tool_name,
+            actor=active.actor,
+            delegation_lineage=active.delegation_lineage,
+            authority_scope=active.authority_scope,
+            execution_state=state,
+            parent_event_id=parent_event_id or active.parent_event_id,
+            call_id=call_id,
+            metadata=metadata,
+        )

jep_mcp_wrapper-0.1.1/src/jep_mcp_wrapper/verifier.py

@@ -0,0 +1,117 @@
+"""Replay and verification for archived JEP MCP tool events."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+
+from .archive import AppendOnlyEventArchive, ArchiveTamperError, validate_events
+from .events import JEPEvent, ToolExecutionState
+
+
+_VALID_TRANSITIONS = {
+    ToolExecutionState.REQUESTED: {ToolExecutionState.RUNNING},
+    ToolExecutionState.RUNNING: {ToolExecutionState.SUCCEEDED, ToolExecutionState.FAILED},
+    ToolExecutionState.SUCCEEDED: set(),
+    ToolExecutionState.FAILED: set(),
+    ToolExecutionState.DELEGATED: {ToolExecutionState.REQUESTED, ToolExecutionState.RUNNING},
+}
+
+
+@dataclass(frozen=True)
+class ReplayResult:
+    """Result of replaying and verifying an archive."""
+
+    verified: bool
+    events: tuple[JEPEvent, ...]
+    terminal_states: dict[str, ToolExecutionState]
+    lineage_by_call: dict[str, tuple[str, ...]]
+    errors: tuple[str, ...] = field(default_factory=tuple)
+
+
+class ReplayVerifier:
+    """Replays execution chains, verifies lineages, and detects tampering."""
+
+    def __init__(self, archive: AppendOnlyEventArchive | str):
+        self.archive = archive
+
+    def replay(self) -> ReplayResult:
+        """Replay archive events and return chain state with validation errors."""
+
+        try:
+            archive = self.archive if isinstance(self.archive, AppendOnlyEventArchive) else AppendOnlyEventArchive(self.archive)
+            events = archive.read_events()
+            validate_events(events)
+        except ArchiveTamperError as exc:
+            return ReplayResult(
+                verified=False,
+                events=(),
+                terminal_states={},
+                lineage_by_call={},
+                errors=(f"tampering detected: {exc}",),
+            )
+
+        errors: list[str] = []
+        events_by_call: dict[str, list[JEPEvent]] = defaultdict(list)
+        for event in events:
+            events_by_call[event.call_id].append(event)
+
+        terminal_states: dict[str, ToolExecutionState] = {}
+        lineage_by_call: dict[str, tuple[str, ...]] = {}
+        for call_id, call_events in events_by_call.items():
+            previous_state: ToolExecutionState | None = None
+            if call_events[0].execution_state not in {ToolExecutionState.REQUESTED, ToolExecutionState.DELEGATED}:
+                errors.append(f"call {call_id} missing initial request")
+            expected_lineage = call_events[0].delegation_lineage
+            for event in call_events:
+                if event.delegation_lineage != expected_lineage:
+                    errors.append(f"call {call_id} changed delegation lineage")
+                if previous_state is not None and event.execution_state not in _VALID_TRANSITIONS[previous_state]:
+                    errors.append(
+                        f"call {call_id} invalid transition {previous_state.value}->{event.execution_state.value}"
+                    )
+                previous_state = event.execution_state
+            terminal_states[call_id] = call_events[-1].execution_state
+            lineage_by_call[call_id] = expected_lineage
+            if call_events[-1].execution_state not in {ToolExecutionState.SUCCEEDED, ToolExecutionState.FAILED}:
+                errors.append(f"call {call_id} did not reach a terminal state")
+
+        self._verify_parent_lineage(events, errors)
+        return ReplayResult(
+            verified=not errors,
+            events=tuple(events),
+            terminal_states=terminal_states,
+            lineage_by_call=lineage_by_call,
+            errors=tuple(errors),
+        )
+
+    def verify_tool_lineage(self, expected_prefix: tuple[str, ...] | None = None) -> bool:
+        """Return True when replay succeeds and every call matches an optional lineage prefix."""
+
+        result = self.replay()
+        if not result.verified:
+            return False
+        if expected_prefix is None:
+            return True
+        return all(lineage[: len(expected_prefix)] == expected_prefix for lineage in result.lineage_by_call.values())
+
+    def detect_tampering(self) -> bool:
+        """Return True when deterministic hashes or replay semantics fail."""
+
+        return not self.replay().verified
+
+    def _verify_parent_lineage(self, events: list[JEPEvent], errors: list[str]) -> None:
+        by_event_id = {event.event_id: event for event in events}
+        for event in events:
+            if event.parent_event_id is None:
+                continue
+            parent = by_event_id.get(event.parent_event_id)
+            if parent is None:
+                errors.append(f"event {event.event_id} references missing parent_event_id")
+                continue
+            if parent.sequence >= event.sequence:
+                errors.append(f"event {event.event_id} parent must precede child")
+            parent_lineage = parent.delegation_lineage
+            lineage = event.delegation_lineage
+            if lineage != parent_lineage and lineage[:-1] != parent_lineage:
+                errors.append(f"event {event.event_id} lineage does not descend from parent")

jep_mcp_wrapper-0.1.1/src/jep_mcp_wrapper/wrapper.py

@@ -0,0 +1,189 @@
+"""Public wrapper for accountable MCP tool execution."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any, Awaitable, Callable, Mapping, TypeVar
+from uuid import uuid4
+
+from .archive import AppendOnlyEventArchive
+from .events import JEPEvent, ToolExecutionState
+from .runtime import ToolDelegationRuntime
+from .tracer import MCPExecutionTracer
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class ToolCallResult:
+    """Tool result plus trace metadata emitted by the wrapper."""
+
+    value: Any
+    call_id: str
+    start_event: JEPEvent
+    end_event: JEPEvent
+
+
+class JEPMCPWrapper:
+    """Wrap MCP tools with verifiable JEP accountability semantics.
+
+    The wrapper decorates existing callables and keeps all accountability state in
+    a side-channel event archive, so MCP protocol request/response schemas remain
+    untouched.
+    """
+
+    def __init__(
+        self,
+        archive: AppendOnlyEventArchive | str,
+        *,
+        default_actor: str = "mcp-client",
+        default_authority_scope: Mapping[str, Any] | None = None,
+        return_trace: bool = False,
+    ):
+        self.archive = archive if isinstance(archive, AppendOnlyEventArchive) else AppendOnlyEventArchive(archive)
+        self.runtime = ToolDelegationRuntime(
+            default_actor=default_actor,
+            default_authority_scope=default_authority_scope,
+        )
+        self.tracer = MCPExecutionTracer(self.archive, self.runtime)
+        self.return_trace = return_trace
+
+    def wrap_tool(
+        self,
+        tool_name: str,
+        tool: Callable[..., T],
+        *,
+        authority_scope: Mapping[str, Any] | None = None,
+        actor: str | None = None,
+    ) -> Callable[..., T | ToolCallResult] | Callable[..., Awaitable[T | ToolCallResult]]:
+        """Return a callable that records requested/running/succeeded/failed events."""
+
+        if inspect.iscoroutinefunction(tool):
+
+            @wraps(tool)
+            async def async_wrapped(*args: Any, **kwargs: Any) -> T | ToolCallResult:
+                return await self._execute_async(tool_name, tool, args, kwargs, authority_scope=authority_scope, actor=actor)
+
+            return async_wrapped
+
+        @wraps(tool)
+        def wrapped(*args: Any, **kwargs: Any) -> T | ToolCallResult:
+            return self._execute(tool_name, tool, args, kwargs, authority_scope=authority_scope, actor=actor)
+
+        return wrapped
+
+    def call_tool(
+        self,
+        tool_name: str,
+        tool: Callable[..., T],
+        *args: Any,
+        authority_scope: Mapping[str, Any] | None = None,
+        actor: str | None = None,
+        **kwargs: Any,
+    ) -> T | ToolCallResult:
+        """Execute a synchronous tool once under accountability tracing."""
+
+        return self._execute(tool_name, tool, args, kwargs, authority_scope=authority_scope, actor=actor)
+
+    async def call_tool_async(
+        self,
+        tool_name: str,
+        tool: Callable[..., Awaitable[T]],
+        *args: Any,
+        authority_scope: Mapping[str, Any] | None = None,
+        actor: str | None = None,
+        **kwargs: Any,
+    ) -> T | ToolCallResult:
+        """Execute an async tool once under accountability tracing."""
+
+        return await self._execute_async(tool_name, tool, args, kwargs, authority_scope=authority_scope, actor=actor)
+
+    def _execute(
+        self,
+        tool_name: str,
+        tool: Callable[..., T],
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+        *,
+        authority_scope: Mapping[str, Any] | None,
+        actor: str | None,
+    ) -> T | ToolCallResult:
+        call_id = uuid4().hex
+        with self.runtime.delegate(tool_name, actor=actor, authority_scope=authority_scope):
+            start_event = self.tracer.record(
+                tool_name=tool_name,
+                state=ToolExecutionState.REQUESTED,
+                call_id=call_id,
+            )
+            try:
+                running_event = self.tracer.record(
+                    tool_name=tool_name,
+                    state=ToolExecutionState.RUNNING,
+                    call_id=call_id,
+                    parent_event_id=start_event.event_id,
+                )
+                value = tool(*args, **kwargs)
+                end_event = self.tracer.record(
+                    tool_name=tool_name,
+                    state=ToolExecutionState.SUCCEEDED,
+                    call_id=call_id,
+                    parent_event_id=running_event.event_id,
+                )
+            except BaseException as exc:
+                end_event = self.tracer.record(
+                    tool_name=tool_name,
+                    state=ToolExecutionState.FAILED,
+                    call_id=call_id,
+                    parent_event_id=start_event.event_id,
+                    metadata={"error_type": type(exc).__name__, "error": str(exc)},
+                )
+                raise
+        if self.return_trace:
+            return ToolCallResult(value=value, call_id=call_id, start_event=start_event, end_event=end_event)
+        return value
+
+    async def _execute_async(
+        self,
+        tool_name: str,
+        tool: Callable[..., Awaitable[T]],
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+        *,
+        authority_scope: Mapping[str, Any] | None,
+        actor: str | None,
+    ) -> T | ToolCallResult:
+        call_id = uuid4().hex
+        with self.runtime.delegate(tool_name, actor=actor, authority_scope=authority_scope):
+            start_event = self.tracer.record(
+                tool_name=tool_name,
+                state=ToolExecutionState.REQUESTED,
+                call_id=call_id,
+            )
+            try:
+                running_event = self.tracer.record(
+                    tool_name=tool_name,
+                    state=ToolExecutionState.RUNNING,
+                    call_id=call_id,
+                    parent_event_id=start_event.event_id,
+                )
+                value = await tool(*args, **kwargs)
+                end_event = self.tracer.record(
+                    tool_name=tool_name,
+                    state=ToolExecutionState.SUCCEEDED,
+                    call_id=call_id,
+                    parent_event_id=running_event.event_id,
+                )
+            except BaseException as exc:
+                end_event = self.tracer.record(
+                    tool_name=tool_name,
+                    state=ToolExecutionState.FAILED,
+                    call_id=call_id,
+                    parent_event_id=start_event.event_id,
+                    metadata={"error_type": type(exc).__name__, "error": str(exc)},
+                )
+                raise
+        if self.return_trace:
+            return ToolCallResult(value=value, call_id=call_id, start_event=start_event, end_event=end_event)
+        return value

jep_mcp_wrapper-0.1.1/src/jep_mcp_wrapper.egg-info/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: jep-mcp-wrapper
+Version: 0.1.1
+Summary: Verifiable accountability wrapper for MCP tool execution
+Author: JEP MCP Wrapper Contributors
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: filelock<4,>=3.12
+
+# jep-mcp-wrapper
+
+`jep-mcp-wrapper` adds verifiable accountability semantics to MCP tool execution without changing the MCP protocol. Existing tool callables are wrapped in a side-channel JEP runtime that emits deterministic, append-only events for each execution lifecycle step.
+
+## What it provides
+
+- `JEPMCPWrapper` wraps sync and async MCP tool callables.
+- `MCPExecutionTracer` writes lifecycle events (`requested`, `running`, `succeeded`, `failed`).
+- `ToolDelegationRuntime` tracks the active actor, delegation lineage, parent context, and authority scope across nested tool calls.
+- `ReplayVerifier` replays archived execution chains, verifies lineage, validates deterministic hashes, and detects archive tampering.
+- `AppendOnlyEventArchive` stores JSONL events as an append-only hash chain.
+
+The wrapper records:
+
+- `tool_name`
+- `actor`
+- delegation lineage
+- authority scope
+- execution state
+- parent event linkage
+- deterministic event hash and previous hash
+
+## Quick start
+
+```python
+from pathlib import Path
+from jep_mcp_wrapper import JEPMCPWrapper, ReplayVerifier
+
+archive = "jep-events.jsonl"
+wrapper = JEPMCPWrapper(
+    archive,
+    default_actor="agent:file-reader",
+    default_authority_scope={"filesystem": "read-only"},
+)
+
+def read_file(path: str) -> str:
+    return Path(path).read_text(encoding="utf-8")
+
+read_file = wrapper.wrap_tool("filesystem.read_file", read_file)
+print(read_file("README.md"))
+
+replay = ReplayVerifier(archive).replay()
+assert replay.verified
+```
+
+## Chained delegation
+
+Nested wrapped calls automatically extend lineage. A `search.query` tool that calls a wrapped `browser.fetch` tool produces two execution chains: one with `("search.query",)` and one with `("search.query", "browser.fetch")`.
+
+```python
+from jep_mcp_wrapper import JEPMCPWrapper
+
+wrapper = JEPMCPWrapper("events.jsonl", default_actor="agent:researcher")
+
+def browser_fetch(url: str) -> str:
+    return f"page:{url}"
+
+def search(query: str, fetch) -> str:
+    return fetch(f"https://example.test?q={query}")
+
+fetch = wrapper.wrap_tool("browser.fetch", browser_fetch, authority_scope={"network": "example.test"})
+search = wrapper.wrap_tool("search.query", search, authority_scope={"purpose": "research"})
+search("accountability", fetch=fetch)
+```
+
+## Replay and tamper detection
+
+```python
+from jep_mcp_wrapper import ReplayVerifier
+
+verifier = ReplayVerifier("events.jsonl")
+result = verifier.replay()
+print(result.verified)
+print(result.lineage_by_call)
+print(verifier.detect_tampering())
+```
+
+Replay verification checks:
+
+1. deterministic hash equality for every event,
+2. previous-hash continuity across the append-only archive,
+3. monotonic event sequence numbers,
+4. valid tool lifecycle transitions,
+5. stable lineage for every tool call,
+6. parent/child lineage consistency when parent links are present.
+
+## Examples
+
+- `examples/filesystem_tool.py` wraps a filesystem read tool.
+- `examples/browser_search_chain.py` wraps browser and search tools with chained delegation.
+
+## Non-goals
+
+- It does not modify MCP protocol schemas or wire semantics.
+- It does not implement an orchestration framework.
+- It does not decide whether a tool is authorized; it records the declared authority scope so execution can be audited and replayed.

jep_mcp_wrapper-0.1.1/src/jep_mcp_wrapper.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+src/jep_mcp_wrapper/__init__.py
+src/jep_mcp_wrapper/archive.py
+src/jep_mcp_wrapper/events.py
+src/jep_mcp_wrapper/runtime.py
+src/jep_mcp_wrapper/tracer.py
+src/jep_mcp_wrapper/verifier.py
+src/jep_mcp_wrapper/wrapper.py
+src/jep_mcp_wrapper.egg-info/PKG-INFO
+src/jep_mcp_wrapper.egg-info/SOURCES.txt
+src/jep_mcp_wrapper.egg-info/dependency_links.txt
+src/jep_mcp_wrapper.egg-info/requires.txt
+src/jep_mcp_wrapper.egg-info/top_level.txt
+tests/test_archive_input.py
+tests/test_hardening.py
+tests/test_wrapper.py

jep_mcp_wrapper-0.1.1/src/jep_mcp_wrapper.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

jep_mcp_wrapper-0.1.1/src/jep_mcp_wrapper.egg-info/requires.txt

@@ -0,0 +1 @@
+filelock<4,>=3.12

jep_mcp_wrapper-0.1.1/src/jep_mcp_wrapper.egg-info/top_level.txt

@@ -0,0 +1 @@
+jep_mcp_wrapper

jep_mcp_wrapper-0.1.1/tests/test_archive_input.py

@@ -0,0 +1,8 @@
+import pytest
+from jep_mcp_wrapper.archive import AppendOnlyEventArchive, ArchiveTamperError
+
+
+def test_non_object_archive_record_is_reported_as_corruption(tmp_path):
+    path = tmp_path / "bad.jsonl"
+    path.write_text("null\n")
+    with pytest.raises(ArchiveTamperError): AppendOnlyEventArchive(path)

jep_mcp_wrapper-0.1.1/tests/test_hardening.py

@@ -0,0 +1,45 @@
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+import pytest
+from jep_mcp_wrapper import JEPMCPWrapper
+from jep_mcp_wrapper.archive import validate_events
+
+
+def test_multiple_instances_append_to_one_valid_archive(tmp_path):
+    path = str(tmp_path / "events.jsonl")
+    wrappers = [JEPMCPWrapper(path) for _ in range(4)]
+    with ThreadPoolExecutor(max_workers=4) as pool:
+        assert list(pool.map(lambda w: w.call_tool("read", lambda: 42), wrappers)) == [42] * 4
+    events = wrappers[0].archive.read_events()
+    assert len(events) == 12
+    validate_events(events)
+
+
+@pytest.mark.asyncio
+async def test_cancelled_call_records_terminal_failure(tmp_path):
+    wrapper = JEPMCPWrapper(str(tmp_path / "events.jsonl"))
+    started = asyncio.Event()
+
+    async def tool():
+        started.set()
+        await asyncio.Event().wait()
+
+    task = asyncio.create_task(wrapper.call_tool_async("wait", tool))
+    await started.wait()
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    events = wrapper.archive.read_events()
+    assert events[-1].execution_state.value == "failed"
+    assert events[-1].metadata["error_type"] == "CancelledError"
+    validate_events(events)
+
+
+def test_terminal_only_call_does_not_verify(tmp_path):
+    from jep_mcp_wrapper.events import ToolExecutionState
+    from jep_mcp_wrapper.verifier import ReplayVerifier
+    wrapper = JEPMCPWrapper(str(tmp_path / "events.jsonl"))
+    wrapper.tracer.record(tool_name="tool", state=ToolExecutionState.SUCCEEDED, call_id="orphan")
+    result = ReplayVerifier(wrapper.archive).replay()
+    assert result.verified is False
+    assert any("missing initial request" in error for error in result.errors)

jep_mcp_wrapper-0.1.1/tests/test_wrapper.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+
+import pytest
+
+from jep_mcp_wrapper import JEPMCPWrapper, ReplayVerifier, ToolExecutionState
+
+
+def test_wrap_tool_records_accountability_events(tmp_path: Path) -> None:
+    archive = tmp_path / "events.jsonl"
+    wrapper = JEPMCPWrapper(
+        archive,
+        default_actor="agent:test",
+        default_authority_scope={"filesystem": "read-only"},
+        return_trace=True,
+    )
+
+    def read_file(path: str) -> str:
+        return Path(path).read_text(encoding="utf-8")
+
+    target = tmp_path / "note.txt"
+    target.write_text("hello", encoding="utf-8")
+    result = wrapper.wrap_tool("filesystem.read_file", read_file)(str(target))
+
+    assert result.value == "hello"
+    replay = ReplayVerifier(archive).replay()
+    assert replay.verified, replay.errors
+    assert len(replay.events) == 3
+    assert [event.execution_state for event in replay.events] == [
+        ToolExecutionState.REQUESTED,
+        ToolExecutionState.RUNNING,
+        ToolExecutionState.SUCCEEDED,
+    ]
+    assert all(event.tool_name == "filesystem.read_file" for event in replay.events)
+    assert all(event.actor == "agent:test" for event in replay.events)
+    assert all(event.delegation_lineage == ("filesystem.read_file",) for event in replay.events)
+    assert all(event.authority_scope["filesystem"] == "read-only" for event in replay.events)
+
+
+def test_chained_tool_delegation_replays_lineage(tmp_path: Path) -> None:
+    archive = tmp_path / "events.jsonl"
+    wrapper = JEPMCPWrapper(archive, default_actor="agent:researcher")
+
+    def browser_fetch(url: str) -> str:
+        return f"page:{url}"
+
+    def search(query: str, fetch) -> str:
+        return fetch(f"https://example.test?q={query}")
+
+    fetch = wrapper.wrap_tool("browser.fetch", browser_fetch, authority_scope={"network": "example.test"})
+    accountable_search = wrapper.wrap_tool("search.query", search, authority_scope={"purpose": "test"})
+
+    assert accountable_search("jep", fetch=fetch) == "page:https://example.test?q=jep"
+    replay = ReplayVerifier(archive).replay()
+
+    assert replay.verified, replay.errors
+    lineages = set(replay.lineage_by_call.values())
+    assert ("search.query",) in lineages
+    assert ("search.query", "browser.fetch") in lineages
+    assert ReplayVerifier(archive).verify_tool_lineage(("search.query",))
+
+
+def test_failed_tool_records_failure_state(tmp_path: Path) -> None:
+    archive = tmp_path / "events.jsonl"
+    wrapper = JEPMCPWrapper(archive)
+
+    def broken() -> None:
+        raise ValueError("boom")
+
+    with pytest.raises(ValueError):
+        wrapper.call_tool("broken.tool", broken)
+
+    replay = ReplayVerifier(archive).replay()
+    assert replay.verified, replay.errors
+    assert replay.events[-1].execution_state == ToolExecutionState.FAILED
+    assert replay.events[-1].metadata["error_type"] == "ValueError"
+
+
+def test_tampering_is_detected_by_deterministic_hash(tmp_path: Path) -> None:
+    archive = tmp_path / "events.jsonl"
+    wrapper = JEPMCPWrapper(archive)
+    wrapper.call_tool("search.query", lambda: "ok")
+
+    records = archive.read_text(encoding="utf-8").splitlines()
+    first = json.loads(records[0])
+    first["actor"] = "attacker"
+    records[0] = json.dumps(first, sort_keys=True)
+    archive.write_text("\n".join(records) + "\n", encoding="utf-8")
+
+    replay = ReplayVerifier(archive).replay()
+    assert not replay.verified
+    assert ReplayVerifier(archive).detect_tampering()
+    assert "tampering detected" in replay.errors[0]
+
+
+def test_async_tool_is_wrapped(tmp_path: Path) -> None:
+    archive = tmp_path / "events.jsonl"
+    wrapper = JEPMCPWrapper(archive, default_actor="agent:async")
+
+    async def browser_fetch(url: str) -> str:
+        return f"async:{url}"
+
+    async def run_wrapped() -> str:
+        wrapped = wrapper.wrap_tool("browser.fetch", browser_fetch)
+        return await wrapped("https://example.test")
+
+    assert asyncio.run(run_wrapped()) == "async:https://example.test"
+
+    replay = ReplayVerifier(archive).replay()
+    assert replay.verified, replay.errors
+    assert all(event.actor == "agent:async" for event in replay.events)