mcp-release-guardian

Deterministic MCP server for validating release hygiene in local repositories. Network-free, read-only, governance-grade outputs.

---

Release Discipline & Guarantees

Governance Template

This repository includes a reusable scaffold for building deterministic, governance-grade MCP servers:

• template/ — copy/paste starter structure (README, pyproject, CI workflows, docs templates)
• template/ADOPTING_THIS_TEMPLATE.md — minimal adoption steps and guardrails

mcp-release-guardian is intentionally minimal and governance-oriented.

Contract stability

• V1 tool schemas are frozen.
• No behavioral changes without explicit phase reopening.
• Canonical JSON outputs documented in docs/EXAMPLE_OUTPUTS.md.

Determinism

• Network-free execution.
• Read-only repository inspection.
• Fail-closed semantics enforced.
• Design rationale documented in docs/DETERMINISM_NOTES.md.

Reproducibility

• Published to PyPI.
• CI-validated on push.
• Tag-triggered PyPI install smoke test ensures external install integrity.

See docs/V1_CONTRACT.md for the authoritative contract.

Overview

mcp-release-guardian exposes three tools via the Model Context Protocol:

Tool	What it does
check_repo_hygiene	Seven file/directory presence checks: package definition, LICENSE, README, bug report template, CI workflows, V1 contract doc, determinism notes doc
check_version_alignment	Reads pyproject.toml [project].version and compares it to an optional expected tag
generate_release_checklist	Generates a deterministic markdown checklist based on local repo state

All tools are:

• Network-free — no external API calls, ever
• Read-only — no writes to the target repository
• Fail-closed — unresolvable state marks that result as failed, not passed

---

Quickstart

Install

pip install mcp-release-guardian

Or with uv:

uv tool install mcp-release-guardian

Run the server manually

mcp-release-guardian

The server starts on stdio and waits for MCP messages.

---

Claude Desktop configuration

Add the following block to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mcp-release-guardian": {
      "command": "mcp-release-guardian",
      "args": []
    }
  }
}

If you installed with uv tool:

{
  "mcpServers": {
    "mcp-release-guardian": {
      "command": "uvx",
      "args": ["mcp-release-guardian"]
    }
  }
}

Restart Claude Desktop after editing the config.

---

Tool usage examples

check_repo_hygiene

Input:

{
  "repo_path": "/ABS/PATH/TO/REPO"
}

Example response:

{
  "tool": "check_repo_hygiene",
  "repo_path": "/ABS/PATH/TO/REPO",
  "ok": true,
  "checks": [
    { "check_id": "has_package_definition",  "ok": true,  "details": "Found pyproject.toml" },
    { "check_id": "has_license",             "ok": true,  "details": "Found LICENSE" },
    { "check_id": "has_readme",              "ok": true,  "details": "Found README.md" },
    { "check_id": "has_bug_report_template", "ok": true,  "details": "Found .github/ISSUE_TEMPLATE/bug_report.yml" },
    { "check_id": "has_ci_workflows",        "ok": true,  "details": "Found .github/workflows/" },
    { "check_id": "has_v1_contract",         "ok": true,  "details": "Found docs/V1_CONTRACT.md" },
    { "check_id": "has_determinism_notes",   "ok": true,  "details": "Found docs/DETERMINISM_NOTES.md" }
  ],
  "fail_closed": false
}

ok is true only when all seven checks pass. fail_closed equals not ok.

---

check_version_alignment

Input:

{
  "repo_path": "/path/to/my-project",
  "expected_tag": "v1.2.0"
}

expected_tag is optional. When omitted, the tool returns version metadata without performing a comparison.

Example response (match):

{
  "tool": "check_version_alignment",
  "repo_path": "/path/to/my-project",
  "ok": true,
  "expected_tag": "v1.2.0",
  "detected": {
    "version": "1.2.0",
    "source": "pyproject.toml"
  },
  "details": "Version 1.2.0 matches expected tag v1.2.0",
  "fail_closed": false
}

Example response (version absent — fail-closed):

{
  "tool": "check_version_alignment",
  "repo_path": "/path/to/my-project",
  "ok": false,
  "expected_tag": "v1.2.0",
  "detected": {
    "version": null,
    "source": null
  },
  "details": "Could not detect version: pyproject.toml missing or [project].version absent",
  "fail_closed": true
}

Version is read exclusively from pyproject.toml [project].version. The leading v in expected_tag is stripped before comparison.

---

generate_release_checklist

Input:

{
  "repo_path": "/path/to/my-project",
  "target_tag": "v1.2.0"
}

Example response:

{
  "tool": "generate_release_checklist",
  "repo_path": "/path/to/my-project",
  "target_tag": "v1.2.0",
  "checklist_markdown": "# Release Checklist — v1.2.0\n\n## Version alignment\n...",
  "inputs_used": {
    "detected_version": "1.2.0",
    "has_ci_workflows": true,
    "has_bug_template": true
  },
  "fail_closed": false
}

fail_closed is true when detected_version is null (version undetectable). The checklist covers: version alignment, test run, tag creation, release notes, and adoption hooks verification.

---

Development

git clone https://github.com/YOUR_ORG/mcp-release-guardian.git
cd mcp-release-guardian
pip install -e .
pytest -q

See docs/V1_CONTRACT.md for the frozen tool contracts and docs/DETERMINISM_NOTES.md for the determinism and fail-closed design rationale.

See docs/EXAMPLE_OUTPUTS.md for canonical example outputs.

---

License

MIT — see LICENSE.

---

Governance / Contract Status (Tier 1)

This MCP guardian is intended to be governance-grade infrastructure.

Tier 1 guarantees

• Deterministic output for the same inputs and environment constraints
• Network-free evaluation (no implicit network calls)
• Read-only evaluation (does not write to the target repo)
• Fail-closed posture: inability to evaluate reliably yields a failing result (never permissive)
• V1 contract: output semantics are stable under the v1 label; breaking/semantic changes require v2+ with migration notes

How to interpret results

• ok indicates policy success for this guardian (compliance passed)
• fail_closed indicates a safety posture: if true, treat the run as a hard stop for automation
• When ok is false and fail_closed is true, the guardian is explicitly refusing to approve under uncertainty

Reproducibility

For orchestration use-cases, a clean-room run should:

• install a pinned guardian version (e.g., mcp-release-guardian==<version>)
• produce canonical JSON output (stable sorting / deterministic serialization)
• remain network-free and read-only

If you are running via an orchestrator, treat orchestrator wrapper execution success as distinct from guardian policy success.

---

Tier 2 Compatibility (Multi-Guardian Composition)

This guardian is designed to operate safely under multi-guardian orchestration.

Composition assumptions:

• It does not mutate shared state.
• It does not depend on execution order relative to other guardians.
• Its ok and fail_closed semantics are self-contained and do not rely on wrapper-level aggregation.
• Missing dependency or execution failure results in explicit fail-closed behavior (e.g., guardian_import_failed when invoked via orchestrator).

Under V1 semantics:

• Policy decisions should be derived from guardian-level fields.
• Orchestrator wrapper execution success MUST NOT be interpreted as policy approval.

This guardian is Tier 2 compatible under the aggregation model defined in: https://github.com/curtis-d-williams/governance-blueprints