MCP Policy Guardian MCP Server

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"