@cocaxcode/api-testing-mcp 0.5.0 → 0.5.1

package/README.md

@@ -1,27 +1,26 @@
 <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/>
+    <strong>A complete API testing toolkit built for AI coding agents.</strong><br/>
     Test, validate, mock, and load-test your APIs — all from natural language.
   </p>
 </p>
 
 <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://www.npmjs.com/package/@cocaxcode/api-testing-mcp"><img src="https://img.shields.io/npm/dm/@cocaxcode/api-testing-mcp.svg?style=flat-square" alt="npm downloads" /></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>
 
 <p align="center">
-  <a href="#installation">Installation</a> •
-  <a href="#just-talk-to-it">Just Talk to It</a> •
-  <a href="#works-with-any-api">Any API</a> •
-  <a href="#features">Features</a> •
-  <a href="#tool-reference">Tool Reference</a> •
-  <a href="#storage">Storage</a> •
+  <a href="#installation">Installation</a> &middot;
+  <a href="#just-talk-to-it">Just Talk to It</a> &middot;
+  <a href="#works-with-any-api">Any API</a> &middot;
+  <a href="#features">Features</a> &middot;
+  <a href="#tool-reference">Tool Reference</a> &middot;
+  <a href="#storage">Storage</a> &middot;
+  <a href="#limitations">Limitations</a> &middot;
   <a href="#contributing">Contributing</a>
 </p>
 
@@ -35,6 +34,73 @@ You describe what you need. The AI figures out the rest.
 
 No cloud accounts. No subscriptions. Everything runs locally and stores data as plain JSON files you can commit to git.
 
+**Requires** an MCP-compatible client such as [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Claude Desktop](https://claude.ai/download), or [Cursor](https://cursor.sh). This is not a standalone CLI tool — it extends your AI assistant with API testing capabilities.
+
+---
+
+## Installation
+
+### Claude Code
+
+```bash
+claude mcp add api-testing -- npx -y @cocaxcode/api-testing-mcp
+```
+
+### Claude Desktop
+
+Add to your config file:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "api-testing": {
+      "command": "npx",
+      "args": ["-y", "@cocaxcode/api-testing-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global):
+
+```json
+{
+  "mcpServers": {
+    "api-testing": {
+      "command": "npx",
+      "args": ["-y", "@cocaxcode/api-testing-mcp"]
+    }
+  }
+}
+```
+
+### Quick start
+
+Once installed, set up an environment so the tool knows where your API lives:
+
+```
+"Create an environment called dev with BASE_URL http://localhost:3000"
+```
+
+From here, relative paths work automatically. `/api/users` becomes `http://localhost:3000/api/users`.
+
+If your API has Swagger/OpenAPI, import the spec:
+
+```
+"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.
+
+To verify the installation is working, try: *"List my environments"* — it should show the one you just created.
+
+Available on [npm](https://www.npmjs.com/package/@cocaxcode/api-testing-mcp).
+
 ---
 
 ## Just Talk to It
@@ -114,75 +180,20 @@ You: "Save this request as cf-list-zones with tag cloudflare"
 
 Every request, collection, and spec is isolated per environment. Your Cloudflare tests don't mix with your local backend tests.
 
-### What the storage looks like
-
-```
-.api-testing/
-├── active-env                       # Currently active: "cloudflare"
-├── environments/
-│   ├── github.json                  # { BASE_URL, GITHUB_TOKEN }
-│   ├── cloudflare.json              # { BASE_URL, API_KEY }
-│   ├── dokploy.json                 # { BASE_URL, TOKEN }
-│   └── my-backend.json              # { BASE_URL, TOKEN }
-├── specs/
-│   ├── dokploy.json                 # Imported OpenAPI spec
-│   └── my-backend.json              # Imported OpenAPI spec
-└── collections/
-    ├── cf-list-zones.json           # Saved requests per API
-    ├── gh-my-repos.json
-    └── dok-list-projects.json
-```
-
 ---
 
-## Installation
-
-### Claude Code
-
-```bash
-claude mcp add api-testing -- npx -y @cocaxcode/api-testing-mcp
-```
-
-### Claude Desktop / Cursor / Any MCP Client
-
-Add to your MCP configuration file:
-
-```json
-{
-  "mcpServers": {
-    "api-testing": {
-      "command": "npx",
-      "args": ["-y", "@cocaxcode/api-testing-mcp"]
-    }
-  }
-}
-```
-
-### First steps
-
-Set up an environment so the tool knows where your API lives:
-
-```
-"Create an environment called dev with BASE_URL http://localhost:3000"
-```
+## Features
 
-From here, relative paths work automatically. `/api/users` becomes `http://localhost:3000/api/users`.
+### HTTP Requests
 
-If your API has Swagger/OpenAPI, import the spec:
+Send any request by describing what you need. The AI resolves relative URLs, injects environment variables, and handles authentication automatically.
 
 ```
-"Import my API spec from http://localhost:3000/api-docs-json"
+"POST to /api/users with name Jane and email jane@company.com using my bearer token"
 ```
 
-Now the AI knows every endpoint, parameter, and schema in your API. You're ready to go.
-
----
-
-## Features
-
-### HTTP Requests
-
-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.
+<details>
+<summary>What the tool executes</summary>
 
 ```
 request({
@@ -192,39 +203,39 @@ request({
   auth: { type: "bearer", token: "{{TOKEN}}" }
 })
 ```
+</details>
 
-**Supports:** GET · POST · PUT · PATCH · DELETE · HEAD · OPTIONS — Headers · Query params · JSON body · Bearer / API Key / Basic auth · Timeout · `{{variable}}` interpolation
+**Supports:** GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS — Headers, query params, JSON body, Bearer / API Key / Basic auth, timeout, `{{variable}}` interpolation.
 
 ### Assertions
 
-Run a request and validate the response against a set of rules in one step. Get structured pass/fail results.
+Validate API responses against a set of rules in one step. Get structured pass/fail results.
 
 ```
-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 }
-  ]
-})
+"Verify that GET /api/health returns 200, body.status is ok, and responds in under 500ms"
 ```
 
 ```
-✅ PASS — 3/3 assertions passed
+PASS — 3/3 assertions passed
 GET /api/health → 200 OK (42ms)
 
-✅ status === 200
-✅ body.status === "ok"
-✅ timing.total_ms < 500
+  status === 200
+  body.status === "ok"
+  timing.total_ms < 500
 ```
 
-**Operators:** `eq` · `neq` · `gt` · `gte` · `lt` · `lte` · `contains` · `not_contains` · `exists` · `type`
+**Operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `not_contains`, `exists`, `type`
 
 ### 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.
+Chain multiple requests together. Extract values from one response and inject them into the next step. Perfect for auth flows, CRUD sequences, and multi-step testing.
+
+```
+"Login as admin@test.com, extract the access token, then use it to fetch all users"
+```
+
+<details>
+<summary>What the tool executes</summary>
 
 ```
 flow_run({
@@ -233,7 +244,7 @@ flow_run({
       name: "login",
       method: "POST",
       url: "/auth/login",
-      body: { email: "admin@test.com", password: "123456" },
+      body: { email: "admin@test.com", password: "SecurePass#99" },
       extract: { "TOKEN": "body.access_token" }
     },
     {
@@ -245,23 +256,24 @@ flow_run({
   ]
 })
 ```
+</details>
 
 ### OpenAPI Import
 
 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.
 
 ```
-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" })
+"Import my API spec from http://localhost:3000/api-docs-json"
+"Show me all user endpoints"
+"What parameters does POST /users expect?"
 ```
 
 ### Mock Data Generation
 
-Generate realistic fake data from your OpenAPI spec. Respects types, formats (`email`, `uuid`, `date-time`), enums, and required fields. Use `count` for arrays.
+Generate realistic fake data from your OpenAPI spec. Respects types, formats (`email`, `uuid`, `date-time`), enums, and required fields.
 
 ```
-mock({ name: "my-backend", method: "POST", path: "/users", target: "request" })
+"Generate mock data for creating a user"
 ```
 
 ```json
@@ -278,17 +290,17 @@ mock({ name: "my-backend", method: "POST", path: "/users", target: "request" })
 Fire N concurrent requests and get performance metrics: min, avg, percentiles (p50/p95/p99), max, and requests per second.
 
 ```
-load_test({ method: "GET", url: "/api/health", concurrent: 50 })
+"How fast is the health endpoint with 50 concurrent requests?"
 ```
 
 ```
-📊 LOAD TEST — GET /api/health
+LOAD TEST — GET /api/health
 
 Requests:        50 concurrent
 Successful:      50 | Failed: 0
 Requests/sec:    23.31
 
-⏱️  Response times:
+Response times:
   Min:   45ms  |  Avg:  187ms
   p50:  156ms  |  p95:  412ms
   p99:  523ms  |  Max:  567ms
@@ -296,13 +308,10 @@ Requests/sec:    23.31
 
 ### Response Diffing
 
-Execute two requests and compare their responses field by field. Detect regressions or compare environments (dev vs prod).
+Execute two requests and compare their responses field by field. Detect regressions or compare environments.
 
 ```
-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" }
-})
+"Compare the users endpoint between dev and prod"
 ```
 
 ### Bulk Testing
@@ -310,21 +319,25 @@ diff_responses({
 Run every saved request in your collection (or filter by tag) and get a pass/fail summary.
 
 ```
-bulk_test({ tag: "smoke" })
+"Run all my saved smoke tests"
 ```
 
 ```
-✅ BULK TEST — 8/8 passed | 1.2s total
+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)
+  health       — GET  /health      → 200 (45ms)
+  list-users   — GET  /users       → 200 (123ms)
+  create-post  — POST /blog        → 201 (89ms)
+  login        — POST /auth/login  → 200 (156ms)
 ```
 
 ### cURL Export
 
-Convert any saved request into a cURL command with resolved variables.
+Convert any saved request into a ready-to-paste cURL command with resolved variables.
+
+```
+"Export the create-user request as curl"
+```
 
 ```bash
 curl -X POST \
@@ -334,7 +347,7 @@ curl -X POST \
   -d '{"name":"Jane","email":"jane@company.com"}'
 ```
 
-### Collections & Environments
+### Collections and Environments
 
 Save requests for reuse (with tags), manage variables across environments (dev/staging/prod), and switch contexts instantly.
 
@@ -349,11 +362,13 @@ Save requests for reuse (with tags), manage variables across environments (dev/s
 | **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 |
+| **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 |
+| **Utilities** | `load_test` `export_curl` `diff_responses` `bulk_test` | 4 |
+
+You don't need to call these tools directly. Just describe what you want and the AI picks the right one.
 
 ---
 
@@ -369,7 +384,7 @@ All data lives in `.api-testing/` as plain JSON — no database, no cloud sync:
 └── specs/                         # Imported OpenAPI specs
 ```
 
-Override the default directory:
+Override the default directory in your MCP config:
 
 ```json
 {
@@ -377,7 +392,17 @@ Override the default directory:
 }
 ```
 
-Commit these files to git to share across your team.
+Commit these files to git to share API configurations across your team.
+
+---
+
+## Limitations
+
+- **Auth**: Supports Bearer token, API Key, and Basic auth. OAuth 2.0 flows (authorization code, PKCE) are not supported — use a pre-obtained token instead.
+- **Protocols**: HTTP/HTTPS only. No WebSocket, gRPC, or GraphQL-specific support (though GraphQL over HTTP works fine).
+- **Load testing**: Recommended maximum of 100 concurrent requests. This is a testing tool, not a benchmarking framework.
+- **Specs**: OpenAPI 3.x only. OpenAPI 2.0 (Swagger) is partially supported. AsyncAPI is not supported.
+- **Storage**: Local JSON files only. No built-in cloud sync or team collaboration server.
 
 ---
 
@@ -398,7 +423,13 @@ npm run typecheck   # Strict TypeScript
 npx @modelcontextprotocol/inspector node dist/index.js
 ```
 
-**Stack:** TypeScript · MCP SDK 1.27 · Zod · Vitest · tsup
+**Stack:** TypeScript &middot; MCP SDK 1.27 &middot; Zod &middot; Vitest &middot; tsup
+
+### How to contribute
+
+- **Bug reports**: [Open an issue](https://github.com/cocaxcode/api-testing-mcp/issues) with steps to reproduce, expected vs actual behavior, and your Node.js version.
+- **Feature requests**: Open an issue describing the use case. Include examples of how you'd use it in natural language.
+- **Pull requests**: Fork, create a branch, make your changes, ensure `npm test` and `npm run typecheck` pass, then open a PR.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocaxcode/api-testing-mcp",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "MCP server for API testing. 20 tools: HTTP requests, assertions, flows, OpenAPI import, mock data, load testing. Zero cloud dependencies.",
   "type": "module",
   "bin": {
@@ -27,12 +27,20 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "api-testing",
     "http",
     "rest",
     "model-context-protocol",
     "claude",
-    "ai-tools"
+    "claude-desktop",
+    "cursor",
+    "ai-tools",
+    "openapi",
+    "swagger",
+    "load-testing",
+    "mock-data",
+    "postman-alternative"
   ],
   "author": "cocaxcode",
   "license": "MIT",