Metadata-Version: 2.4
Name: mcp-agent-tester
Version: 0.1.1
Summary: Local-first MCP server inspector, smoke tester, and agent runner with a web UI, CLI, and JSON traces.
Project-URL: Homepage, https://github.com/akshaychame/mcp-agent-tester
Project-URL: Source, https://github.com/akshaychame/mcp-agent-tester
Project-URL: Issues, https://github.com/akshaychame/mcp-agent-tester/issues
Author-email: Akshay Chame <akshay.chame@tmdc.io>
License: MIT License
        
        Copyright (c) 2026 Akshay Chame
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,inspector,llm,mcp,model-context-protocol,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.124.0
Requires-Dist: fastmcp==3.2.0
Requires-Dist: openai>=2.0.0
Requires-Dist: pydantic>=2.12.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=14.0.0
Requires-Dist: typer>=0.20.0
Requires-Dist: uvicorn>=0.40.0
Description-Content-Type: text/markdown

# mcp-agent-tester

Local-first MCP server inspector, smoke tester, and agent runner with a small web UI,
CLI commands, and JSON traces.

## What It Does

mcp-agent-tester can connect to an MCP server over Streamable HTTP, SSE, or stdio and:

- inspect tools, prompts, and resources
- run safe smoke tests based on explicit tool policies
- run an agent against the server using Codex CLI, Claude Code, or Cursor agent
- stream live events into the UI
- write per-run traces under `~/.mcp-agent-tester/runs/`

## Quickstart

**With uv (recommended):**
```bash
uv tool install mcp-agent-tester

# If the command is not found after install:
export PATH="$HOME/.local/bin:$PATH"
# To make it permanent:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

mcp-agent-tester ui
```

**With pip:**
```bash
pip install mcp-agent-tester
mcp-agent-tester ui
```

**From source:**
```bash
git clone https://github.com/akshaychame/mcp-agent-tester
cd mcp-agent-tester
uv sync
uv run mcp-agent-tester ui
```

Open `http://127.0.0.1:8765`, enter an MCP server URL or stdio command, and choose
`inspect`, `smoke`, or `agent`.

You can also run from the CLI:

```bash
mcp-agent-tester inspect --profile profiles/example.yaml
mcp-agent-tester smoke --profile profiles/example.yaml
mcp-agent-tester agent --profile profiles/example.yaml "Summarize what this MCP server exposes."
```

Or with uv:

```bash
uv run mcp-agent-tester inspect --profile profiles/example.yaml
uv run mcp-agent-tester smoke --profile profiles/example.yaml
uv run mcp-agent-tester agent --profile profiles/example.yaml "Summarize what this MCP server exposes."
```

## Profiles

Profiles are YAML files that describe server connection details and safe smoke-test
policies. Start from `profiles/example.yaml` and add your own local file:

```yaml
server:
  name: my-mcp-server
  transport: http
  endpoint: http://localhost:8080/mcp

tools:
  default_policy: list_only
  policies:
    example_read_only_tool:
      policy: safe_with_args
      args:
        limit: 5
```

Local overrides such as `*.local.yaml` are ignored by git.

## Agent Runners

- Codex CLI: used by default for agent runs
- Claude Code: select the Claude agent in the UI
- Cursor agent: select Cursor in the UI and sign in when prompted

## Requirements

- Python 3.11+
- `uv`
- Optional: Codex CLI, Claude Code CLI, or Cursor agent CLI for agent runs

## License

MIT
