@cocaxcode/api-testing-mcp 0.3.0 → 0.4.0

package/README.md

@@ -2,238 +2,354 @@
 
 [![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)
+[![Tests](https://img.shields.io/badge/tests-70%20passing-brightgreen)]()
+[![Node](https://img.shields.io/badge/node-%3E%3D20-blue)]()
 
-MCP server for API testing. Lightweight, local, zero cloud dependencies.
+**The API testing toolkit for AI coding agents.** Test APIs directly from Claude Code, Claude Desktop, Cursor, or any MCP client — using natural language.
 
-Test your APIs directly from Claude Code, Claude Desktop, Cursor, or any MCP client — without leaving your workflow.
+> "Test my login endpoint with invalid credentials"
+> "Import the API spec and show me all blog endpoints"
+> "Run a load test with 50 concurrent requests to /health"
+> "Generate mock data for the create user endpoint"
 
-## Features
+Zero cloud dependencies. Everything stored locally as JSON.
 
-- **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
+---
 
-## Installation
+## Why?
 
-### Claude Desktop
+| Problem | Solution |
+|---------|----------|
+| Switching between Postman and your IDE | Test APIs without leaving your editor |
+| Remembering endpoint URLs and body schemas | Import your OpenAPI spec — the AI knows your API |
+| Writing `{{BASE_URL}}/api/users` every time | Just write `/api/users` — BASE_URL is auto-resolved |
+| Manual regression testing | `bulk_test` runs your entire collection in seconds |
+| No idea what data to send | `mock` generates fake data from your API spec |
+| Testing auth flows manually | `flow_run` chains requests — login → extract token → use it |
 
-Add to your `claude_desktop_config.json`:
+---
 
-```json
-{
-  "mcpServers": {
-    "api-testing": {
-      "command": "npx",
-      "args": ["-y", "@cocaxcode/api-testing-mcp"]
-    }
-  }
-}
-```
+## Quick Start
 
-### Claude Code
+### Install in Claude Code
 
 ```bash
 claude mcp add api-testing -- npx -y @cocaxcode/api-testing-mcp
 ```
 
-### Custom storage directory
+### Install in Claude Desktop / Cursor
+
+Add to your MCP config:
 
 ```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
+### Setup your environment
 
-### `request`
-
-Execute an HTTP request with optional authentication and variable interpolation.
+```
+"Create an environment called dev with BASE_URL http://localhost:3000 and TOKEN my-dev-token"
+```
 
-Relative URLs (starting with `/`) automatically use `BASE_URL` from the active environment — no need to write `{{BASE_URL}}` every time.
+That's it. Now just talk:
 
 ```
-// Relative URL — auto-prepends BASE_URL from active environment
-request({ method: "GET", url: "/api/users" })
+"GET /api/health"
+"Create a blog post with random data"
+"Show me all users sorted by creation date"
+```
 
-// Equivalent to:
-request({ method: "GET", url: "{{BASE_URL}}/api/users" })
+---
 
-// Full example with all options
-request({
-  method: "GET",
-  url: "/api/users",
-  headers: { "Authorization": "Bearer {{TOKEN}}" },
-  query: { "page": "1" },
-  timeout: 5000
-})
-```
+## Features & Examples
 
-**Auth examples:**
+### 🌐 HTTP Requests — `request`
 
+Execute any HTTP request with full control. Relative URLs (`/path`) auto-resolve using `BASE_URL` from the active environment.
+
+```
+"GET /api/users"
+"POST /api/blog with title 'Hello World' and content 'My first post'"
+"DELETE /api/users/123 with Bearer token abc123"
 ```
-// Bearer token
-request({ method: "GET", url: "...", auth: { type: "bearer", token: "abc123" } })
 
-// API Key
-request({ method: "GET", url: "...", auth: { type: "api-key", key: "mykey", header: "X-API-Key" } })
+**Supports:** GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS | Headers | Query params | JSON body | Auth (Bearer, API Key, Basic) | Timeout | Variable interpolation `{{VAR}}`
 
-// Basic Auth
-request({ method: "GET", url: "...", auth: { type: "basic", username: "user", password: "pass" } })
-```
+---
 
-**Response format:**
+### ✅ Assertions — `assert`
 
-```json
-{
-  "status": 200,
-  "statusText": "OK",
-  "headers": { "content-type": "application/json" },
-  "body": { "users": [] },
-  "timing": { "total_ms": 142.35 },
-  "size_bytes": 1024
-}
-```
+Execute a request AND validate the response in one step. Get structured pass/fail results.
 
-### `collection_save`
+```
+"Assert that GET /api/health returns status 200 and body.status equals 'ok'"
+"Verify POST /api/login with wrong password returns 401"
+"Check that GET /api/users responds in less than 500ms"
+```
 
-Save a request to your local collection for reuse.
+**Available operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `not_contains`, `exists`, `type`
 
+**Output:**
 ```
-collection_save({
-  name: "get-users",
-  request: { method: "GET", url: "https://api.example.com/users" },
-  tags: ["users", "read"]
-})
+✅ PASS — 3/3 assertions passed
+GET /api/health → 200 OK (42ms)
+
+✅ status === 200
+✅ body.status === "ok"
+✅ timing.total_ms < 500
 ```
 
-### `collection_list`
+---
 
-List all saved requests. Optionally filter by tag.
+### 🔗 Flow — `flow_run`
+
+Chain multiple requests in sequence. Extract data from one response and use it in the next step with `{{variables}}`.
 
 ```
-collection_list({ tag: "users" })
+"Run a flow: first login with email admin@test.com and password 123456,
+ extract the token from body.token,
+ then use that token to GET /api/users"
 ```
 
-### `collection_get`
+**Output:**
+```
+✅ FLOW COMPLETO — 2/2 pasos ejecutados
 
-Get the full details of a saved request.
+✅ Paso 1: login
+   Status: 200 | Tiempo: 145ms
+   Extraído: TOKEN=eyJhbGciOiJIUzI1NiIs...
 
+✅ Paso 2: get-users
+   Status: 200 | Tiempo: 89ms
 ```
-collection_get({ name: "get-users" })
-```
 
-### `collection_delete`
+---
+
+### 📋 OpenAPI Import — `api_import`, `api_endpoints`, `api_endpoint_detail`
+
+Import your Swagger/OpenAPI spec so the AI knows your entire API — endpoints, schemas, required fields, everything.
 
-Delete a saved request from the collection.
+```
+"Import my API from http://localhost:3000/api-docs-json"
+"What endpoints does the blog module have?"
+"Show me the details of POST /api/users — what fields does it need?"
+```
 
+**Output:**
 ```
-collection_delete({ name: "get-users" })
+API 'my-backend' imported — 24 endpoints, 15 schemas
+
+Endpoints by tag:
+  auth: 3 endpoints
+  users: 5 endpoints
+  blog: 6 endpoints
+  projects: 4 endpoints
 ```
 
-### `env_create`
+---
 
-Create a new environment with optional initial variables.
+### 🎭 Mock Data — `mock`
 
+Generate realistic fake data from your OpenAPI spec. Perfect for frontend development without a running backend.
+
+```
+"Generate mock data for creating a user"
+"Give me 10 fake blog posts based on the API spec"
+"What would the response of GET /api/projects look like?"
 ```
-env_create({
-  name: "dev",
-  variables: { "BASE_URL": "http://localhost:3000", "TOKEN": "dev-token" }
-})
+
+**Output:**
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "email": "user42@example.com",
+  "name": "Test User 73",
+  "role": "admin",
+  "active": true
+}
 ```
 
-### `env_list`
+---
 
-List all environments and which one is active.
+### 📊 Load Test — `load_test`
 
-### `env_set`
+Launch N concurrent requests and get performance stats: avg, min, max, percentiles, requests/second.
 
-Set a variable in an environment (defaults to active environment).
+```
+"Run a load test with 50 concurrent requests to GET /api/health"
+"Load test POST /api/search with 20 concurrent requests"
+```
 
+**Output:**
 ```
-env_set({ key: "TOKEN", value: "new-token-value" })
+📊 LOAD TEST — GET /api/health
+
+Requests: 50 concurrentes
+Exitosos: 50 | Fallidos: 0
+Tiempo total: 2145ms
+Requests/segundo: 23.31
+
+⏱️ Tiempos de respuesta:
+  Min:  45ms
+  Avg:  187ms
+  p50:  156ms
+  p95:  412ms
+  p99:  523ms
+  Max:  567ms
+
+📋 Status codes:
+  200: 50 (100%)
 ```
 
-### `env_get`
+---
 
-Get a specific variable or all variables from an environment.
+### 🔄 Diff Responses — `diff_responses`
+
+Compare two requests side by side. Useful for regression testing or comparing environments (dev vs prod).
 
 ```
-env_get({ key: "BASE_URL" })
-env_get({})  // returns all variables
+"Compare GET /api/users on dev vs prod"
+"Diff the response of v1/users vs v2/users"
 ```
 
-### `env_switch`
+---
+
+### 🚀 Bulk Test — `bulk_test`
 
-Switch the active environment. Active environment variables are used for `{{interpolation}}`.
+Run all saved requests in your collection and get a summary report. Filter by tag.
 
 ```
-env_switch({ name: "prod" })
+"Run all saved requests tagged 'smoke'"
+"Bulk test my entire collection"
 ```
 
-### `api_import`
+**Output:**
+```
+✅ BULK TEST — 8/8 passed | 1234ms total
+
+✅ health-check — GET /api/health → 200 (45ms)
+✅ list-users — GET /api/users → 200 (123ms)
+✅ create-post — POST /api/blog → 201 (89ms)
+✅ get-post — GET /api/blog/test-post → 200 (67ms)
+...
+```
+
+---
+
+### 📤 Export cURL — `export_curl`
 
-Import an OpenAPI/Swagger spec from a URL or local file. Endpoints and schemas are stored locally for browsing.
+Convert any saved request to a cURL command. Ready to copy-paste and share.
 
 ```
-api_import({
-  name: "my-backend",
-  source: "http://localhost:3001/api-docs-json"
-})
+"Export the create-user request as cURL"
+```
 
-// Or from a local file:
-api_import({ name: "my-backend", source: "./openapi.json" })
+**Output:**
+```bash
+curl \
+  -X POST \
+  'https://api.example.com/users' \
+  -H 'Authorization: Bearer abc123' \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"John","email":"john@example.com"}'
 ```
 
-### `api_endpoints`
+---
+
+### 💾 Collections — `collection_save`, `collection_list`, `collection_get`, `collection_delete`
 
-List endpoints from an imported API. Filter by tag, method, or path.
+Save, organize, and reuse requests locally. Tag them for easy filtering.
 
 ```
-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" })
+"Save this request as 'create-user' with tags 'users' and 'write'"
+"Show me all saved requests tagged 'auth'"
+"Delete the old-endpoint request"
 ```
 
-### `api_endpoint_detail`
+---
 
-Get full details of an endpoint: parameters, request body schema, and responses. Useful to know what data to send.
+### 🌍 Environments — `env_create`, `env_list`, `env_set`, `env_get`, `env_switch`
+
+Manage variables per environment. Switch between dev/staging/prod seamlessly.
 
 ```
-api_endpoint_detail({ name: "my-backend", method: "POST", path: "/blog" })
+"Create a prod environment with BASE_URL https://api.example.com"
+"Switch to dev environment"
+"Set TOKEN to my-new-token in the current environment"
 ```
 
+---
+
+## All 20 Tools
+
+| Category | Tool | Description |
+|----------|------|-------------|
+| **Request** | `request` | Execute HTTP requests |
+| **Assert** | `assert` | Request + validate with assertions |
+| **Flow** | `flow_run` | Chain requests, extract variables |
+| **Collections** | `collection_save` | Save a request |
+| | `collection_list` | List saved requests |
+| | `collection_get` | Get request details |
+| | `collection_delete` | Delete a request |
+| **Environments** | `env_create` | Create environment |
+| | `env_list` | List environments |
+| | `env_set` | Set a variable |
+| | `env_get` | Get variable(s) |
+| | `env_switch` | Switch active env |
+| **API Spec** | `api_import` | Import OpenAPI spec |
+| | `api_endpoints` | List endpoints |
+| | `api_endpoint_detail` | Endpoint details |
+| **Mock** | `mock` | Generate fake data |
+| **Load Test** | `load_test` | Concurrent performance test |
+| **Utilities** | `export_curl` | Export as cURL |
+| | `diff_responses` | Compare responses |
+| | `bulk_test` | Run entire collection |
+
+---
+
 ## Storage
 
-All data is stored locally as JSON files in `.api-testing/` (in your current working directory by default):
+All data is stored locally as JSON files in `.api-testing/`:
 
 ```
 .api-testing/
-├── active-env                    # Name of the active environment
+├── active-env
 ├── collections/
-│   ├── get-users.json
-│   └── create-post.json
+│   ├── health-check.json
+│   └── create-user.json
 ├── environments/
 │   ├── dev.json
 │   └── prod.json
 └── specs/
-    └── my-backend.json           # Imported OpenAPI specs
+    └── my-backend.json
+```
+
+Configure the storage directory:
+
+```json
+{
+  "mcpServers": {
+    "api-testing": {
+      "command": "npx",
+      "args": ["-y", "@cocaxcode/api-testing-mcp"],
+      "env": {
+        "API_TESTING_DIR": "/path/to/your/.api-testing"
+      }
+    }
+  }
+}
 ```
 
-You can version these files in git if you want to share collections and environments with your team.
+You can version these files in git to share with your team.
+
+---
 
 ## Development
 
@@ -241,8 +357,9 @@ You can version these files in git if you want to share collections and environm
 git clone https://github.com/cocaxcode/api-testing-mcp.git
 cd api-testing-mcp
 npm install
-npm test
+npm test          # 70 tests
 npm run build
+npm run typecheck
 ```
 
 ### Test with MCP Inspector
@@ -251,6 +368,8 @@ npm run build
 npx @modelcontextprotocol/inspector node dist/index.js
 ```
 
+---
+
 ## License
 
-MIT
+MIT — [cocaxcode](https://github.com/cocaxcode)