Implementation Phases

Mcph was built in 10 phases, tracked as GitHub issues with a state-machine label system.

Phase Details

Phase 0: Scaffold

Project structure, pyproject.toml, CI pipeline (ruff, mypy, pytest), AGENTS.md.

Phase 1: Parser & AST

Hand-written recursive descent parser producing an AST with 15 node types. Supports all DSL keywords: CONNECT, INITIALIZE, LIST, CALL, READ, ASSERT, CAPTURE, REQUIRE_CAPABILITY, SHUTDOWN.

Phase 2-3: Transports

Stdio — async subprocess with newline-delimited JSON-RPC framing. Streamable HTTP — httpx-based, Mcp-Session-Id header tracking.

Phase 4: Protocol Engine

JSON-RPC 2.0 envelopes, sequential request IDs, response validation, initialize → notifications/initialized handshake.

Phase 5: Assertion Engine

JSONPath extraction, regex matching, fuzzy type matchers, structural dict subset equality, clear error messages.

Phase 6: Variable Capture

JSONPath + regex extraction, recursive template resolution through dicts and lists, nested variable path support.

Phase 7: Runtime

Full execution pipeline: parse → connect → initialize → execute → report. Capability gating, soft/hard failure modes.

Phase 8-9: Reporting & CLI

Console, JUnit XML, JSON reporters. Typer CLI with --transport, --command, --url, --reporter, --env, --timeout flags.

Phase 10: Integration

E2E test against reference MCP echo server. Full conformance suite example.

Test Suite

139 tests across 8 test files:

• 64 parser tests (all keywords, edge cases, full conformance suite)
• 12 stdio transport tests
• 6 HTTP transport tests
• 10 protocol engine tests
• 17 assertion engine tests
• 12 capture tests
• 8 reporter tests
• 5 runtime integration tests
• 5 CLI + E2E tests

Ruff clean, mypy strict, all passing.