Skip to main content
Glama
curtis-d-williams

mcp-policy-guardian

by curtis-d-williams
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

mcp-policy-guardian

PyPI Python CI PyPI install smoke

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

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-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.

Install Server
A
security – no known vulnerabilities
F
license - not found
A
quality - A tier

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/curtis-d-williams/mcp-policy-guardian'

If you have feedback or need assistance with the MCP directory API, please join our Discord server