mcp-policy-guardian

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

Release Discipline & Guarantees

mcp-policy-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-policy-guardian exposes three tools via the Model Context Protocol:

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-policy-guardian

Or with uv:

uv tool install mcp-policy-guardian

Run the server manually

mcp-policy-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-policy-guardian": {
      "command": "mcp-policy-guardian",
      "args": []
    }
  }
}

If you installed with uv tool:

{
  "mcpServers": {
    "mcp-policy-guardian": {
      "command": "uvx",
      "args": ["mcp-policy-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-policy-guardian.git
cd mcp-policy-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.