Skip to main content
Glama
adimalkar

ReproGate

by adimalkar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

ReproGate

CI CodeQL M8ven Verified License

ReproGate is an action-contract layer for MCP tool execution. Its intended contract binds a policy decision or human approval to the exact tool, schema, arguments, authority, policy, and observed workspace state, then makes that binding available to an execution receipt. The current configured path does not yet enforce all of those fields at a durable write boundary.

The goal is narrower than “another MCP gateway”: make a tool action independently inspectable and make approval invalid as soon as the proposed action changes.

Current status: Phase 2 reference path and Phase 3 prepared Git promotion journal

This repository contains the action-contract kernel, a plan-only MCP server by default, and the first opt-in Phase 2 execution boundary. It can:

  • discover tools through a small stable façade;

  • build deterministic, digest-bound action envelopes from an operator-controlled catalog;

  • return explainable allow, approval_required, or deny decisions;

  • issue and validate one-use capability tokens bound to an exact envelope;

  • create tamper-evident, hash-chained decision records.

  • persist plans and atomically consume approvals in SQLite;

  • re-check a live downstream MCP schema before one stdio call;

  • recover interrupted calls as indeterminate;

  • emit and independently verify signed Execution Receipt v1 records.

  • load a strict execution configuration with environment-referenced secrets;

  • bind and verify a downstream artifact before process spawn;

  • hash bounded filesystem manifests without retaining file contents.

  • bind a proposed patch digest to a read-only, clean Git worktree witness and exact path list.

  • stage a Git patch in a disposable index and record a host-side, revocable approval of its reviewed effect.

  • bind that approval to a persisted exact-action Git intent, current catalog, policy, and repository configuration.

  • authenticate operator-key decisions about an exact staged Git effect and atomically record linked approval evidence or a durable denial.

  • bind explicit V2 intents to a distinct unchecked-out destination without reinterpreting V1 approvals;

  • prepare exact candidate commit objects without moving protected refs, HEAD, index or worktree;

  • retain a cooperative host ownership fence across worker death, with exact-owner quiescent release.

  • permanently reserve one linked signed Git approval as immutable prepared intent in the existing SQLite ledger, with guarded raw revocation.

Execution is deliberately disabled in the default server and requires explicit executor wiring. The configured path is not a sandbox or a production authorization boundary. Git review authenticates a configured signing key and exact decision, not human presence or inspection. The host owns configuration, databases and key isolation; protected-ref promotion is not implemented. See the Git change contract and limits.

Related MCP server: Living Stack MCP — Retired Beta Listing

Try it

Requirements: Node.js 22.13 or newer; Git workflows require Git 2.45 or newer. CI tests the maintained Node.js 22 and 24 release lines on Linux, macOS, and Windows.

npm install
npm run check
npm run demo

Run the MCP server over stdio:

npm run build
node dist/src/cli.js serve

The Phase 2 APIs are exported for explicit application wiring:

  • SqliteExecutionStore for durable plans, one-use approvals, and execution state;

  • StdioMcpConnector for configured downstream processes;

  • ReproGateExecutor for the fail-closed execution sequence;

  • signExecutionReceipt and verifyExecutionReceipt for receipt handling.

Approval issuance is intentionally out of band and reads its secret from the environment rather than command-line arguments:

REPROGATE_CAPABILITY_SECRET='<at-least-32-byte-secret>' \
  node dist/src/cli.js approve --config /absolute/path/reprogate.json '<action-id>'

REPROGATE_RECEIPT_SECRET='<at-least-32-byte-secret>' \
  node dist/src/cli.js verify-receipt --config /absolute/path/reprogate.json ./receipt.json

Do not treat these HMAC keys or filesystem observation as OS-level enforcement. See the threat model before enabling action.execute.

The separate host-only git-review CLI prepares an exact staged-effect request, signs an explicit operator-key decision, imports linked evidence, checks current authorization, and revokes ledger approval. Signing reads a protected key file only after staging and displays the full safely escaped diff; no default MCP approval tool is added. See the operator review guide for configuration, commands, limits and deployment separation.

The Git promotion foundations provide exact candidate objects and a cooperative ownership fence. Candidate preparation permits object/scratch writes and possible unreachable objects. The fence requires private host storage, cooperative writers and trusted-host child quiescence; it is not an OS sandbox. The prepared promotion journal permanently consumes an exact linked signed approval in the existing SQLite ledger and guards raw revocation. Prepared records and status reads grant no dispatch authority. Final authenticated ref CAS, terminal evidence, conservative recovery and promotion CLI/config integration remain follow-up work.

The default server exposes exactly five tools, each with an output schema and conservative annotations:

  • catalog.search: names, descriptions and effects only

  • catalog.describe: one tool's input schema and the schemaDigest a plan binds

  • action.plan: a compact summary (actionId, decision, reasonCodes, nextStep) by default; pass detail: "full" for the full envelope

  • action.inspect: the complete persisted plan for one actionId

  • policy.explain

When an executor is explicitly supplied, the server also registers action.execute. With an opt-in mediation configuration, it also registers action.run, which runs policy-allow read-only plans using a host-issued capability and returns redacted, bounded output. The CLI does this only after serve --config <absolute-path> successfully validates Runtime Configuration v1. See the configuration guide. The included default catalog remains a deterministic, plan-only demo fixture.

A host can also opt in to the advisory handoff_status and handoff_update tools with serve --handoff-config <absolute-path>. They keep durable, caller-asserted session context for one configured workspace and project it to .agent/handoff.md. They never authorize actions. See the handoff guide.

Core invariant

An approval is valid for one exact action, not for a server or tool name in general:

tool identity + schema + arguments + policy + authority + workspace + expiry
                                  │
                                  ▼
                       canonical action digest
                                  │
                     one-use approval capability
                                  │
                                  ▼
                        execution receipt

Arguments are hashed and not stored raw in decision evidence. Tool schemas and effects come from an operator-controlled catalog, not from model-provided metadata. Workspace identity is reserved for gateway-observed values; the agent cannot label its own context as observed.

Why this wedge

MCP gateways, policy engines, audit proxies, replay tools, and provenance systems already exist. ReproGate is designed to integrate with those systems, not rebuild all of them. Its differentiator is the portable contract spanning pre-execution authority and post-execution verification.

See idea validation, the phased roadmap, the improvement backlog, and the threat model.

Contributing and security

Read CONTRIBUTING.md before opening a pull request. Security vulnerabilities should be reported privately according to SECURITY.md, never in a public issue.

License

Apache-2.0.

Available Tools

3 tools
action.planB

Create a digest-bound action envelope and evaluate deterministic policy; this Phase 1 tool never executes the action

ParametersJSON Schema
NameRequiredDescriptionDefault
toolRefYes
argumentsYes

TDQS

B3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden. It discloses a critical safety trait—'never executes the action'—which prevents misuse. However, it omits other behaviors such as side effects, prerequisites, or what happens on policy failure. The single disclosed trait is valuable but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that efficiently conveys the core purpose and key limitation. It avoids filler but uses jargon ('digest-bound action envelope') that may reduce clarity; still, it is appropriately compact for the information it delivers.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of annotations and output schema, the description must stand alone. It does not define key terms (digest, action envelope, deterministic policy), explain inputs, describe return values, or provide usage context. Many operational details are missing, making it insufficient for a complex planning tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description provides no explanation of the two parameters (toolRef and arguments). It does not clarify their roles or formats. With zero schema documentation and zero description compensation, agents are left to guess parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: it creates a digest-bound action envelope and evaluates deterministic policy, explicitly noting it never executes the action. This verb+resource phrasing distinguishes it from siblings like catalog.search (search) and policy.explain (explanation), making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool versus alternatives. It implies a planning/evaluation phase via 'Phase 1' and 'never executes,' but does not mention sibling tools or conditions for selection. An agent would have to infer when to invoke it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

catalog.searchC

Search the trusted downstream tool catalog without exposing every schema

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryNo

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description bears the full burden of behavioral disclosure. It reveals that the tool does not expose every schema, which is a useful limitation, but it does not mention whether the operation is read-only, returns partial results, handles pagination, or has any side effects. The behavioral transparency is minimal for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that front-loads the verb and resource. The phrase 'without exposing every schema' is not redundant and serves as a useful caveat. There is no filler or unnecessary context, though the sentence could arguably be more explicit about query semantics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool, the description is not complete. It gives no information about what the search results will contain, what fields are returned, or how the parameters behave. The absence of an output schema and lack of parameter descriptions mean an agent has to guess at basic invocation details. The 'without exposing every schema' hint partially addresses output, but not sufficiently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not mention either 'query' or 'limit' at all. The description says nothing about what values should be provided, how the query is interpreted, or how limit affects results. With no parameter documentation in either the schema or description, this is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('Search') and resource ('the trusted downstream tool catalog'), and the qualifier 'without exposing every schema' distinguishes it from generic catalog queries. It is not a tautology and clearly separates the search intent from the sibling tools, which are about planning and policy explanation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus action.plan or policy.explain. It does not name alternatives, mention exclusions, or specify context such as 'when you need to find a downstream tool.' The usage is only implied by the tool's name and generic search phrasing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

policy.explainA

Explain the deterministic decision for a previously planned action

ParametersJSON Schema
NameRequiredDescriptionDefault
actionIdYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral disclosure burden. 'Explain' strongly implies a read-only operation and 'deterministic' adds useful context, but the description does not mention prerequisites, error conditions, or whether any state is affected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single focused sentence with no filler. It front-loads the key verb and object and omits redundant detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, this description is largely sufficient: it states the input's purpose and the operation being performed. It could add explicit mention of the return value or the need for the action to already exist, but those are minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It meaningfully clarifies that actionId refers to a previously planned action, giving the lone parameter context beyond the bare schema entry.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Explain') and a clear resource ('deterministic decision for a previously planned action'). It distinguishes itself from siblings like action.plan by focusing on explaining an already-planned action rather than creating or searching for actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'previously planned action' clearly signals that this tool is appropriate after planning has occurred, not for creating plans or searching. It provides clear contextual guidance, though it does not explicitly name alternatives or state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.0.0
    • First observedaction.plan
    • First observedcatalog.search
    • First observedpolicy.explain
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.7/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct action: creating an action envelope with policy evaluation, searching the tool catalog, and explaining previous decisions. There is no overlap or ambiguity in their purposes.

Naming Consistency5/5

All tool names follow the same domain.verb lowercase pattern (action.plan, catalog.search, policy.explain). The naming is uniform, predictable, and clearly groups tools by their domain.

Tool Count5/5

Three tools is within the ideal range, and each tool serves a necessary and distinct function in the planning-and-policy workflow. The small set feels intentionally scoped rather than sparse.

Completeness5/5

The toolset covers the core workflow: discover actionable capabilities, plan an action with deterministic policy evaluation, and explain the resulting decision. As a Phase 1 non-executing gate, no obvious missing operations are present.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-permission-server

    jigonyoo
    A
    license
    Not graded
    quality
    B
    maintenance
    Enforces fine-grained, context-aware access control on MCP tool calls, with a tamper-evident, replayable audit log that records denials and verifies every decision.
    MIT

  • Living Stack MCP — Retired

    equinoxaifinance-rgb
    A
    license
    A
    quality
    B
    maintenance
    Retired snapshot of the former 15-tool Apache-2.0 beta. Use Living Stack Community for the free seven-tool proof edition; Complete Local is the paid runtime with memory, recovery, signed traces, release verification, and multi-agent workflows.
    14
    Apache 2.0

  • Agent Action Preflight v1

    jinen-project
    A
    license
    C
    quality
    C
    maintenance
    Enables an AI agent to preflight concrete tool calls by recording principal, destination, scope, authority evidence, and relations, allowing only formed actions to execute and producing inspectable evidence receipts.
    1
    MIT