Agent Readiness MCP server

agent-readiness-action

What it is

A GitHub Action that checks how ready a repository is for AI coding agents (Claude Code, Cursor, Codex, Copilot, and similar). It bundles two deterministic engines:

repository from 0 to 100: instruction files, architecture notes, scripts, tests, safety boundaries, and more. Lockfiles, version pins, test runners, linters, and formatters are scored on the files of each detected ecosystem (Node.js, Python, Go, Rust). It prints a category breakdown in the log and job summary.

• agent-readiness-kit scores the

context-audit: 'true', checks the instruction files themselves: placeholders, risky directives, contradictions, stale commands, pasted secrets, hidden Unicode, and risky Claude Code and MCP configuration such as bypassPermissions, hooks that run remote scripts, or third-party API endpoints.

• agent-context-doctor, with

It can fail the build below a score, block pull requests that lower the score, write a Markdown report, and post a summary comment on pull requests.

Both engines are bundled into the action at pinned commits, so nothing is downloaded or executed from a package registry at run time. There are no external API calls (other than the optional PR comment), no telemetry, and no LLM calls.

Why use it

setup docs) before it slows down day-to-day agent work.

• Catch missing or low-quality agent context (instruction files, architecture notes,

let them run commands without asking.

• Catch instruction files and agent settings that steer agents toward unsafe changes or

any drop from the base branch.

• Track the readiness score over time and gate pull requests on a minimum score or on

review, not a replacement for it.

• Give reviewers a concise, deterministic summary on each PR — a complement to human

Quick start

# .github/workflows/agent-readiness.yml
name: Agent Readiness Audit

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: alipajand/agent-readiness-action@v1

Examples

Basic audit

name: Agent Readiness Audit

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: alipajand/agent-readiness-action@v1

Fail below a minimum score

- uses: alipajand/agent-readiness-action@v1
  with:
    min-score: '70'
    fail-on-threshold: 'true'

Comment on pull requests

permissions:
  contents: read
  pull-requests: write
  issues: write

steps:
  - uses: actions/checkout@v7
  - uses: alipajand/agent-readiness-action@v1
    with:
      comment-on-pr: 'true'
      min-score: '70'
      github-token: ${{ github.token }}

Shortened. The full README is on GitHub.