Metadata-Version: 2.4
Name: mcp-api-test
Version: 0.1.0
Summary: MCP server for testing REST API with built-in assertions
Author: Ryan Febriansyah
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: License :: OSI Approved :: MIT License
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"
Dynamic: license-file

# api-test-mcp

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

MCP server for REST API testing with assertions. Provides a `test_api` tool that accepts either a cURL command or structured request fields, runs the request, and validates against expected status codes and response fields

## Prerequisites

- Python >= 3.10
- pip or uv for package installation

## Install

### From PyPI

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

### From source

```bash
git clone git@gitlab.com:ryaneatfood/mcp-api-testing.git

# change the directory
cd api-test-mcp

# install from source
pip install -e .
```

This registers the `api-test-mcp` CLI command on your PATH. Verify with:

```bash
which api-test-mcp
```

## Testing with MCP Inspector

The [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) provides a browser-based UI to verify your server connects and responds correctly before wiring it into a client.

Make sure `api-test-mcp` is installed on your PATH (see [Install](#install)), then run:

```bash
npx @modelcontextprotocol/inspector
```

This launches the inspector and opens `http://localhost:5173` in your browser. From the UI:

1. Set **Transport Type** to `STDIO`
2. Set **Command** to `api-test-mcp`
3. Leave **Arguments** empty (your server needs none)
4. Click **Connect**

When the connection succeeds, the status badge changes to **Connected** and the inspector lists the `test_api` tool under the Tools tab. You can click the tool to open a form and run test calls interactively. This is useful for rapid iteration without restarting your MCP client.

If the status shows "Failed to connect" double-check that `which api-test-mcp` resolves and that `pip install -e .` completed without errors

## Running Tests

Install test dependencies and run the suite:

```bash
# install test dependencies
pip install pytest pytest-asyncio respx

# run the whole test suite
pytest -v
```

All integration tests use `respx` to mock HTTP responses. No real network calls are made, so the suite runs fast and offline. The test suite also consisted of unit test and integration test

## OpenCode Setup

Edit `opencode.json` (already configured at project root):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "api-test-mcp": {
      "type": "local",
      "command": ["api-test-mcp"],
      "enabled": true
    }
  }
}
```

## Claude Desktop Setup

Edit `claude_desktop_config.json` (usually at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

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

Restart Claude Desktop after saving.

## Usage

The `test_api` tool supports two modes:

### cURL mode

Pass a raw cURL command, and then the server parses method, URL, headers, and payload automatically into restructured data. Example prompt that you might be used:

> "Please test this API using this cURL: `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'"

### Structured mode

Provide individual fields rather than used a cURL command. Example prompt:

> "Please test this API at https://api.example.com/v1/users with method GET, and the request header is {"Content-Type":"application/json"}, ensure status code is 200 and response body contains 'data'" attribute

### Assertions

At the moment, this library provides built-in assertions that proved useful for testing the API, such as:

| Parameter | Type | Description |
|-----------|------|-------------|
| `required_status_code` | `int` | Assert exact status code |
| `required_status_code_range` | `str` | Assert status code is within a range (e.g. `"2xx"`, `"200-299"`) |
| `required_response_fields` | `list[str]` | Assert fields exist in JSON response |
| `required_response_contains` | `str` | Assert response body contains a substring |

## Response

The tool returns a formatted console string with box-drawing, pass/fail symbols, and a summary:

### Passing (with assertions)

```
┌──────────────────────────────────────────────┐
│ Api Test Result                              │
└──────────────────────────────────────────────┘

API Name        : create-user
Method          : POST
URL             : https://api.example.com/v1/users
Status Code     : 201
Response Time   : 142.35 ms
Overall Result  : Passed

Assertions
--------------------------------------------------
✓ status_code
✓ response_field_exist

Summary
--------------------------------------------------
Total Assertions : 2
Passed           : 2
Failed           : 0
```

### Failing (assertion mismatch)

```
┌──────────────────────────────────────────────┐
│ Api Test Result                              │
└──────────────────────────────────────────────┘

API Name        : create-user
Method          : POST
URL             : https://api.example.com/v1/users
Status Code     : 500
Response Time   : 89.12 ms
Overall Result  : Failed

Assertions
--------------------------------------------------
✗ status_code

Summary
--------------------------------------------------
Total Assertions : 1
Passed           : 0
Failed           : 1
```

### Network / runtime error

```
┌──────────────────────────────────────────────┐
│ Api Test Result                              │
└──────────────────────────────────────────────┘

API Name        : check-service
Method          : GET
URL             : https://api.internal.example.com/v1/status
Overall Result  : Failed

Error
--------------------------------------------------
ConnectError: [Errno 8] nodename nor servname provided, or not known
```

## Logging

The server writes logs to `log/mcp-api-test.log` at the project root. Useful for debugging failed requests or tracing tool calls.

## Environment Variables

The server loads a `.env` file via `python-dotenv` on startup. Useful for storing API keys, base URLs, etc. without hardcoding them in prompts.

## Development

```bash
# Re-install after pulling changes
pip install -e .

# Run the MCP server directly
api-test-mcp
```

To run the test suite:

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