Skip to content

Commit 2c2b504

Browse files
ProfRandom92ProfRandom92
authored
feat: add lightweight MCP replay context layer
Adds a lightweight deterministic MCP-compatible replay-aware context layer with compact replay payload generation, validation, prompt-context rendering, file-backed context helpers, deterministic example artifact, and regeneration validation.
1 parent 003e270 commit 2c2b504

10 files changed

Lines changed: 995 additions & 0 deletions

‎artifacts/mcp_context_layer_example.json‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
{
2+
"artifact_id": "mcp_context_layer_example_v1",
3+
"evaluation_mode": "deterministic",
4+
"example": {
5+
"fixture_id": "mcp_trace_replay_v1",
6+
"prompt_context": "task: mcp_trace_replay_v1\nadmissible: true\nconstraints:\n- execute_external_action:requires_human_approval\n- execute_external_action:requires_validation_passed\nrequired_order:\n- user_request_received\n- capability_scope_checked\n- tool_schema_validated\n- read_context\n- validate_external_action\n- execute_external_action\n- verify_result\n- recovery_path_registered\ndependencies:\n- capability_scope_checked -> execute_external_action\n- capability_scope_checked -> tool_schema_validated\n- capability_scope_checked -> validate_external_action\n- execute_external_action -> recovery_path_registered\n- execute_external_action -> verify_result\n- read_context -> validate_external_action\n- tool_schema_validated -> read_context\n- user_request_received -> capability_scope_checked\n- validate_external_action -> execute_external_action\nblockers:\n- capability_scope_checked -> execute_external_action\nrecovery:\n- execute_external_action -> recovery_path_registered",
7+
"replay_payload": {
8+
"blockers": [
9+
[
10+
"capability_scope_checked",
11+
"execute_external_action"
12+
]
13+
],
14+
"constraints": [
15+
"execute_external_action:requires_human_approval",
16+
"execute_external_action:requires_validation_passed"
17+
],
18+
"dependency_chains": [
19+
[
20+
"capability_scope_checked",
21+
"execute_external_action"
22+
],
23+
[
24+
"capability_scope_checked",
25+
"tool_schema_validated"
26+
],
27+
[
28+
"capability_scope_checked",
29+
"validate_external_action"
30+
],
31+
[
32+
"execute_external_action",
33+
"recovery_path_registered"
34+
],
35+
[
36+
"execute_external_action",
37+
"verify_result"
38+
],
39+
[
40+
"read_context",
41+
"validate_external_action"
42+
],
43+
[
44+
"tool_schema_validated",
45+
"read_context"
46+
],
47+
[
48+
"user_request_received",
49+
"capability_scope_checked"
50+
],
51+
[
52+
"validate_external_action",
53+
"execute_external_action"
54+
]
55+
],
56+
"recovery": [
57+
[
58+
"execute_external_action",
59+
"recovery_path_registered"
60+
]
61+
],
62+
"required_order": [
63+
"user_request_received",
64+
"capability_scope_checked",
65+
"tool_schema_validated",
66+
"read_context",
67+
"validate_external_action",
68+
"execute_external_action",
69+
"verify_result",
70+
"recovery_path_registered"
71+
],
72+
"task": "mcp_trace_replay_v1"
73+
},
74+
"source_fixture_path": "fixtures/mcp_trace_replay_v1/original",
75+
"validation": {
76+
"admissible": true,
77+
"failure_labels": [],
78+
"issues": []
79+
}
80+
},
81+
"external_apis": "none",
82+
"generated_by": "McpContextLayerExampleArtifactGenerator",
83+
"llm_judges": "none",
84+
"schema_version": "mcp_context_layer_example.v1",
85+
"version": "1.0"
86+
}

‎docs/mcp_context_layer.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# MCP Context Layer
2+
3+
CompText V7 includes a lightweight replay-aware context layer for MCP-style
4+
runtime systems. The layer preserves compact operational context for
5+
deterministic replay validation; it does not execute tools, orchestrate agents,
6+
call external APIs, or judge semantic quality.
7+
8+
## Scope
9+
10+
The context layer is additive to the existing replay fixtures and contracts. It
11+
builds a compact payload from explicit trace, state, and dependency-graph fields:
12+
13+
```json
14+
{
15+
"task": "mcp_trace_replay_v1",
16+
"constraints": [
17+
"execute_external_action:requires_human_approval",
18+
"execute_external_action:requires_validation_passed"
19+
],
20+
"required_order": [
21+
"capability_scope_checked",
22+
"tool_schema_validated",
23+
"read_context",
24+
"validate_external_action",
25+
"execute_external_action"
26+
],
27+
"blockers": [
28+
["capability_scope_checked", "execute_external_action"]
29+
],
30+
"dependency_chains": [
31+
["validate_external_action", "execute_external_action"]
32+
],
33+
"recovery": [
34+
["execute_external_action", "recovery_path_registered"]
35+
]
36+
}
37+
```
38+
39+
## Public API
40+
41+
- `build_replay_payload(trace)` extracts compact deterministic commitments.
42+
- `render_prompt_context(payload)` renders a compact prompt-safe text view.
43+
- `validate_replay_payload(payload)` validates replay admissibility from explicit
44+
payload fields.
45+
- `ContextStore(root).save_context(trace)` writes a stable JSON payload.
46+
- `ContextStore(root).load_context(task_id)` restores the compact payload.
47+
- `save_context(trace, store_dir=...)` and `load_context(task_id, store_dir=...)`
48+
provide module-level convenience wrappers.
49+
50+
## Deterministic checks
51+
52+
`validate_replay_payload` detects:
53+
54+
- missing preserved constraints as `CONSTRAINT_DRIFT`
55+
- dependency-order drift as `TOOL_ORDER_VIOLATION`
56+
- dependency collapse as `DEPENDENCY_CHAIN_BREAK`
57+
- missing recovery paths as `RECOVERY_PATH_LOSS`
58+
59+
The validator uses exact strings, ordered lists, and explicit dependency edges.
60+
It performs no embedding lookup, fuzzy scoring, probabilistic reasoning, LLM
61+
judging, runtime blocking, or policy enforcement.
62+
63+
## Prompt context rendering
64+
65+
`render_prompt_context(payload)` produces a token-light text form without dumping
66+
raw trace, state, or dependency-graph documents:
67+
68+
```text
69+
task: mcp_trace_replay_v1
70+
admissible: true
71+
constraints:
72+
- execute_external_action:requires_validation_passed
73+
required_order:
74+
- validate_external_action
75+
- execute_external_action
76+
dependencies:
77+
- validate_external_action -> execute_external_action
78+
recovery:
79+
- execute_external_action -> recovery_path_registered
80+
```
81+
82+
## Example artifact
83+
84+
`artifacts/mcp_context_layer_example.json` is a fixture-bound deterministic
85+
example generated from `fixtures/mcp_trace_replay_v1/original`. It contains the
86+
compact replay payload, prompt-context rendering, and validation result for the
87+
baseline MCP trace replay fixture.
88+
89+
## Relationship to MCP
90+
91+
This layer augments context integrity for MCP-compatible systems. It is not an
92+
MCP implementation and does not replace MCP transport, runtime execution, or
93+
tool semantics.

‎scripts/generate_mcp_context_layer_example_artifact.py‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
"""Generate a deterministic MCP context-layer example artifact."""
2+
3+
from __future__ import annotations
4+
5+
import json
6+
import sys
7+
from pathlib import Path
8+
from typing import Any
9+
10+
REPO_ROOT = Path(__file__).resolve().parents[1]
11+
if str(REPO_ROOT) not in sys.path:
12+
sys.path.insert(0, str(REPO_ROOT))
13+
14+
from src.comptext_v7.mcp import build_replay_payload, render_prompt_context, validate_replay_payload
15+
16+
ARTIFACT_ID = "mcp_context_layer_example_v1"
17+
EXAMPLE_FIXTURE_ID = "mcp_trace_replay_v1"
18+
EXAMPLE_FIXTURE_PATH = REPO_ROOT / "fixtures" / EXAMPLE_FIXTURE_ID / "original"
19+
OUTPUT_PATH = REPO_ROOT / "artifacts" / "mcp_context_layer_example.json"
20+
21+
22+
def _load_json(path: Path) -> dict[str, Any]:
23+
return json.loads(path.read_text(encoding="utf-8"))
24+
25+
26+
def _load_fixture_context() -> dict[str, Any]:
27+
return {
28+
"task": EXAMPLE_FIXTURE_ID,
29+
"trace": _load_json(EXAMPLE_FIXTURE_PATH / "trace.json"),
30+
"state": _load_json(EXAMPLE_FIXTURE_PATH / "state.json"),
31+
"dependency_graph": _load_json(EXAMPLE_FIXTURE_PATH / "dependency_graph.json"),
32+
}
33+
34+
35+
def build_mcp_context_layer_example_artifact() -> dict[str, Any]:
36+
replay_payload = build_replay_payload(_load_fixture_context())
37+
validation = validate_replay_payload(replay_payload)
38+
prompt_context = render_prompt_context({**replay_payload, "validation": validation})
39+
40+
return {
41+
"artifact_id": ARTIFACT_ID,
42+
"evaluation_mode": "deterministic",
43+
"example": {
44+
"fixture_id": EXAMPLE_FIXTURE_ID,
45+
"prompt_context": prompt_context,
46+
"replay_payload": replay_payload,
47+
"source_fixture_path": f"fixtures/{EXAMPLE_FIXTURE_ID}/original",
48+
"validation": validation,
49+
},
50+
"external_apis": "none",
51+
"generated_by": "McpContextLayerExampleArtifactGenerator",
52+
"llm_judges": "none",
53+
"schema_version": "mcp_context_layer_example.v1",
54+
"version": "1.0",
55+
}
56+
57+
58+
def generate_mcp_context_layer_example_artifact(output_path: Path = OUTPUT_PATH) -> Path:
59+
artifact = build_mcp_context_layer_example_artifact()
60+
output_path.parent.mkdir(parents=True, exist_ok=True)
61+
output_path.write_text(json.dumps(artifact, indent=2, sort_keys=True) + "\n", encoding="utf-8")
62+
return output_path
63+
64+
65+
def main() -> int:
66+
output_path = generate_mcp_context_layer_example_artifact()
67+
print(output_path.relative_to(REPO_ROOT).as_posix())
68+
return 0
69+
70+
71+
if __name__ == "__main__":
72+
raise SystemExit(main())

‎src/comptext_v7/mcp/__init__.py‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
"""Replay-aware context layer for MCP-style runtime systems."""
2+
3+
from .context_store import ContextStore, load_context, save_context
4+
from .replay_payload import build_replay_payload, render_prompt_context
5+
from .validator import validate_replay_payload
6+
7+
__all__ = [
8+
"ContextStore",
9+
"build_replay_payload",
10+
"load_context",
11+
"render_prompt_context",
12+
"save_context",
13+
"validate_replay_payload",
14+
]

0 commit comments

Comments
 (0)