Provides tools for auditing local Git repositories, including verifying version alignment with tags and ensuring project metadata consistency during the release process.
Validates the presence of GitHub-specific repository assets such as issue templates and CI workflow configurations to ensure compliance with release hygiene policies.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-policy-guardiancheck the release hygiene and version alignment of this repo"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
Tool | What it does |
| Seven file/directory presence checks: package definition, LICENSE, README, bug report template, CI workflows, V1 contract doc, determinism notes doc |
| Reads |
| 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-policy-guardianOr with uv:
uv tool install mcp-policy-guardianRun the server manually
mcp-policy-guardianThe 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 -qSee 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.
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.