MCPReady

Stop shipping broken MCP servers.

MCPReady is a small CI gate for Model Context Protocol servers. It starts a stdio MCP server, runs the basic client handshake, lists tools, checks the tool contract shape, scans observed metadata/stderr for obvious secret leaks, and writes Markdown/JSON reports that fit cleanly into GitHub Actions.

It is not a visual inspector. Use the official MCP Inspector when you want to click around a server by hand. Use MCPReady when you want a pull request to fail before a broken MCP server lands.

Install

pip install mcpready

For local development from the repository:

pip install -e ".[dev]"

Quick Start

mcpready check \
  --command "python -m your_mcp_server" \
  --report mcpready-report.md \
  --json mcpready-report.json

The command exits with code 0 when the server passes, and code 1 when the server fails a required check.

Use --fail-on-warn if warnings should also fail CI.

What v0.1 Checks

• the server process starts
• the MCP initialize handshake completes
• tools/list returns successfully
• each tool has a non-empty name and input schema
• observed stderr and tool metadata do not contain obvious token patterns
• Markdown and JSON reports can be written for CI artifacts

MCPReady v0.1 only supports stdio servers. HTTP and SSE transports are planned for later releases.

GitHub Action

MCPReady also ships as a composite GitHub Action:

name: MCPReady

on:
  pull_request:
  push:
    branches: [main]

jobs:
  mcpready:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: "3.13"
      - uses: he-yufeng/MCPReady@v0.1.0
        with:
          command: python -m your_mcp_server
          report: mcpready-report.md
          json: mcpready-report.json

The action installs MCPReady from the action checkout, so it works before the package is published to PyPI. Use @main only when you intentionally want the latest unreleased changes.

Development

python -m pytest -q
python -m ruff check .
python -m ruff format --check .
python -m compileall -q src tests
python -m build
python -m twine check dist/*

Publishing

MCPReady publishes through PyPI Trusted Publishing. Configure a pending publisher on PyPI with:

• PyPI project name: mcpready
• Owner: he-yufeng
• Repository name: MCPReady
• Workflow name: publish.yml
• Environment name: pypi

After that, publishing a GitHub Release will upload the package without storing a long-lived PyPI token in GitHub secrets.

License

MIT