@postman/postman-mcp-server 2.3.6 → 2.4.0
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/README.md +188 -74
- package/dist/package.json +4 -2
- package/dist/src/enabledResources.js +2 -0
- package/dist/src/index.js +10 -1
- package/dist/src/tools/getCollections.js +2 -0
- package/dist/src/tools/runCollection.js +133 -0
- package/dist/src/tools/updateMock.js +3 -0
- package/dist/src/tools/utils/runner.js +84 -0
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -1,101 +1,92 @@
|
|
|
1
1
|
# Postman MCP Server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The Postman MCP Server connects Postman to AI tools, giving AI agents and assistants the ability to access workspaces, manage collections and environments, evaluate APIs, and automate workflows through natural language interactions.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
- [**Streamable HTTP**](#streamable-http)
|
|
5
|
+
Postman supports the following tool configurations:
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
* **Minimal** — (Default) Only includes essential tools for basic Postman operations This offers faster performance and simplifies use for those who only need basic Postman operations. Ideal for users who want to modify a single Postman elements, such as collections, workspaces, or environments.
|
|
8
|
+
* **Full** — Includes all available Postman API tools (100+ tools). This configuration is ideal for users who engage in advanced collaboration and Postman's Enterprise features.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
For a complete list of the Postman MCP Server's tools, see the [Postman MCP Server collection](https://www.postman.com/postman/postman-public-workspace/collection/681dc649440b35935978b8b7). This collection offers both the remote [full](https://www.postman.com/postman/postman-public-workspace/mcp-request/6821a76b17ccb90a86df48d3) and [minimal](https://www.postman.com/postman/postman-public-workspace/mcp-request/689e1c635be722a98b723238) servers, and the [local server](https://www.postman.com/postman/postman-public-workspace/mcp-request/6866a655b36c67cc435b5033).
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Postman also offers servers as an [npm package](https://www.npmjs.com/package/@postman/postman-mcp-server).
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
**Note:** Before getting started, ensure that you have a valid [Postman API key](https://postman.postman.co/settings/me/api-keys).
|
|
15
15
|
|
|
16
|
-
###
|
|
16
|
+
### Use Cases
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
18
|
+
* **Code synchronization** - Effortlessly keep your code in sync with your [Postman Collections](https://learning.postman.com/docs/design-apis/collections/overview/) and specs.
|
|
19
|
+
* **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.
|
|
20
|
+
* **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.
|
|
21
|
+
* **Automatic spec creation** - Create [specs](https://learning.postman.com/docs/design-apis/specifications/overview/) from your code and use them to generate collections.
|
|
21
22
|
|
|
22
|
-
|
|
23
|
+
Designed for developers who want to integrate their AI tools with Postman’s context and features. Supports quick natural language queries queries to advanced agent workflows.
|
|
23
24
|
|
|
24
|
-
|
|
25
|
+
### Support for EU
|
|
25
26
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
"postman-api-mcp": {
|
|
30
|
-
"type": "stdio",
|
|
31
|
-
"command": "npx",
|
|
32
|
-
"args": [
|
|
33
|
-
"@postman/postman-mcp-server",
|
|
34
|
-
"--full" // (optional) Use this flag to enable full mode
|
|
35
|
-
],
|
|
36
|
-
"env": {
|
|
37
|
-
"POSTMAN_API_KEY": "${input:postman-api-key}"
|
|
38
|
-
}
|
|
39
|
-
}
|
|
40
|
-
},
|
|
41
|
-
"inputs": [
|
|
42
|
-
{
|
|
43
|
-
"id": "postman-api-key",
|
|
44
|
-
"type": "promptString",
|
|
45
|
-
"description": "Enter your Postman API key"
|
|
46
|
-
}
|
|
47
|
-
]
|
|
48
|
-
}
|
|
49
|
-
```
|
|
27
|
+
The Postman MCP Server supports the EU region for remote and local servers:
|
|
28
|
+
* For streamable HTTP, the remote server is available at `https://mcp.eu.postman.com`.
|
|
29
|
+
* For our STDIO public package, use the `--region` flag to specify the Postman API region (`us` or `eu`), or set the `POSTMAN_API_BASE_URL` environment variable directly.
|
|
50
30
|
|
|
51
|
-
|
|
31
|
+
---
|
|
52
32
|
|
|
53
|
-
|
|
33
|
+
### Contents
|
|
54
34
|
|
|
55
|
-
|
|
35
|
+
* [**Remote server**](#remote-server)
|
|
36
|
+
* [**VS Code**](#install-in-visual-studio-code)
|
|
37
|
+
* [**Cursor**](#install-in-cursor)
|
|
38
|
+
* [**Claude Code**](#install-in-claude-code)
|
|
39
|
+
* [**Local server**](#local-server)
|
|
40
|
+
* [**VS Code**](#install-in-visual-studio-code-1)
|
|
41
|
+
* [**Cursor**](#install-in-cursor-1)
|
|
42
|
+
* [**Claude**](#claude-integration)
|
|
43
|
+
* [**Claude Code**](#install-in-claude-code-1)
|
|
44
|
+
* [**Gemini CLI**](#use-as-a-gemini-cli-extension)
|
|
45
|
+
* [**Docker**](#install-in-docker)
|
|
46
|
+
* [**Questions and support**](#questions-and-support)
|
|
47
|
+
* [**Migration from Postman MCP Server v1 to v2**](#migration-from-v1x-to-v2x)
|
|
56
48
|
|
|
57
|
-
|
|
58
|
-
1. In the repository's root folder, run the `npm install` command. This installs all the required dependencies.
|
|
59
|
-
1. Replace `${workspaceFolder}` in the *mcp.json* file with the full path to the Postman MCP repository.
|
|
60
|
-
1. When prompted, enter your [Postman API key](https://go.postman.co/settings/me/api-keys).
|
|
49
|
+
---
|
|
61
50
|
|
|
62
|
-
|
|
51
|
+
## Remote server
|
|
63
52
|
|
|
64
|
-
|
|
53
|
+
The remote Postman MCP Server is hosted by Postman over streamable HTTP and provides the easiest method for getting started. If your MCP host doesn't support remote MCP servers, you can use the [local Postman MCP Server](#local-server).
|
|
65
54
|
|
|
66
|
-
|
|
67
|
-
- **postman-api-mcp-full.dxt** - Contains all 106+ tools for comprehensive Postman functionality.
|
|
55
|
+
The remote server supports the following tool configurations:
|
|
68
56
|
|
|
69
|
-
|
|
57
|
+
* **Minimal** — (Default) Only includes essential tools for basic Postman operations, available at `https://mcp.postman.com/minimal` and `https://mcp.eu.postman.com/minimal` for EU users.
|
|
58
|
+
* **Full** — Includes all available Postman API tools (100+ tools), available at `https://mcp.postman.com/mcp` and `https://mcp.eu.postman.com/mcp` for EU users.
|
|
70
59
|
|
|
71
|
-
|
|
60
|
+
### Install in Cursor
|
|
72
61
|
|
|
73
|
-
|
|
62
|
+
[](https://cursor.com/en/install-mcp?name=postman_mcp_server&config=eyJ1cmwiOiJodHRwczovL21jcC5wb3N0bWFuLmNvbS9taW5pbWFsIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIFlPVVJfQVBJX0tFWSJ9fQ%3D%3D)
|
|
74
63
|
|
|
75
|
-
|
|
76
|
-
- **Full** — Includes all available Postman API tools (100+ tools), available at `https://mcp.postman.com/mcp`.
|
|
64
|
+
To install the remote Postman MCP Server in Cursor, click the install button.
|
|
77
65
|
|
|
78
|
-
|
|
66
|
+
**Note:** Ensure that the Authorization header uses the `Bearer <YOUR_API_KEY>` format.
|
|
79
67
|
|
|
80
|
-
|
|
68
|
+
By default, the server uses **Minimal** mode. To access **Full** mode, change the `url` value to `https://mcp.postman.com/mcp` in the `mcp.json` file.
|
|
81
69
|
|
|
82
|
-
|
|
83
|
-
> Ensure the Authorization header uses the Bearer <YOUR_API_KEY> format.
|
|
70
|
+
### Install in Visual Studio Code
|
|
84
71
|
|
|
85
|
-
[](https://insiders.vscode.dev/redirect/mcp/install?name=postman_mcp_server&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fmcp.postman.com%2Fminimal%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20YOUR_API_KEY%22%7D%7D)
|
|
86
73
|
|
|
87
|
-
|
|
74
|
+
To install the remote Postman MCP Server in VS Code, click the install button or use the [Postman VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Postman.postman-for-vscode).
|
|
88
75
|
|
|
89
|
-
|
|
76
|
+
By default, the server uses **Minimal** mode. To access **Full** mode, change the `url` value to `https://mcp.postman.com/mcp` in the `mcp.json` file.
|
|
90
77
|
|
|
91
|
-
|
|
78
|
+
#### Manual configuration
|
|
79
|
+
|
|
80
|
+
You can use the Postman MCP Server with MCP-compatible extensions in VS Code, such as GitHub Copilot, Claude for VS Code, or other AI assistants that support MCP. To do so, add the following JSON block to the `.vscode/mcp.json` configuration file:
|
|
92
81
|
|
|
93
82
|
```json
|
|
94
83
|
{
|
|
95
84
|
"servers": {
|
|
96
85
|
"postman-api-http-server": {
|
|
97
86
|
"type": "http",
|
|
98
|
-
"url": "https://mcp.postman.com/{minimal
|
|
87
|
+
"url": "https://mcp.postman.com/{minimal OR mcp}",
|
|
88
|
+
// Use "https://mcp.postman.com/mcp" for full or "https://mcp.postman.com/minimal" for minimal mode.
|
|
89
|
+
// For the EU server, use the "https://mcp.eu.postman.com" URL.
|
|
99
90
|
"headers": {
|
|
100
91
|
"Authorization": "Bearer ${input:postman-api-key}"
|
|
101
92
|
}
|
|
@@ -111,21 +102,144 @@ To install in VS Code, you can use the [Postman VS Code Extension](https://marke
|
|
|
111
102
|
}
|
|
112
103
|
```
|
|
113
104
|
|
|
114
|
-
When prompted, enter your Postman API key.
|
|
105
|
+
When prompted, enter your Postman API key.
|
|
106
|
+
|
|
107
|
+
### Install in Claude Code
|
|
108
|
+
|
|
109
|
+
To install the MCP server in Claude Code, run the following command in your terminal:
|
|
110
|
+
|
|
111
|
+
For **Minimal** mode:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
claude mcp add --transport http postman https://mcp.postman.com/minimal
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
For **Full** mode:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
claude mcp add --transport http postman https://mcp.postman.com/mcp
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Local server
|
|
126
|
+
|
|
127
|
+
If remote MCP servers aren't supported by your MCP host, you can install the Postman MCP Server to your local machine.
|
|
128
|
+
|
|
129
|
+
STDIO is a lightweight solution that's ideal for integration with editors and tools like Visual Studio Code. Install an MCP-compatible VS Code extension, such as GitHub Copilot, Claude for VS Code, or other AI assistants that support MCP.
|
|
130
|
+
|
|
131
|
+
**Note:** To run the server as a Node application, install [Node.js](https://nodejs.org/en).
|
|
132
|
+
|
|
133
|
+
The local server supports the following tool configurations:
|
|
134
|
+
|
|
135
|
+
* **Minimal** — (Default) Only includes essential tools for basic Postman operations.
|
|
136
|
+
* **Full** — Includes all available Postman API tools (100+ tools). Use the `--full` flag to enable this configuration.
|
|
137
|
+
|
|
138
|
+
**Note:** Use the `--region` flag to specify the Postman API region (`us` or `eu`), or set the `POSTMAN_API_BASE_URL` environment variable directly. By default, the server uses the `us` option.
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
### Install in Visual Studio Code
|
|
142
|
+
|
|
143
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=postman-api-mcp&inputs=%5B%7B%22id%22%3A%22postman-api-key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Enter%20your%20Postman%20API%20key%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40postman%2Fpostman-mcp-server%22%2C%22--full%22%5D%2C%22env%22%3A%7B%22POSTMAN_API_KEY%22%3A%22%24%7Binput%3Apostman-api-key%7D%22%7D%7D)
|
|
144
|
+
|
|
145
|
+
To install the local Postman MCP Server in VS Code, click the install button.
|
|
146
|
+
|
|
147
|
+
By default, the server uses **Full** mode. To access **Minimal** mode, remove the `--full` flag from the `mcp.json` configuration file.
|
|
148
|
+
|
|
149
|
+
#### Manual configuration
|
|
150
|
+
|
|
151
|
+
You can manually integrate your MCP server with Cursor or VS Code to use it with extensions that support MCP. To do this, create a `mcp.json` file in your project and add the following JSON block to it:
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
{
|
|
155
|
+
"servers": {
|
|
156
|
+
"postman-api-mcp": {
|
|
157
|
+
"type": "stdio",
|
|
158
|
+
"command": "npx",
|
|
159
|
+
"args": [
|
|
160
|
+
"@postman/postman-mcp-server",
|
|
161
|
+
"--full" // (optional) Use this flag to enable full mode.
|
|
162
|
+
"--region us" // (optional) Use this flag to specify the Postman API region (us or eu). Defaults to us.
|
|
163
|
+
],
|
|
164
|
+
"env": {
|
|
165
|
+
"POSTMAN_API_KEY": "${input:postman-api-key}"
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
},
|
|
169
|
+
"inputs": [
|
|
170
|
+
{
|
|
171
|
+
"id": "postman-api-key",
|
|
172
|
+
"type": "promptString",
|
|
173
|
+
"description": "Enter your Postman API key"
|
|
174
|
+
}
|
|
175
|
+
]
|
|
176
|
+
}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### Install in Cursor
|
|
180
|
+
|
|
181
|
+
[](https://cursor.com/en/install-mcp?name=postman-api-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAcG9zdG1hbi9wb3N0bWFuLW1jcC1zZXJ2ZXIiLCItLWZ1bGwiXSwiZW52Ijp7IlBPU1RNQU5fQVBJX0tFWSI6IllPVVJfQVBJX0tFWSJ9fQ%3D%3D)
|
|
182
|
+
|
|
183
|
+
To install the local Postman MCP Server in Cursor, click the install button.
|
|
184
|
+
|
|
185
|
+
By default, the server uses **Full** mode. To access **Minimal** mode, remove the `--full` flag from the `mcp.json` configuration file.
|
|
186
|
+
|
|
187
|
+
### Claude integration
|
|
188
|
+
|
|
189
|
+
To integrate the MCP server with Claude, check the latest [Postman MCP Server release](https://github.com/postmanlabs/postman-mcp-server/releases) and get the `.mcpb` file.
|
|
190
|
+
|
|
191
|
+
* **Minimal** - `postman-api-mcp-minimal.mcpb`
|
|
192
|
+
* **Full** - `postman-api-mcp-full.mcpb`
|
|
193
|
+
|
|
194
|
+
For more information, see the [Claude Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions) documentation.
|
|
195
|
+
|
|
196
|
+
### Install in Claude Code
|
|
197
|
+
|
|
198
|
+
To install the MCP server in Claude Code, run the following command in your terminal:
|
|
199
|
+
|
|
200
|
+
For **Minimal** mode:
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
claude mcp add postman -- npx @postman/mcp-server@latest
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
For **Full** mode:
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
claude mcp add postman -- npx @postman/mcp-server@latest --full
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
### Use as a Gemini CLI extension
|
|
213
|
+
|
|
214
|
+
To install the MCP server as a Gemini CLI extension, run the following command in your terminal:
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
gemini extensions install https://github.com/postmanlabs/postman-mcp-server
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
### Install in Docker
|
|
221
|
+
|
|
222
|
+
For Docker set up and installation, see [DOCKER.md](./DOCKER.md).
|
|
223
|
+
|
|
224
|
+
---
|
|
115
225
|
|
|
116
226
|
## Migration from v1.x to v2.x
|
|
117
227
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
-
|
|
123
|
-
-
|
|
124
|
-
|
|
228
|
+
If you're migrating from Postman MCP Server version 1.x to 2.x, be aware of the following:
|
|
229
|
+
|
|
230
|
+
* **Tool naming changes** - All tool names changed from kebab-case to camelCase. For example:
|
|
231
|
+
* `create-collection` → `createCollection`
|
|
232
|
+
* `get-workspaces` → `getWorkspaces`
|
|
233
|
+
* `delete-environment` → `deleteEnvironment`
|
|
234
|
+
* **Tool availability changes**
|
|
235
|
+
* The default (minimal) behavior provides only 37 essential tools.
|
|
236
|
+
* The `--full` flag provides access to all tools.
|
|
237
|
+
|
|
238
|
+
---
|
|
125
239
|
|
|
126
240
|
## Questions and support
|
|
127
241
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
242
|
+
* See the [Postman Agent Generator](https://postman.com/explore/agent-generator) page for updates and new capabilities.
|
|
243
|
+
* See [Add your MCP requests to your collections](https://learning.postman.com/docs/postman-ai-agent-builder/mcp-requests/overview/) to learn how to use Postman to perform MCP requests.
|
|
244
|
+
* Visit the [Postman Community](https://community.postman.com/) to share what you've built, ask questions, and get help.
|
|
245
|
+
* You can connect to both the remote and local servers and test them using the [Postman MCP Server collection](https://www.postman.com/postman/postman-public-workspace/collection/681dc649440b35935978b8b7).
|
package/dist/package.json
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@postman/postman-mcp-server",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.4.0",
|
|
4
4
|
"description": "A simple MCP server to operate on the Postman API",
|
|
5
|
+
"mcpName": "com.postman/@postman/postman-mcp-server",
|
|
5
6
|
"main": "dist/src/index.js",
|
|
6
7
|
"type": "module",
|
|
7
8
|
"scripts": {
|
|
@@ -30,7 +31,8 @@
|
|
|
30
31
|
"@modelcontextprotocol/sdk": "^1.18.1",
|
|
31
32
|
"dotenv": "^17.2.2",
|
|
32
33
|
"es-toolkit": "^1.39.10",
|
|
33
|
-
"express": "^5.1.0"
|
|
34
|
+
"express": "^5.1.0",
|
|
35
|
+
"newman": "^6.2.1"
|
|
34
36
|
},
|
|
35
37
|
"devDependencies": {
|
|
36
38
|
"@eslint/js": "^9.35.0",
|
|
@@ -109,6 +109,7 @@ const full = [
|
|
|
109
109
|
'getDuplicateCollectionTaskStatus',
|
|
110
110
|
'deleteApiCollectionComment',
|
|
111
111
|
'deleteSpecFile',
|
|
112
|
+
'runCollection',
|
|
112
113
|
];
|
|
113
114
|
const minimal = [
|
|
114
115
|
'createCollection',
|
|
@@ -149,6 +150,7 @@ const minimal = [
|
|
|
149
150
|
'createCollectionResponse',
|
|
150
151
|
'duplicateCollection',
|
|
151
152
|
'getStatusOfAnAsyncApiTask',
|
|
153
|
+
'runCollection',
|
|
152
154
|
];
|
|
153
155
|
const excludedFromGeneration = ['createCollection', 'putCollection'];
|
|
154
156
|
export const enabledResources = {
|
package/dist/src/index.js
CHANGED
|
@@ -83,7 +83,16 @@ async function loadAllTools() {
|
|
|
83
83
|
return [];
|
|
84
84
|
}
|
|
85
85
|
}
|
|
86
|
-
dotenv.config();
|
|
86
|
+
const dotEnvOutput = dotenv.config({ quiet: true });
|
|
87
|
+
if (dotEnvOutput.error) {
|
|
88
|
+
if (dotEnvOutput.error.code !== 'ENOENT') {
|
|
89
|
+
log('error', `Error loading .env file: ${dotEnvOutput.error}`);
|
|
90
|
+
process.exit(1);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
else {
|
|
94
|
+
log('info', `Environment variables loaded: ${dotEnvOutput.parsed ? Object.keys(dotEnvOutput.parsed).length : 0} environment variables: ${Object.keys(dotEnvOutput.parsed || {}).join(', ')}`);
|
|
95
|
+
}
|
|
87
96
|
const SERVER_NAME = packageJson.name;
|
|
88
97
|
const APP_VERSION = packageJson.version;
|
|
89
98
|
export const USER_AGENT = `${SERVER_NAME}/${APP_VERSION}`;
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { McpError, ErrorCode, } from '@modelcontextprotocol/sdk/types.js';
|
|
3
|
+
import newman from 'newman';
|
|
4
|
+
import { TestTracker, OutputBuilder, buildNewmanOptions } from './utils/runner.js';
|
|
5
|
+
function asMcpError(error) {
|
|
6
|
+
const cause = error?.cause ?? String(error);
|
|
7
|
+
return new McpError(ErrorCode.InternalError, cause);
|
|
8
|
+
}
|
|
9
|
+
export const method = 'runCollection';
|
|
10
|
+
export const description = 'Runs a Postman collection by ID with detailed test results and execution statistics. Supports optional environment for variable substitution. Note: Advanced parameters like custom delays and other runtime options are not yet available.';
|
|
11
|
+
export const parameters = z.object({
|
|
12
|
+
collectionId: z
|
|
13
|
+
.string()
|
|
14
|
+
.describe('The collection ID in the format <OWNER_ID>-<UUID> (e.g. 12345-33823532ab9e41c9b6fd12d0fd459b8b).'),
|
|
15
|
+
environmentId: z
|
|
16
|
+
.string()
|
|
17
|
+
.optional()
|
|
18
|
+
.describe('Optional environment ID to use for variable substitution during the run.'),
|
|
19
|
+
stopOnError: z.boolean().optional().describe('Gracefully halt on errors (default: false)'),
|
|
20
|
+
stopOnFailure: z
|
|
21
|
+
.boolean()
|
|
22
|
+
.optional()
|
|
23
|
+
.describe('Gracefully halt on test failures (default: false)'),
|
|
24
|
+
abortOnError: z.boolean().optional().describe('Abruptly halt on errors (default: false)'),
|
|
25
|
+
abortOnFailure: z
|
|
26
|
+
.boolean()
|
|
27
|
+
.optional()
|
|
28
|
+
.describe('Abruptly halt on test failures (default: false)'),
|
|
29
|
+
iterationCount: z.number().optional().describe('Number of iterations to run (default: 1)'),
|
|
30
|
+
requestTimeout: z
|
|
31
|
+
.number()
|
|
32
|
+
.optional()
|
|
33
|
+
.describe('Request timeout in milliseconds (default: 60000)'),
|
|
34
|
+
scriptTimeout: z.number().optional().describe('Script timeout in milliseconds (default: 5000)'),
|
|
35
|
+
});
|
|
36
|
+
export const annotations = {
|
|
37
|
+
title: 'Run Postman Collection',
|
|
38
|
+
readOnlyHint: false,
|
|
39
|
+
destructiveHint: false,
|
|
40
|
+
idempotentHint: true,
|
|
41
|
+
};
|
|
42
|
+
export async function handler(params, extra) {
|
|
43
|
+
try {
|
|
44
|
+
const tracker = new TestTracker();
|
|
45
|
+
const output = new OutputBuilder();
|
|
46
|
+
output.add(`🚀 Fetching collection with ID: ${params.collectionId}`);
|
|
47
|
+
const response = await extra.client.get(`/collections/${params.collectionId}`);
|
|
48
|
+
const collectionJSON = response.collection || response;
|
|
49
|
+
output.add(`✅ Successfully fetched collection: ${collectionJSON.info?.name || 'Unknown'}\n`);
|
|
50
|
+
let environmentJSON;
|
|
51
|
+
if (params.environmentId) {
|
|
52
|
+
output.add(`🌍 Fetching environment with ID: ${params.environmentId}`);
|
|
53
|
+
const envResponse = await extra.client.get(`/environments/${params.environmentId}`);
|
|
54
|
+
environmentJSON = envResponse.environment || envResponse;
|
|
55
|
+
output.add(`✅ Successfully fetched environment: ${environmentJSON.name || 'Unknown'}\n`);
|
|
56
|
+
}
|
|
57
|
+
const newmanOptions = buildNewmanOptions(params, collectionJSON, environmentJSON);
|
|
58
|
+
const startTime = Date.now();
|
|
59
|
+
await new Promise((resolve, reject) => {
|
|
60
|
+
newman
|
|
61
|
+
.run(newmanOptions)
|
|
62
|
+
.on('start', () => {
|
|
63
|
+
output.add('🎯 Starting collection run...\n');
|
|
64
|
+
})
|
|
65
|
+
.on('assertion', (_err, args) => {
|
|
66
|
+
if (args.assertion) {
|
|
67
|
+
tracker.addAssertion({
|
|
68
|
+
passed: !args.error,
|
|
69
|
+
assertion: args.assertion,
|
|
70
|
+
name: args.assertion,
|
|
71
|
+
error: args.error,
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
})
|
|
75
|
+
.on('item', (_err, args) => {
|
|
76
|
+
if (args.item) {
|
|
77
|
+
const testResults = tracker.displayCurrentResults();
|
|
78
|
+
if (testResults) {
|
|
79
|
+
output.add(`\n📝 Request: ${args.item.name}`);
|
|
80
|
+
output.add(testResults);
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
})
|
|
84
|
+
.on('done', (err, summary) => {
|
|
85
|
+
const endTime = Date.now();
|
|
86
|
+
const durationMs = endTime - startTime;
|
|
87
|
+
const durationSec = (durationMs / 1000).toFixed(2);
|
|
88
|
+
if (err) {
|
|
89
|
+
output.add('\n❌ Run error: ' + err.message);
|
|
90
|
+
output.add(`⏱️ Duration: ${durationSec}s`);
|
|
91
|
+
reject(err);
|
|
92
|
+
return;
|
|
93
|
+
}
|
|
94
|
+
output.add('\n=== ✅ Run completed! ===');
|
|
95
|
+
output.add(`⏱️ Duration: ${durationSec}s`);
|
|
96
|
+
const testStats = tracker.getTotalStats();
|
|
97
|
+
if (testStats.total > 0) {
|
|
98
|
+
output.add('\n📊 Overall Test Statistics:');
|
|
99
|
+
output.add(` Total tests: ${testStats.total}`);
|
|
100
|
+
output.add(` Passed: ${testStats.passed} ✅`);
|
|
101
|
+
output.add(` Failed: ${testStats.failed} ❌`);
|
|
102
|
+
output.add(` Success rate: ${((testStats.passed / testStats.total) * 100).toFixed(1)}%`);
|
|
103
|
+
}
|
|
104
|
+
if (summary?.run?.stats) {
|
|
105
|
+
output.add('\n📈 Request Summary:');
|
|
106
|
+
output.add(` Total requests: ${summary.run.stats.requests?.total || 0}`);
|
|
107
|
+
output.add(` Failed requests: ${summary.run.stats.requests?.failed || 0}`);
|
|
108
|
+
output.add(` Total assertions: ${summary.run.stats.assertions?.total || 0}`);
|
|
109
|
+
output.add(` Failed assertions: ${summary.run.stats.assertions?.failed || 0}`);
|
|
110
|
+
if (summary.run.stats.iterations) {
|
|
111
|
+
output.add(` Total iterations: ${summary.run.stats.iterations.total || 0}`);
|
|
112
|
+
output.add(` Failed iterations: ${summary.run.stats.iterations.failed || 0}`);
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
resolve();
|
|
116
|
+
});
|
|
117
|
+
});
|
|
118
|
+
return {
|
|
119
|
+
content: [
|
|
120
|
+
{
|
|
121
|
+
type: 'text',
|
|
122
|
+
text: output.build(),
|
|
123
|
+
},
|
|
124
|
+
],
|
|
125
|
+
};
|
|
126
|
+
}
|
|
127
|
+
catch (e) {
|
|
128
|
+
if (e instanceof McpError) {
|
|
129
|
+
throw e;
|
|
130
|
+
}
|
|
131
|
+
throw asMcpError(e);
|
|
132
|
+
}
|
|
133
|
+
}
|
|
@@ -29,6 +29,9 @@ export const parameters = z.object({
|
|
|
29
29
|
})
|
|
30
30
|
.describe("The mock server's configuration settings.")
|
|
31
31
|
.optional(),
|
|
32
|
+
collection: z
|
|
33
|
+
.string()
|
|
34
|
+
.describe("The associated collection's unique ID. This is a mandatory parameter."),
|
|
32
35
|
})
|
|
33
36
|
.optional(),
|
|
34
37
|
});
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
export class TestTracker {
|
|
2
|
+
assertions = [];
|
|
3
|
+
totalTests = 0;
|
|
4
|
+
totalPassed = 0;
|
|
5
|
+
totalFailed = 0;
|
|
6
|
+
addAssertion(assertion) {
|
|
7
|
+
this.assertions.push(assertion);
|
|
8
|
+
this.totalTests++;
|
|
9
|
+
if (assertion.passed) {
|
|
10
|
+
this.totalPassed++;
|
|
11
|
+
}
|
|
12
|
+
else {
|
|
13
|
+
this.totalFailed++;
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
displayCurrentResults() {
|
|
17
|
+
if (this.assertions.length === 0) {
|
|
18
|
+
return '';
|
|
19
|
+
}
|
|
20
|
+
const lines = [' 📊 Test Results:'];
|
|
21
|
+
this.assertions.forEach((assertion) => {
|
|
22
|
+
const status = assertion.passed ? '✓' : '✗';
|
|
23
|
+
const name = assertion.assertion || assertion.name || 'Unnamed test';
|
|
24
|
+
lines.push(` ${status} ${name}`);
|
|
25
|
+
if (!assertion.passed && assertion.error) {
|
|
26
|
+
const errorMessage = typeof assertion.error === 'string'
|
|
27
|
+
? assertion.error
|
|
28
|
+
: assertion.error.message || 'Unknown error';
|
|
29
|
+
lines.push(` └─ Error: ${errorMessage}`);
|
|
30
|
+
}
|
|
31
|
+
});
|
|
32
|
+
const passed = this.assertions.filter((a) => a.passed).length;
|
|
33
|
+
const failed = this.assertions.filter((a) => !a.passed).length;
|
|
34
|
+
lines.push(` ────────────────────────────────────────`);
|
|
35
|
+
lines.push(` ${this.assertions.length} tests | ✓ ${passed} passed | ✗ ${failed} failed\n`);
|
|
36
|
+
this.assertions.length = 0;
|
|
37
|
+
return lines.join('\n');
|
|
38
|
+
}
|
|
39
|
+
getTotalStats() {
|
|
40
|
+
return {
|
|
41
|
+
total: this.totalTests,
|
|
42
|
+
passed: this.totalPassed,
|
|
43
|
+
failed: this.totalFailed,
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
reset() {
|
|
47
|
+
this.assertions.length = 0;
|
|
48
|
+
this.totalTests = 0;
|
|
49
|
+
this.totalPassed = 0;
|
|
50
|
+
this.totalFailed = 0;
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
export class OutputBuilder {
|
|
54
|
+
lines = [];
|
|
55
|
+
add(line) {
|
|
56
|
+
this.lines.push(line);
|
|
57
|
+
}
|
|
58
|
+
build() {
|
|
59
|
+
return this.lines.join('\n');
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
export function buildNewmanOptions(params, collection, environment) {
|
|
63
|
+
return {
|
|
64
|
+
collection: collection,
|
|
65
|
+
environment: environment,
|
|
66
|
+
iterationCount: params.iterationCount || 1,
|
|
67
|
+
timeout: params.requestTimeout || 60000,
|
|
68
|
+
timeoutRequest: params.requestTimeout || 60000,
|
|
69
|
+
timeoutScript: params.scriptTimeout || 5000,
|
|
70
|
+
delayRequest: 1000,
|
|
71
|
+
ignoreRedirects: false,
|
|
72
|
+
insecure: false,
|
|
73
|
+
bail: params.stopOnFailure ? ['failure'] : false,
|
|
74
|
+
suppressExitCode: true,
|
|
75
|
+
reporters: [],
|
|
76
|
+
reporter: {},
|
|
77
|
+
color: 'off',
|
|
78
|
+
verbose: false,
|
|
79
|
+
requestAgents: {
|
|
80
|
+
http: undefined,
|
|
81
|
+
https: undefined,
|
|
82
|
+
},
|
|
83
|
+
};
|
|
84
|
+
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@postman/postman-mcp-server",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.4.0",
|
|
4
4
|
"description": "A simple MCP server to operate on the Postman API",
|
|
5
|
+
"mcpName": "com.postman/@postman/postman-mcp-server",
|
|
5
6
|
"main": "dist/src/index.js",
|
|
6
7
|
"type": "module",
|
|
7
8
|
"scripts": {
|
|
@@ -30,7 +31,8 @@
|
|
|
30
31
|
"@modelcontextprotocol/sdk": "^1.18.1",
|
|
31
32
|
"dotenv": "^17.2.2",
|
|
32
33
|
"es-toolkit": "^1.39.10",
|
|
33
|
-
"express": "^5.1.0"
|
|
34
|
+
"express": "^5.1.0",
|
|
35
|
+
"newman": "^6.2.1"
|
|
34
36
|
},
|
|
35
37
|
"devDependencies": {
|
|
36
38
|
"@eslint/js": "^9.35.0",
|