pikopod mcp speaks JSON-RPC 2.0 over stdin and stdout, one message per line, protocol version 2024-11-05. It supports initialize, ping, tools/list and tools/call. Every call returns a result with a verdict and, on UNVERIFIABLE, a reason. Unknown arguments are refused. See Coding agents for the client setup and the verdict contract.
Result shape:
Readers
spec_diff
Diff two spec versions as declared drift with a severity per finding. It sees only what the documents declare; behaviour a provider changed without updating its spec is invisible here.FINDINGS when anything at or above fail_on exists, else CLEAN with lower findings attached. data carries fail_on, summary and findings with fingerprints.
drift_events
Drift events and incidents the agent recorded for an upstream. Reports only changes observed in traffic that passed warmup.FINDINGS when events exist. UNVERIFIABLE when the upstream has no baselines yet, or when no endpoint has passed warmup, with the samples seen and the gate. CLEAN otherwise, naming how many endpoint families are warmed up and how many are still warming. Every result carries a warmup block: gate values, per-family samples, and the standing notice that an endpoint with no traffic is invisible.
replay_ci
The CI gate: recorded traffic against frozen baselines, offline.FINDINGS lists drift per endpoint. CLEAN means every gated recording matched. UNVERIFIABLE with a reason when an upstream has no baselines or no recordings. Recordings made before an endpoint warmed up are skipped and counted.
conformance
Whether an upstream’s recorded responses obey its imported spec.FINDINGS lists violations. Checks whose evidence the sanitizer redacted are counted as unverifiable and never scored as passes. With no violations and some unverifiable checks the verdict is UNVERIFIABLE.
reproduce
Turn a recorded incident into a runnable scenario pack and run it against the local sandbox. Writes one pack file underdata_dir/scenarios and touches nothing else.
FINDINGS with reproduced: true means the failure now happens locally, and data carries the pack name and path. UNVERIFIABLE when the pack ran but the failure did not recur, or when no sandbox exists to run it against. The request is rebuilt from a redacted recording, so a 4xx that depended on the exact body may not recur.
scenario_list
Which failure archetypes bind to a sandbox’s API, and why the rest do not.CLEAN when at least one archetype binds. UNVERIFIABLE when none does, with every reason attached. data carries the archetypes, saved packs, and endpoint count.
scenario_run
Run archetypes or packs against a throwaway copy of a sandbox. The served sandbox is untouched, and this drives pikopod’s own requests, not the caller’s application.CLEAN when all pass, FINDINGS when any fails, ERROR when a step could not execute. data.runs carries each scenario’s result.
get_requests
What the caller’s application actually sent to a running sandbox: the request journal, newest last, with identifiers tokenized.
Needs
pikopod up. When older entries were evicted the result says so, because ordering claims across the gap cannot be proven.
Controls over the running sandbox
These needpikopod up and act on a local fake, never on a provider.
set_mode
Put the running sandbox into a scenario’s failure state so the caller’s own tests meet it. The mode stands untilclear_mode.
Scenarios that have no standing state are refused with the reason.
clear_mode
Clear the standing mode and every fault it armed.arm_fault
Arm one fault. HTTP faults needmethod and path; webhook faults match by event.
clear_faults
Clear faults matchingmethod and path, or every fault when both are omitted.
emit_webhook
Fire a declared event, signed and shaped the way the sandbox’s spec declares, to the sandbox’s configured webhook URL. Undeclared events are refused.Deliberately absent
fix, import, chaos, ack, accept, up and every reset. They stay human-operated commands, and a test fails the build if any of them appears in the tool list.