Click on "Deploy 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-release-guardian generate release checklist for /home/user/project"
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.
Deterministic MCP server for validating release hygiene in local repositories. Network-free, read-only, governance-grade outputs.
Related MCP server: TaskBounty Check
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.
mcp-release-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
pip install mcp-release-guardianOr with uv:
uv tool install mcp-release-guardianmcp-release-guardianThe server starts on stdio and waits for MCP messages.
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.
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.
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.
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.
git clone https://github.com/YOUR_ORG/mcp-release-guardian.git
cd mcp-release-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.
MIT — see LICENSE.
This MCP guardian is intended to be governance-grade infrastructure.
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
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
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.
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
Validate that a repo contains the minimum release hygiene artifacts.
Runs seven file/directory presence checks as defined in docs/V1_CONTRACT.md. No network access. Fail-closed.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | Yes | Absolute or relative path to the repository root. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behaviors: no network access and fail-closed operation. With no annotations provided, this adds valuable context. However, it does not detail the output format or error handling beyond 'fail-closed,' though an output schema may cover that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three short sentences. The first sentence front-loads the purpose, and subsequent sentences add key details without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter interface and presence of an output schema, the description adequately covers context. It mentions offline operation and fail-closed behavior, but could add more about supported repository states or error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the single parameter (repo_path) with a clear description. The tool description adds no additional semantic information beyond referencing the contract, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates a repo for minimum release hygiene artifacts, using a specific verb (Validate) and resource (repo). It mentions seven specific checks and references a contract document, distinguishing it from sibling tools like check_version_alignment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for release readiness validation but lacks explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites or exclusions, though 'No network access' hints at an environment constraint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check that pyproject.toml [project].version matches an optional expected tag.
No network access. Fail-closed when version cannot be detected.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | Yes | Absolute or relative path to the repository root. | |
| expected_tag | No | Optional target tag, e.g. "v0.1.0". Leading "v" is stripped before comparison with the file-level version string. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral info: no network access and fail-closed behavior. However, it does not explain the return value or side effects beyond what is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, tightly packed with essential information. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a simple check tool, but it relies on the output schema for return details. Lacks explicit statement of what the tool returns, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the tool description adds no extra meaning. The baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks if pyproject.toml version matches an optional expected tag, which is specific and distinct from sibling tools like check_repo_hygiene or generate_release_checklist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool vs. alternatives. It does not mention prerequisites or scenarios where it should be avoided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deterministically generate a release checklist based on local repo state.
No network access. Reads pyproject.toml version, CI workflow presence, and bug template presence to tailor the checklist.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | Yes | Absolute or relative path to the repository root. | |
| target_tag | Yes | Target release tag, e.g. "v0.1.0". |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses determinism, no network access, and specific file reads. However, it does not mention error handling or what happens if required files are missing, nor does it explicitly state that it does not modify the repo.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences cover the essential purpose and constraints. Information is front-loaded with the action verb. No extraneous words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists and annotations are absent, the description sufficiently covers the tool's deterministic read-only behavior. It lacks details on error scenarios or prerequisites, but is adequate for a simple checklist generator.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description adds context by stating that the checklist is tailored based on repo state, but it does not provide new semantic information beyond what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a release checklist deterministically from local repo state, specifying the inputs (pyproject.toml version, CI workflow, bug template). This distinguishes it from sibling tools which likely focus on checking hygiene or version alignment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus its siblings (check_repo_hygiene, check_version_alignment). It implies usage for release preparation but does not provide when-to-use or when-not-to scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.4check_repo_hygienecheck_version_alignmentgenerate_release_checklistScored across 3 tools
Each tool has a clear, distinct purpose: checking hygiene, version alignment, and generating a checklist. No overlap.
All tools follow a consistent verb_noun pattern with underscores (check_repo_hygiene, check_version_alignment, generate_release_checklist).
Three tools is fitting for a focused release guardian server, though the low count suggests a narrow scope.
The tools cover validation and checklist generation for releases, but lack a tool for applying fixes or executing the release itself.
Read-only AI coding tools for change verification, release readiness, capacity, and guidance.
Generate SBOMs, scan vulnerabilities, and analyze dependencies from local projects or Git repos.
Verify PyPI and npm packages, symbols, and version diffs against real artifacts. Free, no account.
Stateless advisor + validator for Conducted Development: kickoff, artifact validation, rule checks.
