@cocaxcode/api-testing-mcp 0.8.2 → 0.9.0

package/README.md

@@ -2,7 +2,7 @@
   <h1 align="center">@cocaxcode/api-testing-mcp</h1>
   <p align="center">
     <strong>The most complete API testing MCP server available.</strong><br/>
-    27 tools &middot; Zero config &middot; Zero dependencies &middot; Everything runs inside your AI conversation.
+    29 tools &middot; Zero config &middot; Zero dependencies &middot; Everything runs inside your AI conversation.
   </p>
 </p>
 
@@ -11,8 +11,8 @@
   <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/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node" />
-  <img src="https://img.shields.io/badge/tools-27-blueviolet?style=flat-square" alt="27 tools" />
-  <img src="https://img.shields.io/badge/tests-83-brightgreen?style=flat-square" alt="83 tests" />
+  <img src="https://img.shields.io/badge/tools-29-blueviolet?style=flat-square" alt="29 tools" />
+  <img src="https://img.shields.io/badge/tests-96-brightgreen?style=flat-square" alt="96 tests" />
 </p>
 
 <p align="center">
@@ -29,7 +29,7 @@
 
 ## What is this?
 
-An [MCP server](https://modelcontextprotocol.io) that gives your AI assistant the ability to **test, validate, mock, chain, diff, load-test, and manage** any API — all from natural language.
+An [MCP server](https://modelcontextprotocol.io) that gives your AI assistant the ability to **test, validate, mock, chain, diff, load-test, export to Postman, and manage** any API — all from natural language.
 
 You describe what you need. The AI figures out the rest.
 
@@ -47,7 +47,7 @@ There are other API testing MCP servers out there. Here's why this one is differ
 
 | Capability | @cocaxcode/api-testing-mcp | Others |
 |---|:---:|:---:|
-| HTTP requests with auth | 27 tools | 1-11 tools |
+| HTTP requests with auth | 29 tools | 1-11 tools |
 | Assertions (eq, neq, gt, lt, contains, exists, type...) | 10 operators | Status code only or none |
 | Request flows with variable extraction | `flow_run` with `extract` | Not available |
 | Collections with tags and CRUD | Full CRUD + tag filtering | Import from Postman or none |
@@ -57,6 +57,7 @@ There are other API testing MCP servers out there. Here's why this one is differ
 | Load testing with percentiles | p50/p95/p99 + req/s | Basic or none |
 | Response diffing | Field-by-field comparison | Not available |
 | Bulk testing by tag | Collection-wide pass/fail | Not available |
+| **Postman export (collection + environment)** | **Files ready to import** | **Not available** |
 | cURL export | With resolved variables | Not available |
 | Project-scoped environments | Per-directory context | Not available |
 | External dependencies | **Zero** — just Node.js | Playwright, Jest, pytest... |
@@ -182,6 +183,8 @@ You don't need to memorize tool names, parameters, or JSON structures — just t
 | *"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 |
+| *"Export my collection to Postman"* | Writes a `.postman_collection.json` file ready to import |
+| *"Export the dev environment for Postman"* | Writes a `.postman_environment.json` file ready to import |
 | *"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 |
 
@@ -396,6 +399,54 @@ BULK TEST — 8/8 passed | 1.2s total
   login        — POST /auth/login  → 200 (156ms)
 ```
 
+### Postman Export
+
+Export your saved requests and environments as Postman-compatible JSON files. The files are written to a `postman/` folder in your project, ready to import in Postman.
+
+```
+"Export my collection to Postman"
+"Export only the smoke tests to Postman"
+"Export the dev environment for Postman"
+```
+
+**What you get:**
+
+```
+your-project/
+└── postman/
+    ├── my-api.postman_collection.json       ← Import in Postman: File → Import
+    └── dev.postman_environment.json          ← Import in Postman: File → Import
+```
+
+**Collection features:**
+- Requests grouped in **folders by tag** (smoke, auth, users, etc.)
+- Auth (Bearer, API Key, Basic) mapped to Postman's native auth format
+- `{{variables}}` preserved as-is (Postman uses the same syntax)
+- Headers, query params, and JSON body included
+- Collection variables from your active environment
+
+**Environment features:**
+- All variables exported with `enabled: true`
+- Postman-compatible format (`_postman_variable_scope: "environment"`)
+- Works with any environment (active or by name)
+
+<details>
+<summary>Example: exporting with a specific tag</summary>
+
+```
+You: "Export my smoke tests to Postman as 'Smoke Tests'"
+```
+
+This creates `postman/smoke-tests.postman_collection.json` with only the requests tagged `smoke`, grouped in folders.
+
+You can also specify a custom output directory:
+
+```
+You: "Export my collection to Postman in the exports folder"
+```
+
+</details>
+
 ### cURL Export
 
 Convert any saved request into a ready-to-paste cURL command with resolved variables.
@@ -443,7 +494,7 @@ Resolution order: project-specific environment → global active environment.
 
 ## Tool Reference
 
-27 tools organized in 8 categories:
+29 tools organized in 8 categories:
 
 | Category | Tools | Count |
 |----------|-------|-------|
@@ -454,7 +505,7 @@ Resolution order: project-specific environment → global active environment.
 | **Environments** | `env_create` `env_list` `env_set` `env_get` `env_switch` `env_rename` `env_delete` `env_spec` `env_project_clear` `env_project_list` | 10 |
 | **API Specs** | `api_import` `api_spec_list` `api_endpoints` `api_endpoint_detail` | 4 |
 | **Mock** | `mock` | 1 |
-| **Utilities** | `load_test` `export_curl` `diff_responses` `bulk_test` | 4 |
+| **Utilities** | `load_test` `export_curl` `diff_responses` `bulk_test` `export_postman_collection` `export_postman_environment` | 6 |
 
 You don't need to call these tools directly. Just describe what you want and the AI picks the right one.
 
@@ -490,14 +541,14 @@ Override the default directory in your MCP config:
 Built for reliability and testability:
 
 - **Zero runtime dependencies** — only `@modelcontextprotocol/sdk` and `zod`
-- **83 integration tests** with mocked fetch (no network calls in CI)
+- **96 integration tests** with mocked fetch (no network calls in CI)
 - **Factory pattern** — `createServer(storageDir?)` for isolated test instances
 - **Strict TypeScript** — zero `any`, full type coverage
-- **< 90KB** bundled output via tsup
+- **< 95KB** bundled output via tsup
 
 ```
 src/
-├── tools/           # 27 MCP tool handlers (one file per category)
+├── tools/           # 29 MCP tool handlers (one file per category)
 ├── lib/             # Business logic (no MCP dependency)
 │   ├── http-client  # fetch wrapper with timing
 │   ├── storage      # JSON file storage engine
@@ -506,7 +557,7 @@ src/
 │   ├── path         # Dot-notation accessor (body.data.0.id)
 │   ├── interpolation # {{variable}} resolver
 │   └── openapi-parser # $ref + allOf/oneOf/anyOf resolution
-└── __tests__/       # 10 test suites, 83 tests
+└── __tests__/       # 10 test suites, 96 tests
 ```
 
 ---
@@ -527,7 +578,7 @@ src/
 git clone https://github.com/cocaxcode/api-testing-mcp.git
 cd api-testing-mcp
 npm install
-npm test            # 83 tests across 10 suites
+npm test            # 96 tests across 10 suites
 npm run build       # ESM bundle via tsup
 npm run typecheck   # Strict TypeScript
 ```

package/dist/index.js

@@ -424,7 +424,8 @@ function interpolateRequest(config, variables) {
     url: interpolateString(config.url, variables),
     headers: interpolateRecord(config.headers, variables),
     query: interpolateRecord(config.query, variables),
-    body: config.body !== void 0 ? interpolateValue(config.body, variables) : void 0
+    body: config.body !== void 0 ? interpolateValue(config.body, variables) : void 0,
+    auth: config.auth ? interpolateValue(config.auth, variables) : void 0
   };
 }
 
@@ -1859,6 +1860,8 @@ function registerFlowTool(server, storage) {
 
 // src/tools/utilities.ts
 import { z as z8 } from "zod";
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { join as join2 } from "path";
 function registerUtilityTools(server, storage) {
   server.tool(
     "export_curl",
@@ -2138,6 +2141,251 @@ ${curlCommand}`
       }
     }
   );
+  server.tool(
+    "export_postman_collection",
+    "Exporta los requests guardados como una Postman Collection v2.1 (JSON). Escribe el archivo en disco, importable directamente en Postman.",
+    {
+      name: z8.string().optional().describe('Nombre de la colecci\xF3n (default: "API Testing Collection")'),
+      tag: z8.string().optional().describe("Filtrar requests por tag"),
+      output_dir: z8.string().optional().describe("Directorio donde guardar el archivo (default: ./postman/)"),
+      resolve_variables: z8.boolean().optional().describe("Resolver {{variables}} del entorno activo (default: false)")
+    },
+    async (params) => {
+      try {
+        const collections = await storage.listCollections(params.tag);
+        if (collections.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: params.tag ? `No hay requests guardados con tag '${params.tag}'.` : "No hay requests guardados en la colecci\xF3n."
+              }
+            ]
+          };
+        }
+        const resolveVars = params.resolve_variables ?? false;
+        const variables = resolveVars ? await storage.getActiveVariables() : {};
+        const savedRequests = [];
+        for (const item of collections) {
+          const saved = await storage.getCollection(item.name);
+          if (saved) savedRequests.push(saved);
+        }
+        const tagged = /* @__PURE__ */ new Map();
+        const untagged = [];
+        for (const saved of savedRequests) {
+          if (saved.tags && saved.tags.length > 0) {
+            const tag = saved.tags[0];
+            if (!tagged.has(tag)) tagged.set(tag, []);
+            tagged.get(tag).push(saved);
+          } else {
+            untagged.push(saved);
+          }
+        }
+        const items = [];
+        for (const [tag, requests] of tagged) {
+          items.push({
+            name: tag,
+            item: requests.map((r) => buildPostmanItem(r, variables, resolveVars))
+          });
+        }
+        for (const saved of untagged) {
+          items.push(buildPostmanItem(saved, variables, resolveVars));
+        }
+        const activeVars = await storage.getActiveVariables();
+        const collectionVars = Object.entries(activeVars).map(([key, value]) => ({
+          key,
+          value,
+          type: "string"
+        }));
+        const collectionName = params.name ?? "API Testing Collection";
+        const postmanCollection = {
+          info: {
+            name: collectionName,
+            schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+          },
+          item: items,
+          variable: collectionVars
+        };
+        const json = JSON.stringify(postmanCollection, null, 2);
+        const outputDir = params.output_dir ?? join2(process.cwd(), "postman");
+        await mkdir2(outputDir, { recursive: true });
+        const fileName = collectionName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") + ".postman_collection.json";
+        const filePath = join2(outputDir, fileName);
+        await writeFile2(filePath, json, "utf-8");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Postman Collection v2.1 exportada (${savedRequests.length} requests).
+
+Archivo: ${filePath}
+
+Importa este archivo en Postman: File \u2192 Import \u2192 selecciona el archivo.`
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+  server.tool(
+    "export_postman_environment",
+    "Exporta un entorno como Postman Environment (JSON). Escribe el archivo en disco, importable directamente en Postman.",
+    {
+      name: z8.string().optional().describe("Nombre del entorno a exportar (default: entorno activo)"),
+      output_dir: z8.string().optional().describe("Directorio donde guardar el archivo (default: ./postman/)")
+    },
+    async (params) => {
+      try {
+        let envName = params.name;
+        if (!envName) {
+          envName = await storage.getActiveEnvironment() ?? void 0;
+          if (!envName) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: 'No hay entorno activo. Especifica un nombre con el par\xE1metro "name".'
+                }
+              ],
+              isError: true
+            };
+          }
+        }
+        const env = await storage.getEnvironment(envName);
+        if (!env) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Entorno '${envName}' no encontrado.`
+              }
+            ],
+            isError: true
+          };
+        }
+        const postmanEnv = {
+          name: env.name,
+          values: Object.entries(env.variables).map(([key, value]) => ({
+            key,
+            value,
+            type: "default",
+            enabled: true
+          })),
+          _postman_variable_scope: "environment"
+        };
+        const json = JSON.stringify(postmanEnv, null, 2);
+        const outputDir = params.output_dir ?? join2(process.cwd(), "postman");
+        await mkdir2(outputDir, { recursive: true });
+        const fileName = env.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") + ".postman_environment.json";
+        const filePath = join2(outputDir, fileName);
+        await writeFile2(filePath, json, "utf-8");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Postman Environment "${env.name}" exportado (${Object.keys(env.variables).length} variables).
+
+Archivo: ${filePath}
+
+Importa este archivo en Postman: File \u2192 Import \u2192 selecciona el archivo.`
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+function buildPostmanItem(saved, variables, resolveVars) {
+  let config = saved.request;
+  if (resolveVars) {
+    const resolvedUrl = resolveUrl(config.url, variables);
+    config = { ...config, url: resolvedUrl };
+    config = interpolateRequest(config, variables);
+  }
+  const item = {
+    name: saved.name,
+    request: buildPostmanRequest(config)
+  };
+  return item;
+}
+function buildPostmanRequest(config) {
+  const request = {
+    method: config.method,
+    header: buildPostmanHeaders(config.headers),
+    url: buildPostmanUrl(config.url, config.query)
+  };
+  if (config.body !== void 0 && config.body !== null) {
+    request.body = {
+      mode: "raw",
+      raw: typeof config.body === "string" ? config.body : JSON.stringify(config.body, null, 2),
+      options: { raw: { language: "json" } }
+    };
+    const headers = request.header;
+    if (!headers.some((h) => h.key.toLowerCase() === "content-type")) {
+      headers.push({ key: "Content-Type", value: "application/json" });
+    }
+  }
+  if (config.auth) {
+    request.auth = buildPostmanAuth(config.auth);
+  }
+  return request;
+}
+function buildPostmanHeaders(headers) {
+  if (!headers) return [];
+  return Object.entries(headers).map(([key, value]) => ({ key, value }));
+}
+function buildPostmanUrl(rawUrl, query) {
+  const url = { raw: rawUrl };
+  const match = rawUrl.match(/^(https?):\/\/([^/]+)(\/.*)?$/);
+  if (match) {
+    url.protocol = match[1];
+    url.host = match[2].split(".");
+    url.path = match[3] ? match[3].slice(1).split("/") : [];
+  }
+  if (query && Object.keys(query).length > 0) {
+    url.query = Object.entries(query).map(([key, value]) => ({ key, value }));
+    const queryStr = Object.entries(query).map(([k, v]) => `${k}=${v}`).join("&");
+    url.raw = rawUrl + (rawUrl.includes("?") ? "&" : "?") + queryStr;
+  }
+  return url;
+}
+function buildPostmanAuth(auth) {
+  switch (auth.type) {
+    case "bearer":
+      return {
+        type: "bearer",
+        bearer: [{ key: "token", value: auth.token ?? "", type: "string" }]
+      };
+    case "api-key":
+      return {
+        type: "apikey",
+        apikey: [
+          { key: "key", value: auth.key ?? "", type: "string" },
+          { key: "value", value: auth.header ?? "X-API-Key", type: "string" },
+          { key: "in", value: "header", type: "string" }
+        ]
+      };
+    case "basic":
+      return {
+        type: "basic",
+        basic: [
+          { key: "username", value: auth.username ?? "", type: "string" },
+          { key: "password", value: auth.password ?? "", type: "string" }
+        ]
+      };
+  }
 }
 
 // src/tools/mock.ts