Metadata-Version: 2.4
Name: mcp-api-test
Version: 0.1.3
Summary: MCP server for testing REST API with built-in assertions
Author: Ryan Febriansyah
License-Expression: MIT
Keywords: testing,mcp,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp
Requires-Dist: httpx
Requires-Dist: python-dotenv
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: respx; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material; extra == "docs"
Dynamic: license-file

# mcp-api-test

![pipeline](https://gitlab.com/ryaneatfood/mcp-api-testing/badges/master/pipeline.svg)

An AI-native API testing engine that enables LLM agents to execute, validate, and reason about REST APIs using natural language or cURL inputs.

Unlike traditional testing frameworks, `mcp-api-test` exposes API testing as a **first-class capability for AI agents** rather than a developer-facing tool. LLM-powered clients invoke the `run_test_api` tool directly, making API validation a building block for autonomous coding agents, not a separate human-driven workflow.

It complements (rather than replaces) tools like pytest, Postman, and Playwright.

## Use cases

- **QA & test engineering**: prompt an agent with natural language instead of crafting Postman requests
- **Post-deployment regression**: have an agent smoke-test critical paths after a deploy
- **Quick validation**: test an endpoint inline during a coding session
- **CI/CD automation**: agents validate deployments autonomously in pipelines

> **Token efficiency.** Agents get deterministic, structured results in a single tool call instead of parsing raw `curl` output. Fewer tokens, fewer hallucinations.

## Install

```bash
pip install mcp-api-test
```

Or from source:

```bash
git clone git@gitlab.com:ryaneatfood/mcp-api-testing.git
cd mcp-api-testing
pip install -e .
```

Requires Python >= 3.10.

## Quick start

Configure your MCP client to use the server. For **OpenCode**, add to `opencode.json`:

```json
{
  "mcp": {
    "mcp-api-test": {
      "type": "local",
      "command": ["mcp-api-test"],
      "enabled": true
    }
  }
}
```

For **Claude Desktop**, add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mcp-api-test": {
      "command": "mcp-api-test"
    }
  }
}
```

Then prompt your agent:

> "Test this API: `curl -X POST https://api.example.com/v1/users -H 'Authorization: Bearer xxx' -d '{"name":"test"}'`, ensure status code is 201 and response contains 'id'"

The agent invokes `run_test_api`, validates against the expected contract, and returns structured pass/fail results.

## Documentation

Full documentation is hosted on [GitLab Pages](https://ryaneatfood.gitlab.io/mcp-api-testing/) (or build locally with `mkdocs serve`).

- **[Getting Started](docs/getting-started/installation.md)**: installation and client setup
- **[Usage](docs/usage/request-modes.md)**: cURL mode, structured mode, assertions, response format
- **[Guides](docs/guides/troubleshooting.md)**: troubleshooting, development, configuration
- **[Reference](docs/reference/tool-parameters.md)**: full parameter reference

## License

MIT
