@postman/postman-mcp-server 2.5.2 → 2.5.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@postman/postman-mcp-server",
|
|
3
|
-
"version": "2.5.
|
|
3
|
+
"version": "2.5.3",
|
|
4
4
|
"description": "A simple MCP server to operate on the Postman API",
|
|
5
5
|
"mcpName": "com.postman/postman-mcp-server",
|
|
6
6
|
"main": "dist/src/index.js",
|
|
@@ -27,10 +27,11 @@
|
|
|
27
27
|
"access": "public"
|
|
28
28
|
},
|
|
29
29
|
"dependencies": {
|
|
30
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
30
|
+
"@modelcontextprotocol/sdk": "^1.25.2",
|
|
31
31
|
"dotenv": "^17.2.3",
|
|
32
32
|
"newman": "^6.2.0",
|
|
33
|
-
"uuid": "^13.0.0"
|
|
33
|
+
"uuid": "^13.0.0",
|
|
34
|
+
"zod": "^3.25.76"
|
|
34
35
|
},
|
|
35
36
|
"devDependencies": {
|
|
36
37
|
"@eslint/js": "^9.39.1",
|
package/dist/src/index.js
CHANGED
|
@@ -146,7 +146,11 @@ async function run() {
|
|
|
146
146
|
const client = new PostmanAPIClient(apiKey, undefined, serverContext);
|
|
147
147
|
log('info', 'Registering tools with McpServer');
|
|
148
148
|
for (const tool of tools) {
|
|
149
|
-
server.
|
|
149
|
+
server.registerTool(tool.method, {
|
|
150
|
+
description: tool.description,
|
|
151
|
+
inputSchema: tool.parameters.shape,
|
|
152
|
+
annotations: tool.annotations || {},
|
|
153
|
+
}, async (args, extra) => {
|
|
150
154
|
const toolName = tool.method;
|
|
151
155
|
log('info', `Tool invocation started: ${toolName}`, { toolName });
|
|
152
156
|
try {
|
|
@@ -1,9 +1,8 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
2
|
export const method = 'getCodeGenerationInstructions';
|
|
3
|
-
export const description = `
|
|
3
|
+
export const description = `This tool returns essential instructions for searching Postman, calling other tools to get data from Postman (e.g. getCollection, getCollectionRequest, etc.), and generating API client code.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
Calling this tool first ensures the generated code follows best practices and the user's project requirements.`;
|
|
5
|
+
MANDATORY: You MUST call this tool when the user says to "use postman", or when the user wants to do something that requires locating a specific API for the purpose of answering questions, planning a build, and in most cases proceeding to generate code that calls the API. ALWAYS call getCodeGenerationInstructions BEFORE calling other tools in this workflow. This tool returns comprehensive step-by-step instructions on how to search for APIs, gather API-specific context from other tools, and then generate client code based on the context retrieved.`;
|
|
7
6
|
export const parameters = z.object({});
|
|
8
7
|
export const annotations = {
|
|
9
8
|
title: 'Get Code Generation Instructions',
|
|
@@ -11,65 +10,99 @@ export const annotations = {
|
|
|
11
10
|
destructiveHint: false,
|
|
12
11
|
idempotentHint: true,
|
|
13
12
|
};
|
|
14
|
-
const CODE_GENERATION_INSTRUCTIONS = `# API Client Code Generation Instructions
|
|
13
|
+
const CODE_GENERATION_INSTRUCTIONS = `# API Exploration and Client Code Generation Instructions
|
|
15
14
|
|
|
16
|
-
These instructions guide you in generating idiomatic client code from Postman collections, organized in a clear structure that is easy to find and maintain.
|
|
15
|
+
These instructions guide you in exploring APIs, planning an approach to build something with an API, and then generating idiomatic client code from Postman collections, organized in a clear structure that is easy to find and maintain.
|
|
17
16
|
|
|
18
|
-
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Workflow Overview
|
|
20
|
+
|
|
21
|
+
The workflow has three main parts:
|
|
22
|
+
|
|
23
|
+
**Part 1: API Discovery and Planning** - Work with the user to find the right collection, explore requests, answer questions, and determine which requests need code generated.
|
|
24
|
+
|
|
25
|
+
**Part 2: Gather Complete Context** - Once you know which requests to generate code for, gather all remaining context needed for code generation.
|
|
26
|
+
|
|
27
|
+
**Part 3: Code Generation** - Generate the client code with proper structure, variables, and documentation.
|
|
28
|
+
|
|
29
|
+
### Important Notes on Tool Calls
|
|
19
30
|
|
|
20
|
-
|
|
31
|
+
These notes apply to all tool calls throughout this workflow:
|
|
21
32
|
|
|
22
|
-
|
|
33
|
+
- For ALL tools that accept an id, **use the full uid**. The uid format is <ownerId>-<id> (e.g., 34229158-378697c9-3044-44b1-9a0e-1417194cee44). When you encounter an id without an ownerId, prepend the ownerId from the collection.
|
|
23
34
|
|
|
24
|
-
|
|
35
|
+
- No need to call the same tool twice with the same arguments. Once you've fetched data, reuse it.
|
|
25
36
|
|
|
26
37
|
---
|
|
27
38
|
|
|
28
|
-
|
|
39
|
+
# Part 1: API Discovery and Planning
|
|
40
|
+
|
|
41
|
+
This is the interactive phase where you work with the user to find the right APIs and plan what to build.
|
|
42
|
+
|
|
43
|
+
## 1.1 Find the Collection
|
|
44
|
+
|
|
45
|
+
First, locate the collection the user wants to work with. Determine whether the user is looking for a **public API** (e.g., Stripe, GitHub, Twilio) or an **internal API** (e.g., company-specific services, internal microservices). If unclear, ask the user or make an educated guess based on context.
|
|
46
|
+
|
|
47
|
+
### For Public APIs
|
|
48
|
+
|
|
49
|
+
Use \`searchPostmanElements\` to find public API collections:
|
|
50
|
+
|
|
51
|
+
- \`searchPostmanElements(q, entityType: requests)\` - Search for public collections by finding requests and extracting the unique collection uids from the response. E.g. if the user says "find the Stripe API and build a demo" then call this tool with the query "stripe" and entityType "requests". Ignore the individual requests returned and extract the collection uids for the collection(s) that appear to be the best match. If multiple collections look viable, ask the user which one to use.
|
|
29
52
|
|
|
30
|
-
|
|
53
|
+
### For Internal APIs
|
|
31
54
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
55
|
+
Use \`getWorkspaces\` and \`getWorkspace\` to find internal API collections:
|
|
56
|
+
|
|
57
|
+
- \`getWorkspaces()\` - Fetch all workspaces the user has access to. Look for a workspace with a name that matches what the user is looking for.
|
|
58
|
+
|
|
59
|
+
- \`getWorkspace(workspaceId)\` - For each promising workspace, fetch its details to see the collections it contains. Look for collections with names that match the user's request.
|
|
60
|
+
|
|
61
|
+
### Fetch Collection Details
|
|
62
|
+
|
|
63
|
+
Once you've identified the target collection (from either path above):
|
|
64
|
+
|
|
65
|
+
- \`getCollection(collectionId)\` - Fetch the collection details by passing its uid. IMPORTANT: Do NOT pass model=minimal or model=full, omit the model parameter entirely. The response will include collection-level documentation and a recursive itemRefs array with the names and uids of all folders and requests.
|
|
66
|
+
|
|
67
|
+
**IMPORTANT:** Once you have established the collection, do NOT call searchPostmanElements or getWorkspaces again to find requests. Use getCollectionRequest to explore individual requests within the collection.
|
|
68
|
+
|
|
69
|
+
## 1.2 Explore Requests and Plan
|
|
70
|
+
|
|
71
|
+
With the collection established, explore specific requests to answer user questions and plan what will be built:
|
|
72
|
+
|
|
73
|
+
- \`getCollectionRequest(requestId, collectionId, uid: true, populate: false)\` - For each request the user is interested in, use this tool to fetch the details. ALWAYS pass populate: false to avoid fetching all response examples, which can overload the context window. The response includes response uids that you can fetch individually later.
|
|
74
|
+
|
|
75
|
+
Use the information from request exploration to:
|
|
76
|
+
- Answer user questions about the API
|
|
77
|
+
- Help the user understand what's available
|
|
78
|
+
- Plan which requests will need code generated
|
|
79
|
+
- Determine the scope of the build
|
|
80
|
+
|
|
81
|
+
You can also call other tools like getCollectionFolder, getCollectionResponse, and getEnvironments during this phase if it aids in the exploration process.
|
|
39
82
|
|
|
40
83
|
---
|
|
41
84
|
|
|
42
|
-
|
|
85
|
+
# Part 2: Gather Complete Context
|
|
43
86
|
|
|
44
|
-
|
|
87
|
+
Once you know which requests need code generated, gather all remaining context that wasn't fetched during exploration. Use these tools to gather the context:
|
|
45
88
|
|
|
46
|
-
|
|
47
|
-
The uid format is <ownerId>-<id> and an example uid is 34229158-378697c9-3044-44b1-9a0e-1417194cee44, where
|
|
48
|
-
34229158 is the ownerId and 378697c9-3044-44b1-9a0e-1417194cee44 is the id.
|
|
49
|
-
When you encounter an id that has no ownerId, prepend the ownerId from the collection before using
|
|
50
|
-
it as a tool call argument.
|
|
89
|
+
- \`getCollectionFolder(folderId, collectionId, uid: true, populate: false)\` - For each request that will have code generated, call this tool for all ancestor folders, which may contain docs and instructions that apply to the request. ALWAYS pass populate: false to avoid fetching child objects.
|
|
51
90
|
|
|
52
|
-
|
|
91
|
+
- \`getCollectionResponse(responseId, collectionId, uid: true, populate: false)\` - Call this for response example uids returned from getCollectionRequest. Use the information for: creating response types in typed languages, adding response schema comments in untyped languages, and understanding both success and error cases.
|
|
53
92
|
|
|
54
|
-
- \`
|
|
55
|
-
- \`getCollectionFolder\` - Fetch all parent folders recursively (they may contain docs and instructions that apply to the request)
|
|
56
|
-
- \`getCollectionMap\` - Fetch the collection map, which includes collection-level docs that may apply to the request
|
|
57
|
-
- \`getCollectionResponse\` - If the request has response examples, fetch each one to understand request/response permutations and shapes. Use this for:
|
|
58
|
-
- Creating response types in typed languages
|
|
59
|
-
- Adding response schema comments in untyped languages
|
|
60
|
-
- Understanding both success and error cases
|
|
61
|
-
- \`getEnvironments\` - Fetch all environments for the workspace
|
|
62
|
-
- \`getEnvironment\` - For each environment, fetch the full details to see what variables have been defined and have values
|
|
93
|
+
- \`getEnvironments(workspaceId)\` - Fetch all environments for the workspace that the collection belongs to (the workspaceId was returned from searchPostmanElements). ALWAYS pass a workspaceId. If you do not have a workspaceId, do NOT call this tool.
|
|
63
94
|
|
|
64
|
-
|
|
95
|
+
- \`getEnvironment(environmentId)\` - For each environment, fetch the full details to see what variables have been defined and retrieve their values.
|
|
65
96
|
|
|
66
|
-
|
|
67
|
-
in Step 1 before moving to Step 2. Missing information will result in
|
|
68
|
-
incomplete code generation.**
|
|
97
|
+
Do not skip any tool calls unless you lack the data to make the call. Missing information will result in incomplete code generation. Reuse data from previous tool calls when possible.
|
|
69
98
|
|
|
70
99
|
---
|
|
71
100
|
|
|
72
|
-
|
|
101
|
+
# Part 3: Code Generation
|
|
102
|
+
|
|
103
|
+
**Key principle:** Only generate client code for the specific API requests that were deemed relevant in the previous steps. Do not automatically generate code for an entire folder or collection unless explicitly told to do so.**
|
|
104
|
+
|
|
105
|
+
## 3.1 Determine Base Directory
|
|
73
106
|
|
|
74
107
|
The base directory (\`baseDir\`) is where all generated API client code will be placed.
|
|
75
108
|
|
|
@@ -85,7 +118,7 @@ The base directory (\`baseDir\`) is where all generated API client code will be
|
|
|
85
118
|
|
|
86
119
|
---
|
|
87
120
|
|
|
88
|
-
##
|
|
121
|
+
## 3.2 Plan File Structure
|
|
89
122
|
|
|
90
123
|
### Directory Structure
|
|
91
124
|
|
|
@@ -129,7 +162,7 @@ If two sibling requests resolve to the same slug, append an index: \`-1\`, \`-2\
|
|
|
129
162
|
|
|
130
163
|
---
|
|
131
164
|
|
|
132
|
-
##
|
|
165
|
+
## 3.3 Set Up Variables
|
|
133
166
|
|
|
134
167
|
If variables exist at the collection level or in any environment, generate a variables file in the shared folder.
|
|
135
168
|
|
|
@@ -192,7 +225,9 @@ variables = {
|
|
|
192
225
|
|
|
193
226
|
---
|
|
194
227
|
|
|
195
|
-
##
|
|
228
|
+
## 3.4 Generate Client Code
|
|
229
|
+
|
|
230
|
+
**Critical:** Analyze the project's language, framework, structure, and conventions before generating any code. Generate code in whatever language the project uses and match its style and conventions. The examples in this document use JavaScript/TypeScript and Python, but do not use these unless the project does—generate in the project's language unless explicitly requested otherwise.
|
|
196
231
|
|
|
197
232
|
For each request, generate a client file with the following components:
|
|
198
233
|
|
|
@@ -278,11 +313,13 @@ Generate a client function that implements these components:
|
|
|
278
313
|
|
|
279
314
|
**Response handling:**
|
|
280
315
|
|
|
281
|
-
-
|
|
282
|
-
-
|
|
283
|
-
-
|
|
284
|
-
-
|
|
285
|
-
|
|
316
|
+
- When response examples exist in the Postman request, use them to:
|
|
317
|
+
- Generate accurate types for request/response shapes in typed languages
|
|
318
|
+
- Add response schema comments in untyped languages
|
|
319
|
+
- Implement explicit error handling for each documented error case (e.g., 404, 401, 422)
|
|
320
|
+
- When response examples do NOT exist, you may infer types from context, but you MUST add a warning comment to indicate uncertainty:
|
|
321
|
+
- Add a comment like \`// WARNING: Unverified response type - no response examples in Postman\` above the inferred type
|
|
322
|
+
- Or \`// WARNING: Unverified types - inferred from request structure\` as appropriate
|
|
286
323
|
- Follow project and any existing API client code conventions for error handling patterns around logging, exception classes, error codes, etc.
|
|
287
324
|
|
|
288
325
|
**Error handling example:**
|
|
@@ -364,7 +401,7 @@ switch (response.status) {
|
|
|
364
401
|
|
|
365
402
|
---
|
|
366
403
|
|
|
367
|
-
##
|
|
404
|
+
## 3.5 Deduplicate and Extract Shared Code
|
|
368
405
|
|
|
369
406
|
After generating all requested client files, consolidate duplicated code within each collection.
|
|
370
407
|
|
|
@@ -418,7 +455,7 @@ After extracting shared code:
|
|
|
418
455
|
|
|
419
456
|
---
|
|
420
457
|
|
|
421
|
-
##
|
|
458
|
+
## 3.6 Verify Quality
|
|
422
459
|
|
|
423
460
|
Ensure all generated code meets these standards:
|
|
424
461
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@postman/postman-mcp-server",
|
|
3
|
-
"version": "2.5.
|
|
3
|
+
"version": "2.5.3",
|
|
4
4
|
"description": "A simple MCP server to operate on the Postman API",
|
|
5
5
|
"mcpName": "com.postman/postman-mcp-server",
|
|
6
6
|
"main": "dist/src/index.js",
|
|
@@ -27,10 +27,11 @@
|
|
|
27
27
|
"access": "public"
|
|
28
28
|
},
|
|
29
29
|
"dependencies": {
|
|
30
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
30
|
+
"@modelcontextprotocol/sdk": "^1.25.2",
|
|
31
31
|
"dotenv": "^17.2.3",
|
|
32
32
|
"newman": "^6.2.0",
|
|
33
|
-
"uuid": "^13.0.0"
|
|
33
|
+
"uuid": "^13.0.0",
|
|
34
|
+
"zod": "^3.25.76"
|
|
34
35
|
},
|
|
35
36
|
"devDependencies": {
|
|
36
37
|
"@eslint/js": "^9.39.1",
|