Shimguard

What shimguard does

The shimguard MCP server exposes ShimGuard’s GitHub tracker verification workflow to MCP clients. ShimGuard checks closed issues in a repository and follows the pull request cited as the fix. Its core verdict distinguishes between a cited fix that merged, one that did not merge, and an issue without enough evidence to verify. These outcomes are reported as MATCH, MISMATCH, and UNVERIFIED.

The underlying check uses GitHub’s REST API rather than a heuristic. A mismatch can identify a closed issue whose referenced pull request is still open or was never merged. The CLI can also perform an optional code-pattern check: given an issue-specific file path and regular-expression pattern, it checks whether that pattern remains at the repository’s current HEAD.

How it works

The shimguard MCP server provides one tool named run. The tool receives an argument list equivalent to the command-line arguments passed to shimguard. For example, an agent can request verify, provide an <owner>/<repo> target, select issue numbers, and ask for JSON output.

The MCP process runs the CLI and returns a structured response. Successful calls include returncode, stdout, and stderr; when the CLI produces JSON, the response also includes that data as a parsed json field. Failed, timed-out, or non-zero commands are returned as an error result instead. JSON mode provides issue metadata, cited pull-request status, optional pattern-check results, verdicts, and reasons in a form suitable for agent processing.

Setup and configuration

Install the Python distribution with MCP support:

pip install "shimguard-cli[mcp]"

Register the executable as an MCP server command in a compatible client:

{
  "mcpServers": {
    "shimguard": {
      "command": "shimguard-mcp"
    }
  }
}

The GitHub token is optional. The CLI accepts --token, and otherwise reads GITHUB_TOKEN when available; the documented command does not require an environment variable for basic operation. The MCP server uses the Python package’s CLI entry point and does not require the separate npm installation.

Tools and capabilities

The shimguard MCP server offers the following capability through its single tool:

• Run the ShimGuard CLI with verification arguments.
• Check selected GitHub issues with --issues.
• Request text or structured JSON output using --format.
• Supply a GitHub token through the CLI argument or environment.
• Apply optional path-and-pattern checks with --patterns.
• Return exit status and raw command streams alongside parsed results.

The CLI’s exit codes can also be used by callers: 1 indicates at least one mismatch, 0 means no checked issue was proven broken, and 2 indicates a usage or network error.

Limitations and notes

Only one MCP tool is exposed, so agents must express operations through ShimGuard’s CLI argument format. The server does not add a separate GitHub API interface or independent verification tool.

Pattern checks require a JSON mapping of issue numbers to file paths and regular expressions. Patterns are compiled as JavaScript regular expressions, and paths are restricted to the target repository. The README recommends using only pattern files that the operator has written or reviewed.

GitHub API access can be affected by rate limits; providing a token enables higher API rate limits. The verification result confirms the cited pull request’s merge state, but the optional pattern check is needed when the operator also wants to test whether a named code pattern remains present.