@cocaxcode/api-testing-mcp 0.4.2 → 0.5.1

package/README.md

@@ -1,26 +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="#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>
 
@@ -34,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
@@ -61,46 +128,57 @@ This tool is designed to be used through natural language. You don't need to mem
 
 ---
 
-## Installation
+## Works with Any API
 
-### Claude Code
+This isn't limited to your own backend. You can test **any API** — public, third-party, or internal — and manage them all simultaneously through environments.
+
+### Managing multiple APIs
+
+Set up one environment per API and switch between them instantly:
 
-```bash
-claude mcp add api-testing -- npx -y @cocaxcode/api-testing-mcp
 ```
+"Create an environment called github with BASE_URL https://api.github.com"
+"Create an environment called cloudflare with BASE_URL https://api.cloudflare.com/client/v4"
+"Create an environment called dokploy with BASE_URL https://my-server:3000/api"
+"Create an environment called my-backend with BASE_URL http://localhost:3000"
+```
+
+Add authentication variables to each one:
 
-### Claude Desktop / Cursor / Any MCP Client
+```
+"Set GITHUB_TOKEN in the github environment"
+"Set API_KEY in cloudflare"
+"Set TOKEN in dokploy"
+```
 
-Add to your MCP configuration file:
+Then just switch context and start working:
 
-```json
-{
-  "mcpServers": {
-    "api-testing": {
-      "command": "npx",
-      "args": ["-y", "@cocaxcode/api-testing-mcp"]
-    }
-  }
-}
 ```
+"Switch to github"
+"Get my repos"                              → GET /user/repos with Bearer token
 
-### First steps
+"Switch to cloudflare"
+"List all DNS zones"                        → GET /zones with API key auth
 
-Set up an environment so the tool knows where your API lives:
+"Switch to dokploy"
+"Show me all running projects"              → GET /project with token
 
+"Switch to my-backend"
+"Create a user with random data"            → POST /users with mock body from spec
 ```
-"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:
+### Real-world example: testing a third-party API
 
 ```
-"Import my API spec from http://localhost:3000/api-docs-json"
+You: "Set up Cloudflare with my API key"
+You: "List my DNS zones"
+You: "Show me all DNS records for cocaxcode.dev"
+You: "Verify that the A record for api.cocaxcode.dev exists"
+You: "How fast is the zones endpoint under load?"
+You: "Save this request as cf-list-zones with tag cloudflare"
 ```
 
-Now the AI knows every endpoint, parameter, and schema in your API. You're ready to go.
+Every request, collection, and spec is isolated per environment. Your Cloudflare tests don't mix with your local backend tests.
 
 ---
 
@@ -108,7 +186,14 @@ Now the AI knows every endpoint, parameter, and schema in your API. You're ready
 
 ### 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.
+Send any request by describing what you need. The AI resolves relative URLs, injects environment variables, and handles authentication automatically.
+
+```
+"POST to /api/users with name Jane and email jane@company.com using my bearer token"
+```
+
+<details>
+<summary>What the tool executes</summary>
 
 ```
 request({
@@ -118,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({
@@ -159,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" }
     },
     {
@@ -171,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
@@ -204,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
@@ -222,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
@@ -236,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 \
@@ -260,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.
 
@@ -275,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.
 
 ---
 
@@ -295,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
 {
@@ -303,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.
 
 ---
 
@@ -324,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.4.2",
+  "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",