rest_to_postman_collection
Convert REST API configurations into Postman collections, synchronizing endpoints while merging updates intelligently to avoid duplicates and preserve custom modifications.
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 implementation of the rest_to_postman_collection tool. Handles creating new collections or intelligently merging/updating existing ones via Postman API, deduplicating requests based on normalized content.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-332 (registration)Tool registration in the tools list provided to MCP ListToolsRequest, including name, description, and detailed inputSchema.{ "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:402-413 (handler)MCP CallToolRequest handler dispatch for rest_to_postman_collection, validates arguments and calls the pushCollection implementation.} 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 type definition for PostmanCollectionRequest used as input type for the tool.export interface PostmanCollectionRequest { info: { name: string, description: string, schema: string }, auth?: Auth, item: PostmanRequest[], event?: ScriptEvent[] }