Skip to main content
Glama
phionyx-pipeline-mcp

phionyx-pipeline-mcp

phionyx-pipeline-mcp

A self-governance MCP server for Claude Code — gates the agent's own "I fixed this / I tested that / this code path changed" declarations against git diff truth and a deterministic gate.

phionyx-pipeline-mcp solves a less-discussed agent-trust problem: when an AI coding agent reports back on its own work, that report is itself a trust object. Without verification, you accept it on faith.

This package gives any MCP-capable host (Claude Desktop, Cursor, Zed, VS Code, JetBrains) a six-tool surface that turns those self-reports into reviewable evidence — coverage of paths claimed vs. paths actually touched, severity-weighted evidence taxonomy, drift tracking across a session, and an explicit pass | regenerate | reject directive before the agent claims "done."

Where this sits in the Phionyx stack

Phionyx ships three distinct things, each with its own version line. This package is the gate:

  • Engine — phionyx-core (current release on PyPI): the deterministic runtime (46-block canonical pipeline, state vector, kill switch, HITL, ethics/safety gates, audit-record contracts — the signed chain is demonstrated at the MCP boundary today).

  • Gate — phionyx-pipeline-mcp (this package): the inward-facing self-claim gate described here. It verifies what the agent says about its own work against git diff truth and a deterministic gate. v0.3.1 adds opt-in, default-off evidence binding (the require_tool directive + continuity binding) on top of the claim-grounding gate. It is the claim-governance layer of the Phionyx governance stack; phionyx-mcp-server (current release on PyPI) is the outward MCP trust boundary.

  • Format — the AI Runtime Evidence Protocol (AIREP): an experimental, vendor-neutral open format for an AI decision receipt — one signed, hash-chained, offline-checkable record per AI runtime decision, readable by anyone and tied to no vendor. Phionyx's Reasoned Governance Envelope (RGE) is developed alongside AIREP; a conformant projection between the two is not implemented (measured 2026-08-06: AIREP's own reference verifier rejects an RGE envelope handed to it directly). AIREP is a proposed format, not a ratified standard. AIREP v0.2.0-beta.1 was published on 9 September 2026 as an experimental prerelease: it ships a first-party Python producer for Decision, Control, Execution and Effect artifacts, runnable lifecycle examples and structured reconciliation; the v0.1 line remains frozen and supported. External implementation results are version- and role-specific — an independently authored producer measured against frozen v0.1.2, and an independently implemented consumer/verifier measured against an earlier v0.2 handoff — and they do not establish same-beta producer-to-consumer interoperability. See ai-runtime-evidence-protocol.

These three version lines — engine v0.9.1, gate v0.3.1, and AIREP v0.2.0-beta.1 (experimental prerelease; v0.1 frozen and supported) — are never cross-attributed.

Related MCP server: did-it

How it works — three-stage verification

Stage 1: LLM declaration   →   Stage 2: Repo truth          →   Stage 3: Deterministic gate
  "I fixed X, tested Y,         git diff parsed; functions       evidence + recency + revision
   affected paths a,b,c"        extracted; cross-checked         thresholds → directive

The gate is deterministic. Stage 1 (the agent's input) is stochastic. Stage 2 — verifying the agent's path declarations against the actual git diff — is what narrows the gap.

(These three stages are internal to the gate's verification flow. They are unrelated to the broader Phionyx governance-stack layers.)

Where this fits on phionyx.ai

This package surfaces under phionyx.ai/bounded-authority — the safety-first AI providers entry. It is the inward-facing self-claim gate that verifies the agent's own "I fixed / I tested / this code path changed" narration against the repository's actual diff and a deterministic gate, producing a pass | regenerate | reject directive paired with reviewer-runnable evidence.

Companion package: phionyx-mcp-server

This package is the inward-facing layer: it gates what the agent says about its own work.

A companion package, phionyx-mcp-server (current release on PyPI), is the outward-facing layer: it sees the host calling a third-party MCP server and signs evidence of that call (descriptor hash, drift detection, audit chain).

When both packages are installed and registered with the same Claude Code host, they agree on a single trace_id per session via PHIONYX_TRACE_ID (with ~/.phionyx/active_trace file fallback). One conversation = one trace = a joined view of the third-party tool calls and agent self-claim gate decisions recorded in that session.

phionyx_session_report (this package) surfaces the server-MCP envelope chain head + validity inline, so a reviewer can see both layers in one JSON.

Install

# This package only:
pip install phionyx-pipeline-mcp

# With the outward-facing companion (recommended for full session evidence):
pip install "phionyx-pipeline-mcp[mcp-server-integration]"

Register with Claude Code

Add to .claude/mcp.json in your project:

{
  "mcpServers": {
    "phionyx-pipeline": {
      "command": "phionyx-pipeline-mcp"
    },
    "phionyx-mcp-server": {
      "command": "phionyx-mcp-server"
    }
  }
}

Both servers will share ~/.phionyx/active_trace by default.

Tool surface

Tool

When to call

phionyx_verify_claim

Before claiming "fixed" or "done." Takes the claim, the evidence, the evidence type, paths tested, paths affected. Returns a directive (pass / regenerate / reject) plus the reasons.

phionyx_causal_trace

While debugging. Validates a causal chain from symptom to root cause. Chains shorter than 3 links or weaker than 40% code-specificity get a deepen directive.

phionyx_response_gate

Before committing or deploying. Action-type-specific thresholds: claim_fixed is strictest, deploy is very strict, default is standard.

phionyx_verify_paths

Cross-check claimed-affected and claimed-tested paths against git diff. Flags underreporting.

phionyx_checkpoint

Lightweight snapshot — call frequently to keep the session telemetry dense.

phionyx_session_report

End-of-session summary: claims, directives, drift metrics, evidence taxonomy, and (if the server MCP is installed) the audit chain head + validity.

Reviewer-runnable CLI (phionyx)

pip install phionyx-pipeline-mcp also installs a phionyx command that exposes the same three-stage verification as the MCP server, but reachable from a plain terminal — no Claude Code / MCP host required.

Four subcommands:

# 1. Verify a self-claim against the gate
phionyx verify-claim \
    --claim "scenario continuation bug is fixed" \
    --evidence "12 scenes played, quest_complete=True" \
    --type integration_test \
    --tested "src/foo/regression.py::regression_handler" \
    --affected "src/foo/regression.py"

# 2. Aggregate the audit chain over the last N days
phionyx audit --days 30
phionyx audit --days 7 --json   # machine-readable

# 3. Replay a specific session's timeline by trace_id (or unique prefix)
phionyx replay --trace <trace_id_or_session_id_prefix>

# 4. The killer demo — reviewer reproduces the failure mode in 5 seconds
phionyx demo broken-test-disabled

The demo is the entry point a reviewer should try first. It runs a scripted scenario in which Claude claims a fix passes and the gate detects that no tested-path coverage exists and the evidence weight is the bottom of the taxonomy — and rejects the claim. The exit code is 2 because the gate did its job.

Exit codes:

Code

Meaning

0

pass / proceed — gate accepts the claim

1

regenerate / rewrite / hedge — claim must be revised

2

reject — gate rejects outright

3

error (invalid args, missing telemetry, internal failure)

CLI and MCP-host invocations write to the same telemetry directory (PHIONYX_PROJECT_ROOT/data/mcp_telemetry/), so phionyx audit and phionyx replay see prior sessions started inside Claude Code or any other MCP-capable host.

Evidence taxonomy

Not all evidence is equal. The gate weights confidence by the type of test that backs a claim:

Evidence type

Weight

browser_test

0.9

manual_repro

0.8

integration_test

0.7

endpoint_test

0.6

log_inspection

0.5

unit_test

0.4

code_review

0.3

none

0.0

A claim_fixed action with evidence_type=none will be rejected outright; even high confidence values cannot compensate for missing test evidence.

Pre-commit gate helper

A standalone phionyx-pipeline-check-gate CLI reads the recent telemetry and exits non-zero if the most recent gate directive was reject or regenerate. Drop it into your pre-commit hook to enforce the discipline:

phionyx-pipeline-check-gate --mode pre-commit

Exit codes: 0 pass · 1 failed (recent reject/regenerate) · 2 no telemetry (warn-only).

Shared-trace contract

When phionyx-mcp-server is also installed, this package extends phionyx_session_report's output with:

{
  "trace_id": "<active trace>",
  "mcp_envelope_chain": {
    "trace_id": "<same trace>",
    "count": 7,
    "head_hash": "sha256:...",
    "valid": true,
    "broken_at": null
  }
}

The integration is read-only — this package imports FilesystemEnvelopeStore + verify_chain from phionyx-mcp-server and reads its chain. No cross-package write coupling. When the server package isn't installed, the field reports "phionyx-mcp-server not installed" and the rest of the report continues to work.

Tests

pip install -e ".[test]"
pytest tests/ -q

License

AGPL-3.0-or-later. See LICENSE.

See also

MCP compatibility (0.3.2 candidate)

This entry point uses mcp.server.fastmcp from MCP 1.x. Installation is now bounded to mcp>=1.27.0,<2; MCP 2.x is not supported by this entry point. The upper bound prevents a successful dependency install followed by a startup import failure. It does not claim compatibility with every future MCP 1.x release.

Available Tools

6 tools
phionyx_causal_traceB

Validate a causal debugging chain. Call when investigating a bug.

Args: symptom: What the user observes (e.g. "scenarios end at scene 2") causal_chain: Arrow-separated chain from symptom to root cause (e.g. "0 choices shown → play page reads res.choices → play_card returns empty → make_choice uses wrong key")

Inputs: symptom (required), causal_chain (required). Returns: object

phionyx_checkpointA

Lightweight physics state snapshot. Call frequently — after completing any subtask, before switching context, or when reporting progress.

This is cheap (no git diff, no verification). Use it to keep the telemetry timeline dense so the founder can track session physics in real time.

Args: context: Brief note of what you're doing (e.g. "finished implementing selector")

Inputs: context. Returns: object

phionyx_response_gateA

Response revision gate with action-type-specific thresholds. Call before committing.

Directives: pass | hedge | regenerate | block | require_tool (P1). Different action types trigger different threshold profiles:

  • claim_fixed: strictest (entropy_reject=0.90, phi_min=0.08)

  • deploy: very strict (entropy_reject=0.85, phi_min=0.10)

  • default: standard pipeline thresholds

  • require_tool (P1): for factual action_types (claim_fixed/claim_working/deploy) with no externally-bound evidence, the result carries require_tool{triggered}; with PHIONYX_GATE_REQUIRE_TOOL_ENFORCE=1 an otherwise-passing directive becomes 'require_tool' — bind real evidence (run a tool) before the claim can pass.

  • continuity_binding (P2): the result carries continuity_binding{bound,stale,dds} from the session constraint ledger. compute_dds(confidence, continuity_score) flags "confident while binding unbound/stale"; with PHIONYX_GATE_CONTINUITY_ENFORCE=1 an otherwise-passing directive is downgraded to 'hedge' (re-bind constraints).

  • ask_question / make_claim (Block 15 short-circuit): each identifier in artifact_references is scored against the read-knowledge boundary by phionyx_core's KnowledgeBoundaryDetector; any source not present in artifact_paths_read is assessed outside the boundary → directive='regenerate' with the ungrounded set + the core's reasoning surfaced. Use 'ask_question' BEFORE asking about a named artifact; use 'make_claim' BEFORE asserting what a named source (file, paper, theory, config) says/contains.

Args: action_type: claim_fixed | claim_working | deploy | refactor | investigate | ask_question | make_claim confidence: Your confidence 0.0-1.0 evidence_count: Number of independent test/verification points evidence_type: Type of evidence (see phionyx_verify_claim for options) affects_user_facing: Whether this change is visible to end users artifact_references: Comma-separated artifact identifiers mentioned in the question/claim (file paths, URLs, issue numbers, named sources). Only meaningful when action_type in {'ask_question', 'make_claim'}. artifact_paths_read: Comma-separated artifact identifiers actually opened this turn (Read tool results, gh issue view output, WebFetch URLs). Only meaningful when action_type in {'ask_question', 'make_claim'}.

Inputs: confidence (required), action_type (required), evidence_count (required), evidence_type, +3 more. Returns: object

phionyx_session_reportA

Session summary: claims, directives, drift metrics, evidence taxonomy, physics state.

Inputs: no named parameters. Returns: object

phionyx_verify_claimA

Verify a completion claim using three-layer verification. Call BEFORE saying 'fixed' or 'done'.

Layer 1: Parse your declarations (claim, evidence, paths) Layer 2: Cross-check paths against git diff (input verification) Layer 3: Physics gate (phi + entropy + revision thresholds)

P1 require_tool: if the claim asserts a factual / external-state fact (live / deployed / version / merged / tests-pass / endpoint-up) and the evidence is not externally bound (only code_review/none, not a run/inspection), the result carries require_tool{triggered,...}; with PHIONYX_GATE_REQUIRE_TOOL_ENFORCE=1 an otherwise- passing directive becomes 'require_tool' — go bind the evidence (run the tool) first.

Args: claim: What you're claiming (e.g. "scenario continuation bug is fixed") evidence: What test output proves it (e.g. "12 scenes played, quest_complete=True") evidence_type: Type of evidence — determines confidence weight. One of: browser_test, manual_repro, integration_test, endpoint_test, log_inspection, unit_test, code_review, none code_paths_tested: Comma-separated functions/endpoints you actually tested code_paths_affected: Comma-separated functions/endpoints affected by the change referenced_sources: (P2b) Comma-separated sources the claim cites/depends on (roadmap, spec, a module/file). Optional. read_paths: (P2b) Comma-separated sources actually Read/bound THIS turn. Optional — when BOTH this and referenced_sources are given, the gate checks read_but_not_bound (a cited source not bound this turn → continuity violation; with PHIONYX_GATE_CONTINUITY_ENFORCE=1 → 'regenerate'). Omit (leave null) when no read-set is available → check is skipped (non-regressive).

Inputs: claim (required), evidence (required), evidence_type (required), code_paths_tested (required), +3 more. Returns: object

phionyx_verify_pathsA

Cross-check your claimed code paths against git diff reality. Call to verify your own declarations.

Compares what you say you affected/tested against what git diff actually shows. Returns discrepancies, trust score, and warnings about underreporting.

Args: claimed_affected: Comma-separated paths you claim are affected claimed_tested: Comma-separated paths you claim to have tested

Inputs: claimed_tested (required), claimed_affected (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation4/5

    Tools have distinct purposes, though response_gate and verify_claim share some verification concepts. Detailed descriptions help differentiate them.

    Naming Consistency5/5

    All tools start with 'phionyx_' and use snake_case. Despite some being nouns and others verb-noun, the pattern is consistent.

    Tool Count5/5

    Six tools is an appropriate number for a pipeline validation server, covering key operations without being excessive.

    Completeness4/5

    The set covers causal debugging, state snapshots, gates, verification, and reporting. Minor gaps like explicit rollback may exist, but core workflows are supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Audits coding agents' claimed actions against the actual Git working tree, blocking completion if any claimed changes are unverified.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI coding agents to submit work for external review before declaring a task done, receiving evidence-backed fix lists and verdicts based on git-measured changes and calibrated quality scoring.
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables Claude to independently check an AI agent's work in a local git repository by recording a baseline, running only the checks relevant to the changed files, and cross-checking what the agent claimed. Returns a compact, evidence-labelled report with a verdict and a ready-to-paste next prompt, so unverified success claims can't slip through.
      8
      MIT