Agent Readiness

What the Agent Readiness MCP server does

The Agent Readiness MCP server is distributed as a GitHub Action that evaluates a repository or selected subdirectory for AI coding agent readiness. Its primary readiness engine produces a score from 0 to 100 and breaks that score into categories such as instruction files, architecture documentation, scripts, tests, safety boundaries, and ecosystem-specific development files.

The action recognizes Node.js, Python, Go, and Rust ecosystems when scoring files such as lockfiles, version pins, test runners, linters, and formatters. A separate context audit can inspect agent instruction files for placeholders, contradictory guidance, stale commands, embedded secrets, hidden Unicode characters, and risky directives. It also checks selected Claude Code and MCP settings, including permission bypasses, hooks that run remote scripts, and third-party API endpoints.

How it works

The action operates on the checked-out files without making LLM calls or contacting external services, apart from the optional GitHub pull request comment feature. The two bundled engines are pinned into the action, so runtime package downloads are not required. Results appear in the Actions log and job summary. Raw JSON can also be printed, and a Markdown report can be written inside the audited repository path.

A workflow can fail when the readiness score is below a configured minimum. For pull requests, baseline-ref lets the action audit the base commit in a temporary Git worktree and compare scores. max-score-drop can then reject changes that reduce the score beyond the allowed amount. The optional context audit has its own failure threshold for low-, medium-, or high-severity findings.

Setup and configuration

Add the action after actions/checkout in a GitHub Actions workflow. The default audit path is the workspace root, but repo-path can target a subdirectory or monorepo package. Set min-score with fail-on-threshold to enforce a minimum result, or use output to create a report artifact.

Pull request comments require pull-requests: write and issues: write permissions. Supply github-token, usually from ${{ github.token }}, or let the action use GITHUB_TOKEN. Comment updates are limited to its earlier bot-authored summary comment; comment-author can restrict updates to a specified login.

Enable context-audit to inspect instruction files with the bundled context checker. The audited repository’s .acdrc is honored. Baseline comparisons require the base commit to be available, so checkout should use fetch-depth: 0.

Tools and capabilities

The Agent Readiness MCP server provides these supported capabilities:

• Score repository readiness from 0 to 100.
• Report category results in logs and job summaries.
• Audit agent context files for safety and quality issues.
• Emit raw JSON or write a Markdown report.
• Compare a pull request with a baseline commit.
• Comment on pull requests and update the existing summary.
• Fail workflows on score or context-audit thresholds.

The checks are read-only with respect to the audited content, although the action can write a configured report and publish a pull request comment.

Limitations and notes

The tool is a GitHub Action rather than a general-purpose repository service. It requires a checked-out workspace and GitHub Actions configuration. Pull request comments are optional and need additional repository permissions. Baseline comparison needs the base commit locally available. The project describes the audit as deterministic and complementary to human review; its output does not replace review of the repository or its agent instructions.