@postman/postman-mcp-server 2.5.1 → 2.5.2

package/README.md

@@ -16,6 +16,7 @@ Postman also offers servers as an [npm package](https://www.npmjs.com/package/@p
 
 ### Use Cases
 
+* **API Testing** - Continuously test your API using your Postman collection.
 * **Code synchronization** - Effortlessly keep your code in sync with your [Postman Collections](https://learning.postman.com/docs/design-apis/collections/overview/) and specs.
 * **Collection management** - Create and [tag](https://learning.postman.com/docs/collections/use-collections/collaborate-with-collections/#tag-a-collection) collections, update collection and request [documentation](https://learning.postman.com/docs/publishing-your-api/api-documentation-overview/), add [comments](https://learning.postman.com/docs/collaborating-in-postman/comments/), or perform actions across multiple collections without leaving your editor.
 * **Workspace and environment management** - Create [workspaces](https://learning.postman.com/docs/collaborating-in-postman/using-workspaces/overview/) and [environments](https://learning.postman.com/docs/sending-requests/variables/managing-environments/), plus manage your environment variables.

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@postman/postman-mcp-server",
-    "version": "2.5.1",
+    "version": "2.5.2",
     "description": "A simple MCP server to operate on the Postman API",
     "mcpName": "com.postman/postman-mcp-server",
     "main": "dist/src/index.js",

package/dist/src/clients/postman.js

@@ -8,10 +8,12 @@ export var ContentType;
 export class PostmanAPIClient {
     baseUrl;
     apiKey;
+    serverContext;
     static instance = null;
-    constructor(apiKey, baseUrl = process.env.POSTMAN_API_BASE_URL || 'https://api.postman.com') {
+    constructor(apiKey, baseUrl = process.env.POSTMAN_API_BASE_URL || 'https://api.postman.com', serverContext) {
         this.apiKey = apiKey;
         this.baseUrl = baseUrl;
+        this.serverContext = serverContext;
     }
     static getInstance(apiKey, baseUrl) {
         if (!PostmanAPIClient.instance) {
@@ -45,7 +47,10 @@ export class PostmanAPIClient {
         const contentType = options.contentType || ContentType.Json;
         const userAgentKey = Object.keys(options.headers ?? {}).find((key) => key.toLowerCase() === 'user-agent');
         const userAgentValue = userAgentKey ? options.headers?.[userAgentKey] : undefined;
-        const userAgentHeader = userAgentValue ? `${userAgentValue}/${USER_AGENT}` : USER_AGENT;
+        let userAgentHeader = userAgentValue ? `${userAgentValue}/${USER_AGENT}` : USER_AGENT;
+        if (this.serverContext?.serverType) {
+            userAgentHeader = `${userAgentHeader} (toolset: ${this.serverContext.serverType})`;
+        }
         const disallowed = new Set([
             'content-length',
             'transfer-encoding',

package/dist/src/enabledResources.js

@@ -103,6 +103,7 @@ const full = [
     'getStatusOfAnAsyncApiTask',
     'getAuthenticatedUser',
     'getTaggedEntities',
+    'getCodeGenerationInstructions',
     'transferCollectionFolders',
     'transferCollectionResponses',
     'transferCollectionResponses',
@@ -173,10 +174,18 @@ const excludedFromGeneration = [
     'getEnabledTools',
     'getCodeGenerationInstructions',
     'getCollectionMap',
+    'getCollection',
 ];
+const subtools = {
+    getCollection: {
+        orchestrator: 'getCollection',
+        subtools: ['getCollection', 'getCollectionMap'],
+    },
+};
 export const enabledResources = {
     full,
     minimal,
     code,
     excludedFromGeneration,
+    subtools,
 };

package/dist/src/index.js

@@ -139,11 +139,11 @@ async function run() {
         await server.close();
         process.exit(0);
     });
-    const client = new PostmanAPIClient(apiKey);
     const serverContext = {
         serverType: useCode ? 'code' : useFull ? 'full' : 'minimal',
         availableTools: tools.map((t) => t.method),
     };
+    const client = new PostmanAPIClient(apiKey, undefined, serverContext);
     log('info', 'Registering tools with McpServer');
     for (const tool of tools) {
         server.tool(tool.method, tool.description, tool.parameters.shape, tool.annotations || {}, async (args, extra) => {

package/dist/src/tools/getCollection/getCollection.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { asMcpError, McpError } from '../utils/toolHelpers.js';
+export const method = 'getCollection';
+export const description = "Gets information about a collection. For a complete list of this endpoint's possible values, refer to the [Postman Collection Format documentation](https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html).";
+export const parameters = z.object({
+    collectionId: z
+        .string()
+        .describe('The collection ID must be in the form <OWNER_ID>-<UUID> (e.g. 12345-33823532ab9e41c9b6fd12d0fd459b8b).'),
+    access_key: z
+        .string()
+        .describe("A collection's read-only access key. Using this query parameter does not require an API key to call the endpoint.")
+        .optional(),
+    model: z
+        .literal('minimal')
+        .describe("Return a list of only the collection's root-level request (`rootLevelRequests`) and folder (`rootLevelFolders`) IDs instead of the full collection element data.")
+        .optional(),
+});
+export const annotations = {
+    title: "Gets information about a collection. For a complete list of this endpoint's possible values, refer to the [Postman Collection Format documentation](https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html).",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+};
+export async function handler(args, extra) {
+    try {
+        const endpoint = `/collections/${args.collectionId}`;
+        const query = new URLSearchParams();
+        if (args.access_key !== undefined)
+            query.set('access_key', String(args.access_key));
+        if (args.model !== undefined)
+            query.set('model', String(args.model));
+        const url = query.toString() ? `${endpoint}?${query.toString()}` : endpoint;
+        const options = {
+            headers: extra.headers,
+        };
+        const result = await extra.client.get(url, options);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${typeof result === 'string' ? result : JSON.stringify(result, null, 2)}`,
+                },
+            ],
+        };
+    }
+    catch (e) {
+        if (e instanceof McpError) {
+            throw e;
+        }
+        throw asMcpError(e);
+    }
+}

package/dist/src/tools/getCollection/getCollectionMap.js

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { asMcpError, McpError } from '../utils/toolHelpers.js';
+export const method = 'getCollectionMap';
+export const description = `Get a Postman collection map with metadata and a complete recursive index of all folders and requests. Response includes collection metadata and description. Response includes itemRefs property (name and id only) instead of the full item array. After calling, present the collection summary and ask the user where they\'d like to explore next, calling getCollectionFolder and/or getCollectionRequest tools in parallel to get more data quickly.
+  Once you've called this tool, DO NOT call searchPostmanElements to find items in or related to this collection. Instead, use the map in itemRefs.
+  Only use searchPostmanElements to find the collection where a request may be. Then, stay in the collection and don't use the search.
+  When using the getCollectionRequest tool to look up request data, omit the populate parameter to avoid getting all response examples
+  back at once (can be very large). Instead, use the response ids from the return value and call getCollectionResponse for each one.
+  Prepend the collection's ownerId to the front of each response id when passing it to getCollectionResponse. This is the first part of the collection uid.
+  Infer the response schema from that information and remember it. Omit the raw response examples from the conversation going forward.`;
+export const parameters = z.object({
+    collectionId: z
+        .string()
+        .describe('The collection ID must be in the form <OWNER_ID>-<UUID> (e.g. 12345-33823532ab9e41c9b6fd12d0fd459b8b).'),
+    access_key: z
+        .string()
+        .describe("A collection's read-only access key. Using this query parameter does not require an API key to call the endpoint.")
+        .optional(),
+});
+export const annotations = {
+    title: 'Get Postman Collection Map',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+};
+function buildItemRefs(items) {
+    if (!Array.isArray(items) || items.length === 0) {
+        return undefined;
+    }
+    return items.map((item) => {
+        const itemId = item.uid || item.id || '';
+        const itemRef = {
+            name: item.name || '',
+            id: itemId,
+        };
+        if (item.item && Array.isArray(item.item)) {
+            const nestedRefs = buildItemRefs(item.item);
+            if (nestedRefs) {
+                itemRef.itemRefs = nestedRefs;
+            }
+        }
+        return itemRef;
+    });
+}
+export async function handler(args, extra) {
+    try {
+        const endpoint = `/collections/${args.collectionId}`;
+        const query = new URLSearchParams();
+        if (args.access_key !== undefined)
+            query.set('access_key', String(args.access_key));
+        const url = query.toString() ? `${endpoint}?${query.toString()}` : endpoint;
+        const options = {
+            headers: extra.headers,
+        };
+        const result = await extra.client.get(url, options);
+        if (typeof result === 'string') {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: result,
+                    },
+                ],
+            };
+        }
+        const response = result;
+        if (response.collection) {
+            const { item, ...collectionWithoutItems } = response.collection;
+            const itemRefs = buildItemRefs(item);
+            const processedResponse = {
+                ...response,
+                collection: {
+                    ...collectionWithoutItems,
+                    ...(itemRefs && { itemRefs }),
+                },
+            };
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(processedResponse, null, 2),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (e) {
+        if (e instanceof McpError) {
+            throw e;
+        }
+        throw asMcpError(e);
+    }
+}

package/dist/src/tools/getCollection/index.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { McpError, asMcpError } from '../utils/toolHelpers.js';
+import { handler as getCollectionApiHandler, parameters as getCollectionApiParameters, } from './getCollection.js';
+import { handler as getCollectionMapHandler } from './getCollectionMap.js';
+export const method = 'getCollection';
+export const description = `Get information about a collection. By default this tool returns the lightweight collection map (metadata + recursive itemRefs).
+Use the model parameter to opt in to Postman's full API responses:
+- model=minimal — root-level folder/request IDs only
+- model=full — full Postman collection payload.`;
+const baseParameters = getCollectionApiParameters.pick({
+    collectionId: true,
+    access_key: true,
+});
+export const parameters = baseParameters.extend({
+    model: z
+        .enum(['minimal', 'full'])
+        .describe('Optional response shape override. Omit to receive the lightweight collection map. Set to `minimal` for the Postman minimal model or `full` for the complete collection payload.')
+        .optional(),
+});
+export const annotations = {
+    title: 'Get Collection (map by default)',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+};
+function omitModel(args) {
+    const { model: _ignored, ...rest } = args;
+    return rest;
+}
+export async function handler(args, extra) {
+    try {
+        if (!args.model) {
+            return await getCollectionMapHandler(omitModel(args), extra);
+        }
+        if (args.model === 'minimal') {
+            return await getCollectionApiHandler({ ...args, model: 'minimal' }, extra);
+        }
+        return await getCollectionApiHandler(omitModel(args), extra);
+    }
+    catch (e) {
+        if (e instanceof McpError) {
+            throw e;
+        }
+        throw asMcpError(e);
+    }
+}

package/dist/src/tools/getCollection.js

@@ -1,52 +1 @@
-import { z } from 'zod';
-import { asMcpError, McpError } from './utils/toolHelpers.js';
-export const method = 'getCollection';
-export const description = "Gets information about a collection. For a complete list of this endpoint's possible values, refer to the [Postman Collection Format documentation](https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html).";
-export const parameters = z.object({
-    collectionId: z
-        .string()
-        .describe('The collection ID must be in the form <OWNER_ID>-<UUID> (e.g. 12345-33823532ab9e41c9b6fd12d0fd459b8b).'),
-    access_key: z
-        .string()
-        .describe("A collection's read-only access key. Using this query parameter does not require an API key to call the endpoint.")
-        .optional(),
-    model: z
-        .literal('minimal')
-        .describe("Return a list of only the collection's root-level request (`rootLevelRequests`) and folder (`rootLevelFolders`) IDs instead of the full collection element data.")
-        .optional(),
-});
-export const annotations = {
-    title: "Gets information about a collection. For a complete list of this endpoint's possible values, refer to the [Postman Collection Format documentation](https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html).",
-    readOnlyHint: true,
-    destructiveHint: false,
-    idempotentHint: true,
-};
-export async function handler(args, extra) {
-    try {
-        const endpoint = `/collections/${args.collectionId}`;
-        const query = new URLSearchParams();
-        if (args.access_key !== undefined)
-            query.set('access_key', String(args.access_key));
-        if (args.model !== undefined)
-            query.set('model', String(args.model));
-        const url = query.toString() ? `${endpoint}?${query.toString()}` : endpoint;
-        const options = {
-            headers: extra.headers,
-        };
-        const result = await extra.client.get(url, options);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `${typeof result === 'string' ? result : JSON.stringify(result, null, 2)}`,
-                },
-            ],
-        };
-    }
-    catch (e) {
-        if (e instanceof McpError) {
-            throw e;
-        }
-        throw asMcpError(e);
-    }
-}
+export { method, description, parameters, annotations, handler } from './getCollection/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman/postman-mcp-server",
-  "version": "2.5.1",
+  "version": "2.5.2",
   "description": "A simple MCP server to operate on the Postman API",
   "mcpName": "com.postman/postman-mcp-server",
   "main": "dist/src/index.js",