@cocaxcode/api-testing-mcp 0.3.0 → 0.4.1

package/README.md

@@ -1,38 +1,67 @@
-# @cocaxcode/api-testing-mcp
+<p align="center">
+  <h1 align="center">@cocaxcode/api-testing-mcp</h1>
+  <p align="center">
+    A complete API testing toolkit built for AI coding agents.<br/>
+    Test, validate, mock, and load-test your APIs — all from natural language.
+  </p>
+</p>
 
-[![npm version](https://img.shields.io/npm/v/@cocaxcode/api-testing-mcp.svg)](https://www.npmjs.com/package/@cocaxcode/api-testing-mcp)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<p align="center">
+  <a href="https://www.npmjs.com/package/@cocaxcode/api-testing-mcp"><img src="https://img.shields.io/npm/v/@cocaxcode/api-testing-mcp.svg?style=flat-square&color=cb3837" alt="npm version" /></a>
+  <a href="https://github.com/cocaxcode/api-testing-mcp/actions"><img src="https://img.shields.io/github/actions/workflow/status/cocaxcode/api-testing-mcp/ci.yml?style=flat-square&label=CI" alt="CI" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License" /></a>
+  <img src="https://img.shields.io/badge/tests-70%20passing-brightgreen?style=flat-square" alt="Tests" />
+  <img src="https://img.shields.io/badge/tools-20-blueviolet?style=flat-square" alt="Tools" />
+  <img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node" />
+</p>
 
-MCP server for API testing. Lightweight, local, zero cloud dependencies.
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#just-talk-to-it">Just Talk to It</a> •
+  <a href="#features">Features</a> •
+  <a href="#tool-reference">Tool Reference</a> •
+  <a href="#storage">Storage</a> •
+  <a href="#contributing">Contributing</a>
+</p>
 
-Test your APIs directly from Claude Code, Claude Desktop, Cursor, or any MCP client — without leaving your workflow.
+---
 
-## Features
+## What is this?
 
-- **HTTP requests** — GET, POST, PUT, PATCH, DELETE with headers, body, query params
-- **Authentication** — Bearer token, API Key, Basic Auth built-in
-- **Collections** — Save, organize, and reuse requests locally
-- **Environments** — Manage variables per environment (dev/staging/prod)
-- **Variable interpolation** — Use `{{VARIABLE}}` in URLs, headers, and body
-- **Response metrics** — Timing (ms) and response size for every request
-- **Zero cloud dependencies** — Everything stored locally as JSON files
+An [MCP server](https://modelcontextprotocol.io) that gives your AI assistant the ability to interact with any API. It works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.
 
-## Installation
+You describe what you need. The AI figures out the rest.
 
-### Claude Desktop
+No cloud accounts. No subscriptions. Everything runs locally and stores data as plain JSON files you can commit to git.
 
-Add to your `claude_desktop_config.json`:
+---
 
-```json
-{
-  "mcpServers": {
-    "api-testing": {
-      "command": "npx",
-      "args": ["-y", "@cocaxcode/api-testing-mcp"]
-    }
-  }
-}
-```
+## Just Talk to It
+
+This tool is designed to be used through natural language. You don't need to memorize tool names, parameters, or JSON structures — just tell the AI what you want, and it translates your intent into the right API calls.
+
+**Here's what a real conversation looks like:**
+
+| You say | What happens behind the scenes |
+|---------|-------------------------------|
+| *"Set up an environment for my local API on port 3000"* | Creates environment with `BASE_URL=http://localhost:3000` |
+| *"Import my API spec from /api-docs-json"* | Downloads the OpenAPI spec, stores all endpoints and schemas |
+| *"Show me all user endpoints"* | Filters and lists endpoints tagged `users` |
+| *"Get all users"* | `GET /api/users` → shows the response |
+| *"Create a user with random data"* | Reads the spec, generates valid mock data, sends `POST /api/users` |
+| *"Verify that deleting user 5 returns 204"* | Runs the request + assertion in one step |
+| *"Login as admin and then fetch the dashboard stats"* | Chains 2 requests: login → extract token → use token for next call |
+| *"How fast is the health endpoint under load?"* | Fires 50 concurrent requests, reports p50/p95/p99 latencies |
+| *"Run all my saved smoke tests"* | Executes every request tagged `smoke`, reports pass/fail |
+| *"Export the create-user request as curl"* | Builds a ready-to-paste cURL command with resolved variables |
+| *"Compare the users endpoint between dev and prod"* | Hits both URLs, diffs status codes, body, and timing |
+| *"Switch to the production environment"* | Changes active env — all subsequent requests use prod URLs and tokens |
+
+**The AI already knows your API** if you've imported the spec. It knows which fields are required, what types they expect, valid enum values, and what the response looks like. When you say *"create a blog post"*, it doesn't guess — it reads the schema and builds the request correctly.
+
+---
+
+## Installation
 
 ### Claude Code
 
@@ -40,217 +69,265 @@ Add to your `claude_desktop_config.json`:
 claude mcp add api-testing -- npx -y @cocaxcode/api-testing-mcp
 ```
 
-### Custom storage directory
+### Claude Desktop / Cursor / Any MCP Client
+
+Add to your MCP configuration file:
 
 ```json
 {
   "mcpServers": {
     "api-testing": {
       "command": "npx",
-      "args": ["-y", "@cocaxcode/api-testing-mcp"],
-      "env": {
-        "API_TESTING_DIR": "/path/to/your/.api-testing"
-      }
+      "args": ["-y", "@cocaxcode/api-testing-mcp"]
     }
   }
 }
 ```
 
-## Tools
+### First steps
+
+Set up an environment so the tool knows where your API lives:
 
-### `request`
+```
+"Create an environment called dev with BASE_URL http://localhost:3000"
+```
 
-Execute an HTTP request with optional authentication and variable interpolation.
+From here, relative paths work automatically. `/api/users` becomes `http://localhost:3000/api/users`.
 
-Relative URLs (starting with `/`) automatically use `BASE_URL` from the active environment — no need to write `{{BASE_URL}}` every time.
+If your API has Swagger/OpenAPI, import the spec:
 
 ```
-// Relative URL — auto-prepends BASE_URL from active environment
-request({ method: "GET", url: "/api/users" })
+"Import my API spec from http://localhost:3000/api-docs-json"
+```
+
+Now the AI knows every endpoint, parameter, and schema in your API. You're ready to go.
+
+---
+
+## Features
+
+### HTTP Requests
 
-// Equivalent to:
-request({ method: "GET", url: "{{BASE_URL}}/api/users" })
+Execute any HTTP method with headers, body, query params, and built-in auth. Relative URLs resolve from the active environment. Variables like `{{TOKEN}}` are replaced from environment values.
 
-// Full example with all options
+```
 request({
-  method: "GET",
+  method: "POST",
   url: "/api/users",
-  headers: { "Authorization": "Bearer {{TOKEN}}" },
-  query: { "page": "1" },
-  timeout: 5000
+  body: { name: "Jane", email: "jane@company.com" },
+  auth: { type: "bearer", token: "{{TOKEN}}" }
 })
 ```
 
-**Auth examples:**
+**Supports:** GET · POST · PUT · PATCH · DELETE · HEAD · OPTIONS — Headers · Query params · JSON body · Bearer / API Key / Basic auth · Timeout · `{{variable}}` interpolation
 
-```
-// Bearer token
-request({ method: "GET", url: "...", auth: { type: "bearer", token: "abc123" } })
+### Assertions
 
-// API Key
-request({ method: "GET", url: "...", auth: { type: "api-key", key: "mykey", header: "X-API-Key" } })
+Run a request and validate the response against a set of rules in one step. Get structured pass/fail results.
 
-// Basic Auth
-request({ method: "GET", url: "...", auth: { type: "basic", username: "user", password: "pass" } })
+```
+assert({
+  method: "GET",
+  url: "/api/health",
+  assertions: [
+    { path: "status", operator: "eq", expected: 200 },
+    { path: "body.status", operator: "eq", expected: "ok" },
+    { path: "timing.total_ms", operator: "lt", expected: 500 }
+  ]
+})
 ```
 
-**Response format:**
+```
+✅ PASS — 3/3 assertions passed
+GET /api/health → 200 OK (42ms)
 
-```json
-{
-  "status": 200,
-  "statusText": "OK",
-  "headers": { "content-type": "application/json" },
-  "body": { "users": [] },
-  "timing": { "total_ms": 142.35 },
-  "size_bytes": 1024
-}
+✅ status === 200
+✅ body.status === "ok"
+✅ timing.total_ms < 500
 ```
 
-### `collection_save`
+**Operators:** `eq` · `neq` · `gt` · `gte` · `lt` · `lte` · `contains` · `not_contains` · `exists` · `type`
 
-Save a request to your local collection for reuse.
+### Request Flows
+
+Chain multiple requests together. Extract values from one response and inject them into the next step using `{{variables}}`. Perfect for auth flows, CRUD sequences, and multi-step testing.
 
 ```
-collection_save({
-  name: "get-users",
-  request: { method: "GET", url: "https://api.example.com/users" },
-  tags: ["users", "read"]
+flow_run({
+  steps: [
+    {
+      name: "login",
+      method: "POST",
+      url: "/auth/login",
+      body: { email: "admin@test.com", password: "123456" },
+      extract: { "TOKEN": "body.access_token" }
+    },
+    {
+      name: "get-users",
+      method: "GET",
+      url: "/api/users",
+      headers: { "Authorization": "Bearer {{TOKEN}}" }
+    }
+  ]
 })
 ```
 
-### `collection_list`
+### OpenAPI Import
 
-List all saved requests. Optionally filter by tag.
+Import your Swagger/OpenAPI spec from a URL or local file. Once imported, the AI understands every endpoint, parameter, and schema — no guessing, no memorizing.
 
 ```
-collection_list({ tag: "users" })
+api_import({ name: "my-backend", source: "http://localhost:3000/api-docs-json" })
+api_endpoints({ name: "my-backend", tag: "users" })
+api_endpoint_detail({ name: "my-backend", method: "POST", path: "/users" })
 ```
 
-### `collection_get`
+### Mock Data Generation
 
-Get the full details of a saved request.
+Generate realistic fake data from your OpenAPI spec. Respects types, formats (`email`, `uuid`, `date-time`), enums, and required fields. Use `count` for arrays.
 
 ```
-collection_get({ name: "get-users" })
+mock({ name: "my-backend", method: "POST", path: "/users", target: "request" })
 ```
 
-### `collection_delete`
-
-Delete a saved request from the collection.
-
-```
-collection_delete({ name: "get-users" })
+```json
+{
+  "email": "user42@example.com",
+  "name": "Test User 73",
+  "password": "TestPass123!",
+  "role": "admin"
+}
 ```
 
-### `env_create`
+### Load Testing
 
-Create a new environment with optional initial variables.
+Fire N concurrent requests and get performance metrics: min, avg, percentiles (p50/p95/p99), max, and requests per second.
 
 ```
-env_create({
-  name: "dev",
-  variables: { "BASE_URL": "http://localhost:3000", "TOKEN": "dev-token" }
-})
+load_test({ method: "GET", url: "/api/health", concurrent: 50 })
 ```
 
-### `env_list`
+```
+📊 LOAD TEST — GET /api/health
 
-List all environments and which one is active.
+Requests:        50 concurrent
+Successful:      50 | Failed: 0
+Requests/sec:    23.31
 
-### `env_set`
+⏱️  Response times:
+  Min:   45ms  |  Avg:  187ms
+  p50:  156ms  |  p95:  412ms
+  p99:  523ms  |  Max:  567ms
+```
 
-Set a variable in an environment (defaults to active environment).
+### Response Diffing
+
+Execute two requests and compare their responses field by field. Detect regressions or compare environments (dev vs prod).
 
 ```
-env_set({ key: "TOKEN", value: "new-token-value" })
+diff_responses({
+  request_a: { label: "dev",  method: "GET", url: "http://dev.api.com/users" },
+  request_b: { label: "prod", method: "GET", url: "http://prod.api.com/users" }
+})
 ```
 
-### `env_get`
+### Bulk Testing
 
-Get a specific variable or all variables from an environment.
+Run every saved request in your collection (or filter by tag) and get a pass/fail summary.
 
 ```
-env_get({ key: "BASE_URL" })
-env_get({})  // returns all variables
+bulk_test({ tag: "smoke" })
 ```
 
-### `env_switch`
-
-Switch the active environment. Active environment variables are used for `{{interpolation}}`.
-
 ```
-env_switch({ name: "prod" })
+✅ BULK TEST — 8/8 passed | 1.2s total
+
+✅ health       — GET  /health      → 200 (45ms)
+✅ list-users   — GET  /users       → 200 (123ms)
+✅ create-post  — POST /blog        → 201 (89ms)
+✅ login        — POST /auth/login  → 200 (156ms)
 ```
 
-### `api_import`
+### cURL Export
 
-Import an OpenAPI/Swagger spec from a URL or local file. Endpoints and schemas are stored locally for browsing.
+Convert any saved request into a cURL command with resolved variables.
 
+```bash
+curl -X POST \
+  'https://api.example.com/users' \
+  -H 'Authorization: Bearer eyJhbGci...' \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Jane","email":"jane@company.com"}'
 ```
-api_import({
-  name: "my-backend",
-  source: "http://localhost:3001/api-docs-json"
-})
 
-// Or from a local file:
-api_import({ name: "my-backend", source: "./openapi.json" })
-```
+### Collections & Environments
 
-### `api_endpoints`
+Save requests for reuse (with tags), manage variables across environments (dev/staging/prod), and switch contexts instantly.
 
-List endpoints from an imported API. Filter by tag, method, or path.
+---
 
-```
-api_endpoints({ name: "my-backend" })
-api_endpoints({ name: "my-backend", tag: "users" })
-api_endpoints({ name: "my-backend", method: "POST" })
-api_endpoints({ name: "my-backend", path: "/blog" })
-```
+## Tool Reference
 
-### `api_endpoint_detail`
+20 tools organized in 8 categories:
 
-Get full details of an endpoint: parameters, request body schema, and responses. Useful to know what data to send.
+| Category | Tools | Count |
+|----------|-------|-------|
+| **Requests** | `request` | 1 |
+| **Testing** | `assert` | 1 |
+| **Flows** | `flow_run` | 1 |
+| **Collections** | `collection_save` · `collection_list` · `collection_get` · `collection_delete` | 4 |
+| **Environments** | `env_create` · `env_list` · `env_set` · `env_get` · `env_switch` | 5 |
+| **API Specs** | `api_import` · `api_endpoints` · `api_endpoint_detail` | 3 |
+| **Mock** | `mock` | 1 |
+| **Utilities** | `load_test` · `export_curl` · `diff_responses` · `bulk_test` | 4 |
 
-```
-api_endpoint_detail({ name: "my-backend", method: "POST", path: "/blog" })
-```
+---
 
 ## Storage
 
-All data is stored locally as JSON files in `.api-testing/` (in your current working directory by default):
+All data lives in `.api-testing/` as plain JSON — no database, no cloud sync:
 
 ```
 .api-testing/
-├── active-env                    # Name of the active environment
-├── collections/
-│   ├── get-users.json
-│   └── create-post.json
-├── environments/
-│   ├── dev.json
-│   └── prod.json
-└── specs/
-    └── my-backend.json           # Imported OpenAPI specs
+├── active-env                     # Active environment name
+├── collections/                   # Saved requests
+├── environments/                  # Environment variables (dev, prod, ...)
+└── specs/                         # Imported OpenAPI specs
 ```
 
-You can version these files in git if you want to share collections and environments with your team.
+Override the default directory:
 
-## Development
+```json
+{
+  "env": { "API_TESTING_DIR": "/path/to/shared/.api-testing" }
+}
+```
+
+Commit these files to git to share across your team.
+
+---
+
+## Contributing
 
 ```bash
 git clone https://github.com/cocaxcode/api-testing-mcp.git
 cd api-testing-mcp
 npm install
-npm test
-npm run build
+npm test            # 70 tests across 10 suites
+npm run build       # ESM bundle via tsup
+npm run typecheck   # Strict TypeScript
 ```
 
-### Test with MCP Inspector
+**Test with MCP Inspector:**
 
 ```bash
 npx @modelcontextprotocol/inspector node dist/index.js
 ```
 
+**Stack:** TypeScript · MCP SDK 1.27 · Zod · Vitest · tsup
+
+---
+
 ## License
 
-MIT
+[MIT](./LICENSE) — built by [cocaxcode](https://github.com/cocaxcode)