rest_to_postman_collection
Convert REST API endpoints to Postman collections, synchronizing API definitions with Postman while preserving existing customizations during updates.
Instructions
Creates or updates a Postman collection with the provided collection configuration. This tool helps synchronize your REST API endpoints with Postman. When updating an existing collection, it intelligently merges the new endpoints with existing ones, avoiding duplicates while preserving custom modifications made in Postman. Here's an example:
{
"info": {
"name": "REST Collection",
"description": "REST Collection",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"auth": {
"type": "bearer",
"bearer": [
{
"key": "Authorization",
"value": "Bearer {{API_TOKEN}}",
"type": "string"
}
]
},
"item": [
{
"name": "Get Users",
"request": {
"method": "GET",
"url": {
"raw": "{{API_URL}}/users",
"protocol": "https",
"host": ["api", "example", "com"],
"path": ["users"]
}
}
},
{
"name": "Create User",
"request": {
"method": "POST",
"url": {
"raw": "{{API_URL}}/users"
},
"body": {
"mode": "raw",
"raw": "{"name":"John Doe","email":"john.doe@example.com"}"
}
}
}
]
}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| collectionRequest | Yes | The Postman collection configuration containing info, items, and other collection details |
Implementation Reference
- src/postman.ts:144-257 (handler)Core handler function that creates or updates a Postman collection by calling the Postman API. Handles merging new items with existing collection without duplicates, preserving custom modifications.
export async function pushCollection(collectionRequest: PostmanCollectionRequest, postmanApiKey?: string, workspaceId?: string): Promise<void> { try { const apiKey = postmanApiKey || process.env.POSTMAN_API_KEY; const activeWorkspaceId = workspaceId || process.env.POSTMAN_ACTIVE_WORKSPACE_ID; // Create collection container const containerRequestBody = { collection: collectionRequest, workspace: activeWorkspaceId }; // Check if collection already exists try { const workspaceResponse = await axios({ method: 'get', url: `https://api.getpostman.com/workspaces/${activeWorkspaceId}`, headers: { 'X-Api-Key': apiKey } }); const workspaceData = workspaceResponse.data as PostmanWorkspaceResponse; var existingCollection = workspaceData.workspace.collections?.find( collection => collection.name === collectionRequest.info.name ); } catch (error) { console.error('Error in pushCollection:', error); } let response; if (existingCollection) { // Reuse getCollection to fetch existing collection data const existingCollectionData = await getCollection(collectionRequest.info.name, apiKey, activeWorkspaceId); // Helper function to normalize request for comparison const normalizeRequest = (request: PostmanRequest) => { const normalized = JSON.parse(JSON.stringify(request)); // Remove id and uid delete normalized.id; delete normalized.uid; // Remove empty arrays if (normalized.response && normalized.response.length === 0) delete normalized.response; if (normalized.request?.header && normalized.request.header.length === 0) delete normalized.request.header; return JSON.stringify(normalized); }; // Deduplicate items while merging const existingItems = existingCollectionData.item || []; const newItems = collectionRequest.item || []; const uniqueItems = [...existingItems]; for (const newItem of newItems) { const normalizedNew = normalizeRequest(newItem); const isDuplicate = uniqueItems.some(existingItem => normalizeRequest(existingItem) === normalizedNew ); if (!isDuplicate) { uniqueItems.push(newItem); } } // Merge the collections const mergedCollection: PostmanCollectionRequest = { info: { ...existingCollectionData.info, ...collectionRequest.info }, auth: collectionRequest.auth || existingCollectionData.auth, item: uniqueItems, event: [...(existingCollectionData.event || []), ...(collectionRequest.event || [])] }; // remove `auth` if it is empty if (mergedCollection.auth && Object.keys(mergedCollection.auth).length === 0) { delete mergedCollection.auth; } // console.log(JSON.stringify(mergedCollection, null, 2)); // Update with merged data response = await axios({ method: 'put', url: `https://api.getpostman.com/collections/${existingCollection.id}`, headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' }, data: { collection: mergedCollection, workspace: activeWorkspaceId } }); } else { // Remove `auth` if it is empty if (containerRequestBody.collection.auth && Object.keys(containerRequestBody.collection.auth).length === 0) { delete containerRequestBody.collection.auth; } response = await axios({ method: 'post', url: 'https://api.getpostman.com/collections', headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' }, data: containerRequestBody }); } } catch (error) { console.error('Error in pushCollection:', error); throw error; } } - src/mcp.ts:103-333 (registration)Tool registration in the tools array, including name, description, and input schema for listTools request.
{ "name": "rest_to_postman_collection", "description": "Creates or updates a Postman collection with the provided collection configuration. This tool helps synchronize your REST API endpoints with Postman. When updating an existing collection, it intelligently merges the new endpoints with existing ones, avoiding duplicates while preserving custom modifications made in Postman. Here's an example: \n\n" + collectionExample, "inputSchema": { "type": "object", "properties": { "collectionRequest": { "type": "object", "description": "The Postman collection configuration containing info, items, and other collection details", "properties": { "info": { "type": "object", "description": "Collection information including name and schema", "properties": { "name": { "type": "string", "description": "Name of the collection" }, "description": { "type": "string", "description": "Description of the collection" }, "schema": { "type": "string", "description": "Schema version of the collection" } }, "required": ["name", "description", "schema"] }, "auth": { "type": "object", "description": "Authentication settings for the collection", "properties": { "type": { "type": "string", "description": "Type of authentication (e.g., 'bearer')" }, "bearer": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Key for the bearer token" }, "value": { "type": "string", "description": "Value of the bearer token" }, "type": { "type": "string", "description": "Type of the bearer token" } }, "required": ["key", "value", "type"] } } }, "required": ["type"] }, "item": { "type": "array", "description": "Array of request items in the collection", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the request" }, "request": { "type": "object", "properties": { "method": { "type": "string", "description": "HTTP method of the request" }, "url": { "type": "object", "properties": { "raw": { "type": "string", "description": "Raw URL string" }, "protocol": { "type": "string", "description": "URL protocol (e.g., 'http', 'https')" }, "host": { "type": "array", "items": { "type": "string" }, "description": "Host segments" }, "path": { "type": "array", "items": { "type": "string" }, "description": "URL path segments" }, "query": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Query parameter key" }, "value": { "type": "string", "description": "Query parameter value" } }, "required": ["key", "value"] } } }, "required": ["raw", "protocol", "host", "path"] }, "auth": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of authentication" }, "bearer": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" }, "type": { "type": "string" } }, "required": ["key", "value", "type"] } } }, "required": ["type"] }, "description": { "type": "string", "description": "Description of the request" } }, "required": ["method", "url"] }, "event": { "type": "array", "items": { "type": "object", "properties": { "listen": { "type": "string", "description": "Event type to listen for" }, "script": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of script" }, "exec": { "type": "array", "items": { "type": "string" }, "description": "Array of script lines to execute" } }, "required": ["type", "exec"] } }, "required": ["listen", "script"] } } }, "required": ["name", "request"] } }, "event": { "type": "array", "description": "Collection-level event scripts", "items": { "type": "object", "properties": { "listen": { "type": "string", "description": "Event type to listen for" }, "script": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of script" }, "exec": { "type": "array", "items": { "type": "string" }, "description": "Array of script lines to execute" } }, "required": ["type", "exec"] } }, "required": ["listen", "script"] } } }, "required": ["info", "item"] } }, "required": ["collectionRequest"] } } ]; - src/mcp.ts:106-331 (schema)Input schema definition for the tool, defining the structure of collectionRequest parameter matching PostmanCollectionRequest type.
"inputSchema": { "type": "object", "properties": { "collectionRequest": { "type": "object", "description": "The Postman collection configuration containing info, items, and other collection details", "properties": { "info": { "type": "object", "description": "Collection information including name and schema", "properties": { "name": { "type": "string", "description": "Name of the collection" }, "description": { "type": "string", "description": "Description of the collection" }, "schema": { "type": "string", "description": "Schema version of the collection" } }, "required": ["name", "description", "schema"] }, "auth": { "type": "object", "description": "Authentication settings for the collection", "properties": { "type": { "type": "string", "description": "Type of authentication (e.g., 'bearer')" }, "bearer": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Key for the bearer token" }, "value": { "type": "string", "description": "Value of the bearer token" }, "type": { "type": "string", "description": "Type of the bearer token" } }, "required": ["key", "value", "type"] } } }, "required": ["type"] }, "item": { "type": "array", "description": "Array of request items in the collection", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the request" }, "request": { "type": "object", "properties": { "method": { "type": "string", "description": "HTTP method of the request" }, "url": { "type": "object", "properties": { "raw": { "type": "string", "description": "Raw URL string" }, "protocol": { "type": "string", "description": "URL protocol (e.g., 'http', 'https')" }, "host": { "type": "array", "items": { "type": "string" }, "description": "Host segments" }, "path": { "type": "array", "items": { "type": "string" }, "description": "URL path segments" }, "query": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Query parameter key" }, "value": { "type": "string", "description": "Query parameter value" } }, "required": ["key", "value"] } } }, "required": ["raw", "protocol", "host", "path"] }, "auth": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of authentication" }, "bearer": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" }, "type": { "type": "string" } }, "required": ["key", "value", "type"] } } }, "required": ["type"] }, "description": { "type": "string", "description": "Description of the request" } }, "required": ["method", "url"] }, "event": { "type": "array", "items": { "type": "object", "properties": { "listen": { "type": "string", "description": "Event type to listen for" }, "script": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of script" }, "exec": { "type": "array", "items": { "type": "string" }, "description": "Array of script lines to execute" } }, "required": ["type", "exec"] } }, "required": ["listen", "script"] } } }, "required": ["name", "request"] } }, "event": { "type": "array", "description": "Collection-level event scripts", "items": { "type": "object", "properties": { "listen": { "type": "string", "description": "Event type to listen for" }, "script": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of script" }, "exec": { "type": "array", "items": { "type": "string" }, "description": "Array of script lines to execute" } }, "required": ["type", "exec"] } }, "required": ["listen", "script"] } } }, "required": ["info", "item"] } }, "required": ["collectionRequest"] } - src/mcp.ts:402-413 (handler)Dispatch handler in the MCP CallToolRequestSchema that invokes pushCollection for this specific tool name.
} else if (request.params.name === "rest_to_postman_collection") { if (!request.params.arguments) { throw new McpError(ErrorCode.InvalidParams, "Missing arguments"); } const { collectionRequest } = request.params.arguments as { collectionRequest: PostmanCollectionRequest }; await pushCollection(collectionRequest, process.env.POSTMAN_API_KEY, process.env.POSTMAN_ACTIVE_WORKSPACE_ID); return { content: [{ type: "text", text: `Successfully created/updated Postman collection: ${collectionRequest.info.name}` }] }; - src/types/index.ts:101-110 (schema)TypeScript interface defining the PostmanCollectionRequest used in the tool schema and handler.
export interface PostmanCollectionRequest { info: { name: string, description: string, schema: string }, auth?: Auth, item: PostmanRequest[], event?: ScriptEvent[] }