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.

中文说明

MCPReady 是一个面向 CI 的 MCP Server 质量门禁工具。它会启动 stdio MCP server，完成基础握手，拉取工具列表，检查工具契约，并把明显的 token 泄露作为失败项报告。

它不是另一个可视化 Inspector。手工调试请用官方 MCP Inspector；想让 PR 在合入前自动发现坏 server，就用 MCPReady。

常用命令：

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

GitHub Action 用法：

- 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

第一版只支持 stdio transport。HTTP / SSE 支持会放到后续版本。

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