Metadata-Version: 2.4
Name: mcpready
Version: 0.1.0
Summary: CI gate for MCP servers
Project-URL: Homepage, https://github.com/he-yufeng/MCPReady
Project-URL: Issues, https://github.com/he-yufeng/MCPReady/issues
Author: Yufeng He
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ci,mcp,model-context-protocol,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: mcp>=1.9
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install mcpready
```

For local development from the repository:

```bash
pip install -e ".[dev]"
```

## Quick Start

```bash
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:

```yaml
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。

常用命令：

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

GitHub Action 用法：

```yaml
- 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

```bash
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
