Metadata-Version: 2.4
Name: mcp-probe-cli
Version: 0.1.0
Summary: Test your MCP server like you test an API — declarative YAML, CI-ready, zero boilerplate.
Project-URL: Homepage, https://github.com/mcp-probe/mcp-probe
Project-URL: Repository, https://github.com/mcp-probe/mcp-probe
Project-URL: Issues, https://github.com/mcp-probe/mcp-probe/issues
Author: mcp-probe contributors
License: MIT
Keywords: ai,cli,mcp,model-context-protocol,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: mcp>=1.6.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# mcp-probe-cli

Test your MCP server like you test an API — declarative YAML, CI-ready, zero boilerplate.

## Install

```bash
pip install mcp-probe-cli
```

## Quick Start

```bash
mcp-probe version
```

Create `tests/mcp.yaml`:

```yaml
server:
  command: python
  args: [src/my_server.py]

tests:
  - name: "lists tools"
    call: tools/list
    expect:
      tool_count: 2
```

Run:

```bash
mcp-probe test tests/mcp.yaml
```

## Example Test YAML

```yaml
server:
  command: python
  args: [src/my_server.py]        # relative to this YAML file's directory
  env:                            # optional — merged with current environment
    LOG_LEVEL: warning

tests:
  # Assert exact tool count
  - name: "lists 3 tools"
    call: tools/list
    expect:
      tool_count: 3

  # Assert a tool name appears in the response
  - name: "echo tool is present"
    call: tools/list
    expect:
      contains: "echo"

  # Call a tool and check output
  - name: "echo returns the input"
    call: tools/call
    params:
      name: echo
      arguments:
        message: "hello"
    expect:
      status: ok           # ok | error
      contains: "hello"

  # Assert the tool call fails
  - name: "unknown tool returns error"
    call: tools/call
    params:
      name: does_not_exist
      arguments: {}
    expect:
      status: error
      contains: "not found"
```

## Commands

| Command | Description |
| --- | --- |
| `mcp-probe test <config>` | Run a test suite from a YAML file |
| `mcp-probe test <config> --json` | Output results as JSON (for CI parsing) |
| `mcp-probe replay <traces> --server <cmd>` | Replay captured traces against a live server |
| `mcp-probe replay <traces> --server <cmd> --diff` | Replay and diff against recorded baselines |
| `mcp-probe version` | Print the CLI version |

## GitHub Action

```yaml
- name: Test MCP server
  uses: mcp-probe/test-action@v1
  with:
    config: tests/mcp.yaml
    github-token: ${{ secrets.GITHUB_TOKEN }}
```

## Links

- [GitHub repository](https://github.com/mcp-probe/mcp-probe)
- [Full documentation](https://github.com/mcp-probe/mcp-probe/tree/main/docs)
- [Issue tracker](https://github.com/mcp-probe/mcp-probe/issues)

## License

MIT
