@postman/postman-mcp-server 2.7.0 → 2.8.0

package/dist/src/tools/searchPostmanElementsInPrivateNetwork.js

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+import { ContentType } from '../clients/postman.js';
+import { asMcpError, McpError } from './utils/toolHelpers.js';
+export const method = 'searchPostmanElementsInPrivateNetwork';
+export const description = `Search for API requests and collections in your organization's Private API Network—a curated repository of trusted, internal APIs shared by your team.
+
+**What is the Private API Network?**
+The Private API Network is where your organization stores vetted APIs for internal use. These are trusted team workspaces containing approved microservices, internal tools, and shared API collections.
+
+**When to Use This Tool:**
+- Finding internal/company trusted APIs (e.g., "find a trusted api for notification service", "find our payment APIs", "search for internal microservices")
+- Discovering trusted APIs shared within your organization
+- Looking up team-approved API collections and requests
+- When the user wants to find collections in the private network (e.g., "find internal access control collections", "search for payment API collections in our network")
+
+**Search Scope:**
+- Searches only trusted internal APIs in the Private API Network
+- Returns requests or collections from team workspaces published to the network
+
+**Entity Types:**
+- \`requests\`: Search for individual API requests (default)
+- \`collections\`: Search for collections (unique collections extracted from request results; pagination applies to underlying requests)`;
+export const parameters = z.object({
+    entityType: z
+        .enum(['requests', 'collections'])
+        .describe('The type of Postman element to search for. Use `requests` to search for individual API requests, or `collections` to search for collections (unique collections extracted from request results; pagination applies to underlying requests).')
+        .default('requests'),
+    q: z
+        .string()
+        .min(1)
+        .max(512)
+        .describe('The search query for API elements in the Private API Network (e.g. "invoices API", "notification service", "payment APIs").'),
+    nextCursor: z
+        .string()
+        .describe('The cursor to get the next set of results in the paginated response. If you pass an invalid value, the API returns empty results.')
+        .optional(),
+    limit: z
+        .number()
+        .int()
+        .gte(1)
+        .lte(10)
+        .describe('The max number of search results returned in the response.')
+        .default(10)
+        .optional(),
+});
+export const annotations = {
+    title: "Search for API requests and collections in your organization's Private API Network—a curated repository of trusted, internal APIs shared by your team.",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+};
+const PRIVATE_NETWORK_FILTER = {
+    $and: [
+        {
+            privateNetwork: {
+                $eq: true,
+            },
+        },
+    ],
+};
+export async function handler(args, extra) {
+    try {
+        const query = new URLSearchParams();
+        if (args.limit !== undefined)
+            query.set('limit', String(args.limit));
+        if (args.nextCursor !== undefined)
+            query.set('nextCursor', String(args.nextCursor));
+        const endpoint = query.toString() ? `/search?${query.toString()}` : '/search';
+        const body = {
+            q: args.q,
+            elementType: 'requests',
+            filters: PRIVATE_NETWORK_FILTER,
+        };
+        const options = {
+            body: JSON.stringify(body),
+            contentType: ContentType.Json,
+            headers: extra.headers,
+        };
+        const result = await extra.client.post(endpoint, options);
+        if (args.entityType === 'collections') {
+            const collectionsMap = new Map();
+            const data = result?.data || [];
+            for (const item of data) {
+                if (item.collection && !collectionsMap.has(item.collection.id)) {
+                    collectionsMap.set(item.collection.id, {
+                        collectionId: item.collection.id,
+                        collectionName: item.collection.name,
+                        workspaceId: item.workspace?.id,
+                        workspaceName: item.workspace?.name,
+                        publisher: item.publisher?.name,
+                        publisherVerified: item.publisher?.isVerified,
+                    });
+                }
+            }
+            const collections = Array.from(collectionsMap.values());
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            data: collections,
+                            meta: {
+                                nextCursor: result?.meta?.nextCursor,
+                                collectionsCount: collections.length,
+                                note: 'Collections extracted from request results. Pagination applies to underlying requests.',
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        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/{searchPostmanElements.js → searchPostmanElementsInPublicNetwork.js}

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { asMcpError, McpError } from './utils/toolHelpers.js';
-export const method = 'searchPostmanElements';
+export const method = 'searchPostmanElementsInPublicNetwork';
 export const description = 'Searches for Postman elements in the public network.\n\n**When to Use This Tool:**\n- When the user asks for a specific named request (e.g., "find PayPal requests", "search for Stripe API requests")\n- When the user wants to find collections (e.g., "find Stripe collections", "search for payment API collections")\n- When the user explicitly wants to search the public network\n- Do NOT use this for searching the user\'s own workspaces or collections (use getCollections or getWorkspaces instead)\n\n**Search Scope:**\n- Only searches the public network (public workspaces and collections)\n- Does not search private workspaces, team workspaces, or personal collections\n\n**Entity Types:**\n- `requests`: Search for individual API requests\n- `collections`: Search for collections (unique collections extracted from request results; pagination applies to underlying requests)\n';
 export const parameters = z.object({
     entityType: z

package/dist/src/tools/updateCollectionRequest.js

@@ -6,7 +6,8 @@ export const description = 'Updates a request in a collection. For a complete li
 export const parameters = z.object({
     requestId: z.string().describe("The request's ID."),
     collectionId: z.string().describe("The collection's ID."),
-    name: z.string().describe('Name of the request. Only provided fields are updated.').optional(),
+    name: z.string().describe("The request's name.").optional(),
+    description: z.string().nullable().describe("The request's description.").optional(),
     method: z
         .enum([
         'GET',
@@ -25,58 +26,81 @@ export const parameters = z.object({
         'PROPFIND',
         'VIEW',
     ])
-        .nullable()
-        .describe("The request's method.")
+        .describe("The request's HTTP method.")
         .optional(),
-    description: z.string().nullable().optional(),
-    url: z.string().nullable().optional(),
+    url: z.string().nullable().describe("The request's URL.").optional(),
     headerData: z
         .array(z.object({
-        key: z.string().optional(),
-        value: z.string().optional(),
-        description: z.string().nullable().optional(),
+        key: z.string().describe("The header's key.").optional(),
+        value: z.string().describe("The header's value.").optional(),
+        description: z.string().describe("The header's description.").optional(),
     }))
+        .describe("The request's headers.")
         .optional(),
     queryParams: z
         .array(z.object({
-        key: z.string().optional(),
-        value: z.string().optional(),
-        description: z.string().nullable().optional(),
-        enabled: z.boolean().optional(),
+        key: z.string().describe("The query parameter's key.").optional(),
+        value: z.string().describe("The query parameter's value.").optional(),
+        description: z.string().describe("The query parameter's description.").optional(),
+        enabled: z.boolean().describe('If true, the query parameter is enabled.').optional(),
     }))
+        .describe("The request's query parameters.")
+        .optional(),
+    dataMode: z
+        .enum(['raw', 'urlencoded', 'formdata', 'binary', 'graphql'])
+        .describe("The request body's data mode.")
         .optional(),
-    dataMode: z.enum(['raw', 'urlencoded', 'formdata', 'binary', 'graphql']).nullable().optional(),
     data: z
         .array(z.object({
-        key: z.string().optional(),
-        value: z.string().optional(),
-        description: z.string().nullable().optional(),
-        enabled: z.boolean().optional(),
-        type: z.enum(['text', 'file']).optional(),
-        uuid: z.string().optional(),
+        key: z.string().describe("The form data's key.").optional(),
+        value: z.string().describe("The form data's value.").optional(),
+        description: z.string().describe("The form data's description.").optional(),
+        enabled: z.boolean().describe('If true, the form data entry is enabled.').optional(),
+        type: z.enum(['text', 'file']).describe("The form data's type.").optional(),
+        uuid: z.string().describe("The form data entry's unique identifier.").optional(),
     }))
         .nullable()
+        .describe("The request body's form data.")
         .optional(),
-    rawModeData: z.string().nullable().optional(),
+    rawModeData: z.string().nullable().describe("The request body's raw mode data.").optional(),
     graphqlModeData: z
-        .object({ query: z.string().optional(), variables: z.string().optional() })
+        .object({
+        query: z.string().describe('The GraphQL query.').optional(),
+        variables: z.string().describe('The GraphQL query variables, in JSON format.').optional(),
+    })
         .nullable()
+        .describe("The request body's GraphQL mode data.")
         .optional(),
     dataOptions: z
         .object({
-        raw: z.record(z.string(), z.unknown()).optional(),
-        urlencoded: z.record(z.string(), z.unknown()).optional(),
-        params: z.record(z.string(), z.unknown()).optional(),
-        binary: z.record(z.string(), z.unknown()).optional(),
-        graphql: z.record(z.string(), z.unknown()).optional(),
+        raw: z
+            .object({ language: z.string().describe("The raw mode data's language type.").optional() })
+            .describe('Options for the `raw` data mode.')
+            .optional(),
+        urlencoded: z
+            .record(z.string(), z.unknown())
+            .describe('Options for the `urlencoded` data mode.')
+            .optional(),
+        params: z
+            .record(z.string(), z.unknown())
+            .describe('Options for the `params` data mode.')
+            .optional(),
+        binary: z
+            .record(z.string(), z.unknown())
+            .describe('Options for the `binary` data mode.')
+            .optional(),
+        graphql: z
+            .record(z.string(), z.unknown())
+            .describe('Options for the `graphql` data mode.')
+            .optional(),
     })
         .nullable()
+        .describe("Additional configurations and options set for the request body's various data modes.")
         .optional(),
     auth: z
         .object({
         type: z
             .enum([
-            'noauth',
             'basic',
             'bearer',
             'apikey',
@@ -89,94 +113,225 @@ export const parameters = z.object({
             'edgegrid',
             'jwt',
             'asap',
+            'noauth',
         ])
-            .optional(),
+            .describe('The authorization type.'),
         apikey: z
-            .array(z.object({
-            key: z.string().optional(),
-            value: z.unknown().optional(),
-            type: z.enum(['string', 'boolean', 'number', 'array', 'object', 'any']).optional(),
-        }))
+            .array(z
+            .object({
+            key: z.string().describe("The auth method's key value."),
+            value: z
+                .union([z.string(), z.array(z.record(z.string(), z.unknown()))])
+                .describe("The key's value.")
+                .optional(),
+            type: z
+                .enum(['string', 'boolean', 'number', 'array', 'object', 'any'])
+                .describe("The value's type.")
+                .optional(),
+        })
+            .describe('Information about the supported Postman [authorization type](https://learning.postman.com/docs/sending-requests/authorization/authorization-types/).'))
+            .describe("The API key's authentication information.")
             .optional(),
-        bearer: z
-            .array(z.object({
-            key: z.string().optional(),
-            value: z.unknown().optional(),
-            type: z.enum(['string', 'boolean', 'number', 'array', 'object', 'any']).optional(),
-        }))
+        awsv4: z
+            .array(z
+            .object({
+            key: z.string().describe("The auth method's key value."),
+            value: z
+                .union([z.string(), z.array(z.record(z.string(), z.unknown()))])
+                .describe("The key's value.")
+                .optional(),
+            type: z
+                .enum(['string', 'boolean', 'number', 'array', 'object', 'any'])
+                .describe("The value's type.")
+                .optional(),
+        })
+            .describe('Information about the supported Postman [authorization type](https://learning.postman.com/docs/sending-requests/authorization/authorization-types/).'))
+            .describe('The attributes for AWS Signature authentication.')
             .optional(),
         basic: z
-            .array(z.object({
-            key: z.string().optional(),
-            value: z.unknown().optional(),
-            type: z.enum(['string', 'boolean', 'number', 'array', 'object', 'any']).optional(),
-        }))
+            .array(z
+            .object({
+            key: z.string().describe("The auth method's key value."),
+            value: z
+                .union([z.string(), z.array(z.record(z.string(), z.unknown()))])
+                .describe("The key's value.")
+                .optional(),
+            type: z
+                .enum(['string', 'boolean', 'number', 'array', 'object', 'any'])
+                .describe("The value's type.")
+                .optional(),
+        })
+            .describe('Information about the supported Postman [authorization type](https://learning.postman.com/docs/sending-requests/authorization/authorization-types/).'))
+            .describe('The attributes for Basic Auth.')
             .optional(),
-        digest: z
-            .array(z.object({
-            key: z.string().optional(),
-            value: z.unknown().optional(),
-            type: z.enum(['string', 'boolean', 'number', 'array', 'object', 'any']).optional(),
-        }))
+        bearer: z
+            .array(z
+            .object({
+            key: z.string().describe("The auth method's key value."),
+            value: z
+                .union([z.string(), z.array(z.record(z.string(), z.unknown()))])
+                .describe("The key's value.")
+                .optional(),
+            type: z
+                .enum(['string', 'boolean', 'number', 'array', 'object', 'any'])
+                .describe("The value's type.")
+                .optional(),
+        })
+            .describe('Information about the supported Postman [authorization type](https://learning.postman.com/docs/sending-requests/authorization/authorization-types/).'))
+            .describe('The attributes for Bearer Token authentication.')
             .optional(),
-        oauth1: z
-            .array(z.object({
-            key: z.string().optional(),
-            value: z.unknown().optional(),
-            type: z.enum(['string', 'boolean', 'number', 'array', 'object', 'any']).optional(),
-        }))
+        digest: z
+            .array(z
+            .object({
+            key: z.string().describe("The auth method's key value."),
+            value: z
+                .union([z.string(), z.array(z.record(z.string(), z.unknown()))])
+                .describe("The key's value.")
+                .optional(),
+            type: z
+                .enum(['string', 'boolean', 'number', 'array', 'object', 'any'])
+                .describe("The value's type.")
+                .optional(),
+        })
+            .describe('Information about the supported Postman [authorization type](https://learning.postman.com/docs/sending-requests/authorization/authorization-types/).'))
+            .describe('The attributes for Digest access authentication.')
             .optional(),
-        oauth2: z
-            .array(z.object({
-            key: z.string().optional(),
-            value: z.unknown().optional(),
-            type: z.enum(['string', 'boolean', 'number', 'array', 'object', 'any']).optional(),
-        }))
+        edgegrid: z
+            .array(z
+            .object({
+            key: z.string().describe("The auth method's key value."),
+            value: z
+                .union([z.string(), z.array(z.record(z.string(), z.unknown()))])
+                .describe("The key's value.")
+                .optional(),
+            type: z
+                .enum(['string', 'boolean', 'number', 'array', 'object', 'any'])
+                .describe("The value's type.")
+                .optional(),
+        })
+            .describe('Information about the supported Postman [authorization type](https://learning.postman.com/docs/sending-requests/authorization/authorization-types/).'))
+            .describe('The attributes for Akamai Edgegrid authentication.')
             .optional(),
         hawk: z
-            .array(z.object({
-            key: z.string().optional(),
-            value: z.unknown().optional(),
-            type: z.enum(['string', 'boolean', 'number', 'array', 'object', 'any']).optional(),
-        }))
-            .optional(),
-        awsv4: z
-            .array(z.object({
-            key: z.string().optional(),
-            value: z.unknown().optional(),
-            type: z.enum(['string', 'boolean', 'number', 'array', 'object', 'any']).optional(),
-        }))
+            .array(z
+            .object({
+            key: z.string().describe("The auth method's key value."),
+            value: z
+                .union([z.string(), z.array(z.record(z.string(), z.unknown()))])
+                .describe("The key's value.")
+                .optional(),
+            type: z
+                .enum(['string', 'boolean', 'number', 'array', 'object', 'any'])
+                .describe("The value's type.")
+                .optional(),
+        })
+            .describe('Information about the supported Postman [authorization type](https://learning.postman.com/docs/sending-requests/authorization/authorization-types/).'))
+            .describe('The attributes for Hawk authentication.')
             .optional(),
         ntlm: z
-            .array(z.object({
-            key: z.string().optional(),
-            value: z.unknown().optional(),
-            type: z.enum(['string', 'boolean', 'number', 'array', 'object', 'any']).optional(),
-        }))
+            .array(z
+            .object({
+            key: z.string().describe("The auth method's key value."),
+            value: z
+                .union([z.string(), z.array(z.record(z.string(), z.unknown()))])
+                .describe("The key's value.")
+                .optional(),
+            type: z
+                .enum(['string', 'boolean', 'number', 'array', 'object', 'any'])
+                .describe("The value's type.")
+                .optional(),
+        })
+            .describe('Information about the supported Postman [authorization type](https://learning.postman.com/docs/sending-requests/authorization/authorization-types/).'))
+            .describe('The attributes for NTLM authentication.')
             .optional(),
-        edgegrid: z
-            .array(z.object({
-            key: z.string().optional(),
-            value: z.unknown().optional(),
-            type: z.enum(['string', 'boolean', 'number', 'array', 'object', 'any']).optional(),
-        }))
+        oauth1: z
+            .array(z
+            .object({
+            key: z.string().describe("The auth method's key value."),
+            value: z
+                .union([z.string(), z.array(z.record(z.string(), z.unknown()))])
+                .describe("The key's value.")
+                .optional(),
+            type: z
+                .enum(['string', 'boolean', 'number', 'array', 'object', 'any'])
+                .describe("The value's type.")
+                .optional(),
+        })
+            .describe('Information about the supported Postman [authorization type](https://learning.postman.com/docs/sending-requests/authorization/authorization-types/).'))
+            .describe('The attributes for OAuth1 authentication.')
+            .optional(),
+        oauth2: z
+            .array(z
+            .object({
+            key: z.string().describe("The auth method's key value."),
+            value: z
+                .union([z.string(), z.array(z.record(z.string(), z.unknown()))])
+                .describe("The key's value.")
+                .optional(),
+            type: z
+                .enum(['string', 'boolean', 'number', 'array', 'object', 'any'])
+                .describe("The value's type.")
+                .optional(),
+        })
+            .describe('Information about the supported Postman [authorization type](https://learning.postman.com/docs/sending-requests/authorization/authorization-types/).'))
+            .describe('The attributes for OAuth2 authentication.')
             .optional(),
         jwt: z
-            .array(z.object({
-            key: z.string().optional(),
-            value: z.unknown().optional(),
-            type: z.enum(['string', 'boolean', 'number', 'array', 'object', 'any']).optional(),
-        }))
+            .array(z
+            .object({
+            key: z.string().describe("The auth method's key value."),
+            value: z
+                .union([z.string(), z.array(z.record(z.string(), z.unknown()))])
+                .describe("The key's value.")
+                .optional(),
+            type: z
+                .enum(['string', 'boolean', 'number', 'array', 'object', 'any'])
+                .describe("The value's type.")
+                .optional(),
+        })
+            .describe('Information about the supported Postman [authorization type](https://learning.postman.com/docs/sending-requests/authorization/authorization-types/).'))
+            .describe('The attributes for JWT authentication.')
             .optional(),
         asap: z
-            .array(z.object({
-            key: z.string().optional(),
-            value: z.unknown().optional(),
-            type: z.enum(['string', 'boolean', 'number', 'array', 'object', 'any']).optional(),
-        }))
+            .array(z
+            .object({
+            key: z.string().describe("The auth method's key value."),
+            value: z
+                .union([z.string(), z.array(z.record(z.string(), z.unknown()))])
+                .describe("The key's value.")
+                .optional(),
+            type: z
+                .enum(['string', 'boolean', 'number', 'array', 'object', 'any'])
+                .describe("The value's type.")
+                .optional(),
+        })
+            .describe('Information about the supported Postman [authorization type](https://learning.postman.com/docs/sending-requests/authorization/authorization-types/).'))
+            .describe('The attributes for ASAP authentication.')
             .optional(),
     })
         .nullable()
+        .describe("The request's authentication information.")
+        .optional(),
+    events: z
+        .array(z.object({
+        listen: z.enum(['test', 'prerequest']).describe('The event type.').optional(),
+        script: z
+            .object({
+            id: z.string().describe("The script's ID.").optional(),
+            type: z
+                .string()
+                .describe('The type of script. For example, `text/javascript`.')
+                .optional(),
+            exec: z
+                .array(z.string().nullable())
+                .describe('A list of script strings, where each line represents a line of code. Separate lines makes it easy to track script changes.')
+                .optional(),
+        })
+            .describe('Information about the Javascript code that can be used to to perform setup or teardown operations in a response.')
+            .optional(),
+    }))
+        .nullable()
+        .describe('A list of scripts configured to run when specific events occur.')
         .optional(),
 });
 export const annotations = {
@@ -193,10 +348,10 @@ export async function handler(args, extra) {
         const bodyPayload = {};
         if (args.name !== undefined)
             bodyPayload.name = args.name;
-        if (args.method !== undefined)
-            bodyPayload.method = args.method;
         if (args.description !== undefined)
             bodyPayload.description = args.description;
+        if (args.method !== undefined)
+            bodyPayload.method = args.method;
         if (args.url !== undefined)
             bodyPayload.url = args.url;
         if (args.headerData !== undefined)
@@ -215,6 +370,8 @@ export async function handler(args, extra) {
             bodyPayload.dataOptions = args.dataOptions;
         if (args.auth !== undefined)
             bodyPayload.auth = args.auth;
+        if (args.events !== undefined)
+            bodyPayload.events = args.events;
         const options = {
             body: JSON.stringify(bodyPayload),
             contentType: ContentType.Json,