Skip to main content
Glama
senih25

HERMX ProofGate

by senih25
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Recall, guarded by HERMX ProofGate

A voice study coach for Alexa+ where routine reviews run instantly and anything that changes a deck waits for your exact approval.

Architecture

The idea

Voice assistants are becoming agents: they don't just answer, they change things. Most changes are small and reversible, and asking for confirmation on every one would make a voice product unbearable. A few changes are consequential, and an agent must never treat "yeah, go ahead" as authorization for those.

Recall is a hands-free spaced-repetition coach that makes this split explicit:

Tier

Tools

Rule

Routine

next_review, grade_answer, progress

Runs immediately. Every effect still extends a SHA-256 audit chain.

Consequential

plan_change → approve_change → execute_change → verify_change for import_deck, reset_topic, delete_topic

Nothing happens until the user says the plan's exact phrase, for example "approve 7 F 3 A 9 C". Execution re-checks the topic's digest and fails closed if it changed after planning. Verification compares the result with the digest predicted at plan time.

proofgate_status exposes the contract, the audit-chain head and the current state digest.

Related MCP server: agent-mcp-workflow-platform

What happens in a session

  1. "Learn this as mcp" creates a plan: Recall reads the text, builds cloze flashcards, and predicts the topic's SHA-256 digest after the import. Nothing is written yet.

  2. "Yes, go ahead" is rejected (APPROVAL_MISMATCH), and the rejection is logged.

  3. "Approve 7 F 3 A 9 C" approves that one plan. Recall re-checks the topic, imports, then verifies the result against the predicted digest.

  4. "Quiz me" and spoken answers are graded (SM-2 scheduling) without confirmation prompts.

  5. If a deck changes between planning and execution (for example, you review a card after asking for a reset), the old approval is refused with STATE_DRIFT.

Repository

Path

What it is

server.py

Python reference MCP server (official MCP Python SDK 1.28.1, FastMCP), Streamable HTTP at /mcp, and the simulator UI at /

proofgate_core.py

The gate: risk tiers, plan-bound approval, drift check, verification, hash-chained audit

learning.py, srs.py

Deterministic cloze-card extraction, spoken-answer grading, SM-2 scheduling

worker/

Cloudflare Worker port used for the free live demo (Durable Object sandbox per visitor)

web/

Alexa+ experience simulator; the page itself is an MCP client of /mcp

demo_flow.py

12-check conformance run using the official MCP Python client

tests/

Safety and effect-boundary tests, plus a Python/JavaScript parity test

Card extraction is deterministic (no LLM, no network), which is what lets the server predict the post-change digest at plan time.

Run locally

Requirements: Python 3.11+, optionally Node.js for the parity test.

python -m venv .venv
# Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"
python server.py            # MCP at http://127.0.0.1:8767/mcp, simulator at http://127.0.0.1:8767/

Verify:

pytest -q                                              # 16 tests
python demo_flow.py                                    # against the local server
python demo_flow.py --url "https://hermx-proofgate-recall.senih-bayankulu25.workers.dev/mcp?sandbox=my-test"

Any MCP client works; for example, point the MCP Inspector at the live /mcp URL with the Streamable HTTP transport. Add ?sandbox=<name> to get your own isolated state.

Deploy your own live demo (Cloudflare free plan)

cd worker
npx wrangler deploy

The Worker serves web/ as static assets and handles /mcp itself: stateless JSON-RPC over Streamable HTTP (JSON response mode, no server-initiated SSE), one SQLite-backed Durable Object per sandbox.

What is and isn't claimed

  • Claimed and verified: a self-hosted MCP server on protocol 2025-11-25 over Streamable HTTP, discoverable tools, the gate behaviour above, and the same behaviour on the live Worker (see EVIDENCE.md).

  • Not claimed: a completed connection inside the production Alexa+ app. The simulator stands in for Alexa+'s voice layer, which the track explicitly allows.

  • Not entered: the AWS Builder mini challenge. This build uses no AWS services.

Public clean-room boundary

This repository is a public clean-room demonstration of the ProofGate approval pattern for MCP workflows. It is not the commercial PBT-G control plane and does not include private browser or terminal enforcement internals, credentials, provider mappings, customer data, deployment secrets, private prompts, pricing logic or production runbooks.

The repository is intended to show the approval-gated workflow pattern at a capability level: plan, exact approval, execute, verify and audit evidence. Commercial PBT-G implementation details remain outside this repository. See SECURITY.md.

The learning-coach half began as a separate prototype, senih25/recall-alexa-mcp, and was merged here so the submission is one product.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityNo data
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • notary-mcp

    salmanneedsajob
    F
    license
    Not graded
    quality
    C
    maintenance
    An MCP approval gate that ensures agents execute only human-approved, hash-verified actions, providing fail-closed consent for consequential operations.
    -

  • alexa-plus

    guptachetan1995
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables smart home automation via MCP with human-in-the-loop approval gates, providing device discovery, state queries, policy checks, and proposal-based execution of actions and scenes that only proceed after explicit user confirmation, with full audit logging.
    MIT