postman

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Postman Agent Skill

Postman Agent 技能

Full API lifecycle management through the Postman MCP Server. Sync specs, generate code, run tests, create mocks, publish docs, and audit security.

Version: 2.0.1 Requires: Postman MCP Server

通过Postman MCP Server实现完整的API生命周期管理。同步规范、生成代码、运行测试、创建模拟服务、发布文档并进行安全审计。

版本: 2.0.1 依赖: Postman MCP Server

Prerequisites

前提条件

This skill requires the Postman MCP Server to be configured. The MCP server exposes 111+ tools for interacting with Postman workspaces, collections, specs, environments, mocks, monitors, and more.

Setup check: Call

getAuthenticatedUser

via MCP. If it succeeds, you're connected. If it fails, walk through Setup below.

使用此技能需要配置Postman MCP Server。MCP服务器提供了111+个工具，用于与Postman工作空间、集合、规范、环境、模拟服务、监控等进行交互。

连接检查: 通过MCP调用

getAuthenticatedUser

。如果调用成功，则已连接；如果失败，请按照下方的设置步骤操作。

Important: MCP Tool Behavior

重要提示：MCP工具行为

Before using the workflows below, be aware of these behaviors:

getWorkspaces
returns ALL workspaces. For large organizations this can be 300KB+. If you already have a workspace ID, use
```
getWorkspace(workspaceId)
```
directly instead.
getCollection
default response is a lightweight map with
```
itemRefs
```
(folder/request tree). This is efficient for discovery. Only use
```
model=full
```
when you need complete request/response bodies, and be aware it can exceed 300KB for large collections. Prefer targeted
```
getCollectionRequest
```
and
```
getCollectionResponse
```
calls for specific endpoints.
getTaggedEntities
returns 404 for missing tags, not an empty array. Handle this gracefully. Tag functionality may require an Enterprise plan.
runCollection
returns aggregate results only (total requests, passed, failed, duration). It does NOT return per-request detail or error messages. For debugging specific failures, examine individual requests with
```
getCollectionRequest
```
and
```
getCollectionResponse
```
after the run.
searchPostmanElements
only searches the PUBLIC Postman network, not private workspaces. Always search private workspace first with
```
getCollections
```
.

在使用以下工作流之前，请注意以下行为：

getWorkspaces
会返回所有工作空间。对于大型组织，返回数据可能超过300KB。如果您已有工作空间ID，请直接使用
```
getWorkspace(workspaceId)
```
。
getCollection
的默认响应是轻量级映射，包含
```
itemRefs
```
（文件夹/请求树）。这对于发现操作非常高效。仅当您需要完整的请求/响应体时，才使用
```
model=full
```
参数，请注意大型集合的响应可能超过300KB。对于特定端点，优先使用针对性的
```
getCollectionRequest
```
和
```
getCollectionResponse
```
调用。
getTaggedEntities
在标签不存在时返回404，而非空数组。请优雅处理此情况。标签功能可能需要企业版计划。
runCollection
仅返回聚合结果（总请求数、通过数、失败数、耗时）。不会返回每个请求的详细信息或错误消息。如需调试特定失败，请在运行后使用
```
getCollectionRequest
```
和
```
getCollectionResponse
```
检查单个请求。
searchPostmanElements
仅搜索公开的Postman网络，不包括私有工作空间。请始终先使用
```
getCollections
```
搜索私有工作空间。

Setup

设置步骤

If MCP tools are not available or

getAuthenticatedUser

fails:

Get a Postman API key:
- Go to https://postman.postman.co/settings/me/api-keys
- Click "Generate API Key", name it "Claude Code"
- Copy the key (starts with PMAK-)

Set the environment variable:

export POSTMAN_API_KEY=PMAK-your-key-here

Add to

~/.zshrc

~/.bashrc

to persist.

Verify: Call
```
getAuthenticatedUser
```
. On success, call
```
getWorkspaces
```
to list workspaces, then
```
getCollections
```
with the workspace ID to count resources.

Present:

Connected as: <user name>

Your workspaces:
  - My Workspace (personal) - 12 collections, 3 specs
  - Team APIs (team) - 8 collections, 5 specs

You're all set.

如果MCP工具不可用或

getAuthenticatedUser

调用失败：

获取Postman API密钥：
- 访问https://postman.postman.co/settings/me/api-keys
- 点击"Generate API Key"，命名为"Claude Code"
- 复制密钥（以PMAK-开头）
设置环境变量：
```
export POSTMAN_API_KEY=PMAK-your-key-here
```
将其添加到
```
~/.zshrc
```
或
```
~/.bashrc
```
中以持久化设置。
验证：调用
```
getAuthenticatedUser
```
。成功后，调用
```
getWorkspaces
```
列出工作空间，然后使用工作空间ID调用
```
getCollections
```
统计资源。

验证成功后显示：

已连接用户: <用户名>

您的工作空间:
  - 我的工作空间（个人） - 12个集合，3个规范
  - 团队API（团队） - 8个集合，5个规范

设置完成。

Routing

路由规则

When the user's request involves Postman or APIs, match their intent to the correct workflow below. Always prefer these structured workflows over raw MCP tool calls.

User Intent	Workflow
Import a spec, push spec to Postman, create collection from spec, sync, push changes	Sync Collections
Generate client code, SDK, wrapper, typed client, consume an API	Generate Client Code
Find API, search endpoints, what's available, discover APIs	Discover APIs
Run tests, check if tests pass, validate API, test collection	Run Collection Tests
Create mock server, fake API, mock for frontend, mock URL	Create Mock Servers
Generate docs, improve documentation, publish docs, API docs	API Documentation
Security audit, vulnerabilities, OWASP, security check	API Security Audit
Is my API agent-ready?, scan my API, analyze spec for AI	Use the postman-api-readiness skill

Routing rules:

Specific workflows take priority. If intent clearly maps to one, use it.
Ambiguous requests: ask the user what they need.
Multi-step requests chain workflows. "Import my spec and run tests" = Sync then Test.
Only use
```
mcp__postman__*
```
tools directly for single targeted updates or when the user explicitly asks.

当用户的请求涉及Postman或API时，将其意图匹配到以下对应的工作流。请始终优先使用这些结构化工作流，而非直接调用原始MCP工具。

用户意图	工作流
导入规范、将规范推送到Postman、从规范创建集合、同步、推送变更	同步集合
生成客户端代码、SDK、包装器、类型化客户端、调用API	生成客户端代码
查找API、搜索端点、了解可用资源、发现API	发现API
运行测试、检查测试是否通过、验证API、测试集合	运行集合测试
创建模拟服务器、模拟API、为前端提供模拟服务、模拟URL	创建模拟服务器
生成文档、改进文档、发布文档、API文档	API文档
安全审计、漏洞检查、OWASP、安全检测	API安全审计
我的API是否支持Agent？、扫描我的API、分析AI适配的规范	使用postman-api-readiness技能

路由规则:

特定工作流优先。如果意图明确匹配某个工作流，请使用该工作流。
模糊请求：询问用户具体需求。
多步骤请求可串联工作流。例如“导入我的规范并运行测试” = 同步工作流 + 测试工作流。
仅在进行单一针对性更新或用户明确要求时，才直接使用
```
mcp__postman__*
```
工具。

Workflow: Sync Collections

工作流：同步集合

Keep Postman collections in sync with API code. Create new collections from OpenAPI specs, update existing ones, or push endpoint changes.

保持Postman集合与API代码同步。从OpenAPI规范创建新集合、更新现有集合，或推送端点变更。

Step 1: Understand What Changed

步骤1：了解变更内容

Detect or ask:

Is there a local OpenAPI spec? Search for

**/openapi.{json,yaml,yml}

**/swagger.{json,yaml,yml}

Did the user add/remove/modify endpoints?
Is there an existing Postman collection to update, or do they need a new one?

检测或询问用户：

是否有本地OpenAPI规范？搜索

**/openapi.{json,yaml,yml}

、

**/swagger.{json,yaml,yml}

用户是否添加/删除/修改了端点？
是否存在需要更新的现有Postman集合，还是需要创建新集合？

Step 2: Resolve Workspace

步骤2：确定工作空间

If the user provides a workspace ID, call

getWorkspace(workspaceId)

directly. Otherwise, call

getCollections

with a workspace ID if known, or ask the user which workspace to use. Avoid calling

getWorkspaces

(no filter) on large org accounts as it returns all workspaces (300KB+).

如果用户提供了工作空间ID，请直接调用

getWorkspace(workspaceId)

。否则，若已知工作空间ID，调用

getCollections

；若未知，请询问用户使用哪个工作空间。避免在大型组织账户中调用

getWorkspaces

（无过滤），因为它会返回所有工作空间（数据量超过300KB）。

Step 3: Find or Create the Collection

步骤3：查找或创建集合

Updating an existing collection:

Call
```
getCollections
```
with the
```
workspace
```
parameter
Match by name or ask which collection
Call
```
getCollection
```
to get current state

Creating from a spec:

Read the local OpenAPI spec

Call

createSpec

with

workspaceId

name

type

(one of

OPENAPI:2.0

OPENAPI:3.0

OPENAPI:3.1

ASYNCAPI:2.0

), and

files

(array of

{path, content}

)

Call
```
generateCollection
```
from the spec. This is async (HTTP 202). Poll
```
getGeneratedCollectionSpecs
```
or
```
getSpecCollections
```
until complete.
Call
```
createEnvironment
```
with variables from the spec:
- ```
base_url
```
  from
```
servers[0].url
```
- Auth variables from
```
securitySchemes
```
  (mark as
```
secret
```
  )
- Common path parameters

更新现有集合:

使用
```
workspace
```
参数调用
```
getCollections
```
通过名称匹配或询问用户选择集合
调用
```
getCollection
```
获取当前状态

从规范创建集合:

读取本地OpenAPI规范

使用

workspaceId

、

name

、

type

（可选值为

OPENAPI:2.0

、

OPENAPI:3.0

、

OPENAPI:3.1

、

ASYNCAPI:2.0

）和

files

（

{path, content}

数组）调用

createSpec

从规范调用
```
generateCollection
```
。此操作是异步的（HTTP 202）。轮询
```
getGeneratedCollectionSpecs
```
或
```
getSpecCollections
```
直到操作完成。
使用规范中的变量调用
```
createEnvironment
```
：
- 从
```
servers[0].url
```
  获取
```
base_url
```
- 从
```
securitySchemes
```
  获取认证变量（标记为
```
secret
```
  ）
- 通用路径参数

Step 4: Sync

步骤4：同步

Spec to Collection (most common):

Call
```
createSpec
```
or
```
updateSpecFile
```
with local spec content
Call
```
syncCollectionWithSpec
```
to update the collection. Async (HTTP 202). Poll
```
getCollectionUpdatesTasks
```
for completion.
Note:
```
syncCollectionWithSpec
```
only supports OpenAPI 3.0. For Swagger 2.0 or OpenAPI 3.1, use
```
updateSpecFile
```
and regenerate via
```
generateCollection
```
.
Report what changed

Collection to Spec (reverse sync):

Call
```
syncSpecWithCollection
```
to update the spec from collection changes
Write the updated spec back to the local file

Manual updates (no spec):

```
createCollectionRequest
```
to add new endpoints
```
updateCollectionRequest
```
to modify existing ones
```
createCollectionFolder
```
to organize by resource
```
createCollectionResponse
```
to add example responses

规范到集合（最常见）:

使用本地规范内容调用
```
createSpec
```
或
```
updateSpecFile
```
调用
```
syncCollectionWithSpec
```
更新集合。此操作是异步的（HTTP 202）。轮询
```
getCollectionUpdatesTasks
```
直到完成。
注意：
```
syncCollectionWithSpec
```
仅支持OpenAPI 3.0。对于Swagger 2.0或OpenAPI 3.1，请使用
```
updateSpecFile
```
并通过
```
generateCollection
```
重新生成集合。
报告变更内容

集合到规范（反向同步）:

调用
```
syncSpecWithCollection
```
从集合变更更新规范
将更新后的规范写回本地文件

手动更新（无规范）:

使用
```
createCollectionRequest
```
添加新端点
使用
```
updateCollectionRequest
```
修改现有端点
使用
```
createCollectionFolder
```
按资源组织端点
使用
```
createCollectionResponse
```
添加示例响应

Step 5: Confirm

步骤5：确认

Collection synced: "Pet Store API" (15 requests)
  Added:    POST /pets/{id}/vaccinations
  Updated:  GET /pets - added 'breed' filter parameter
  Removed:  (none)

  Environment: "Pet Store - Development" updated
  Spec Hub: petstore-v3.1.0 pushed

集合已同步: "Pet Store API"（15个请求）
  新增:    POST /pets/{id}/vaccinations
  更新:  GET /pets - 添加'breed'过滤参数
  删除:  无

  环境: "Pet Store - Development"已更新
  规范中心: petstore-v3.1.0已推送

Workflow: Generate Client Code

工作流：生成客户端代码

Generate typed client code from Postman collections. Reads private API definitions and writes production-ready code matching the project's conventions.

从Postman集合生成类型化客户端代码。读取私有API定义并生成符合项目规范的生产级代码。

Step 1: Find the API

步骤1：查找API

If workspace ID is known, call
```
getWorkspace(workspaceId)
```
to get the full inventory (collections, specs, environments) in one call. Otherwise ask the user which workspace.
Call
```
getCollections
```
with
```
workspace
```
parameter. Use
```
name
```
filter if specified.
If no results in private workspace, fall back to
```
searchPostmanElements
```
(public network only)
Call
```
getCollection
```
for the lightweight map (default, no
```
model
```
param)
Call
```
getSpecDefinition
```
if a linked spec exists (richer type info)

如果已知工作空间ID，调用
```
getWorkspace(workspaceId)
```
一次性获取完整资源清单（集合、规范、环境）。否则询问用户使用哪个工作空间。
使用
```
workspace
```
参数调用
```
getCollections
```
。如果指定了名称，使用
```
name
```
过滤。
如果私有工作空间中无结果，回退到
```
searchPostmanElements
```
（仅公开网络）
调用
```
getCollection
```
获取轻量级映射（默认，不使用
```
model
```
参数）
如果存在关联规范，调用
```
getSpecDefinition
```
（获取更丰富的类型信息）

Step 2: Understand the API Shape

步骤2：了解API结构

For each relevant endpoint:

Call
```
getCollectionFolder
```
for resource grouping
Call
```
getCollectionRequest
```
for method, URL, headers, auth, body schema, parameters
Call
```
getCollectionResponse
```
for status codes, response shapes, error formats
Call
```
getEnvironment
```
for base URLs and variables
Call
```
getCodeGenerationInstructions
```
for Postman-specific codegen guidance

对于每个相关端点：

调用
```
getCollectionFolder
```
获取资源分组
调用
```
getCollectionRequest
```
获取方法、URL、请求头、认证、请求体 schema、参数
调用
```
getCollectionResponse
```
获取状态码、响应结构、错误格式
调用
```
getEnvironment
```
获取基础URL和变量
调用
```
getCodeGenerationInstructions
```
获取Postman特定的代码生成指导

Step 3: Detect Project Language

步骤3：检测项目语言

If not specified, detect from the project:

```
package.json
```
or
```
tsconfig.json
```
-> TypeScript/JavaScript
```
requirements.txt
```
or
```
pyproject.toml
```
-> Python
```
go.mod
```
-> Go
```
Cargo.toml
```
-> Rust
```
pom.xml
```
or
```
build.gradle
```
-> Java
```
Gemfile
```
-> Ruby

如果未指定，从项目中检测：

```
package.json
```
或
```
tsconfig.json
```
-> TypeScript/JavaScript
```
requirements.txt
```
或
```
pyproject.toml
```
-> Python
```
go.mod
```
-> Go
```
Cargo.toml
```
-> Rust
```
pom.xml
```
或
```
build.gradle
```
-> Java
```
Gemfile
```
-> Ruby

Step 3b: Check for Variable Mismatches

步骤3b：检查变量不匹配

Compare collection variables with environment variables. Common issue: collection uses

{{baseUrl}}

but environment defines

base_url

(or vice versa). Flag any naming mismatches to the user before generating code, as these cause silent failures at runtime.

比较集合变量与环境变量。常见问题：集合使用

{{baseUrl}}

但环境定义的是

base_url

（反之亦然）。在生成代码前向用户标记任何命名不匹配，因为这些问题会导致运行时静默失败。

Step 4: Generate Code

步骤4：生成代码

Generate a typed client with:

Method per endpoint with proper parameters
Request/response types from collection schemas
Authentication handling from collection auth config
Error handling based on documented error responses
Environment-based configuration (base URL from env vars)
Pagination support if the API uses it

Code conventions:

Match the project's existing style (imports, formatting, naming)
Include JSDoc/docstrings from collection descriptions
Use the project's HTTP library if one exists (axios, fetch, requests, etc.)
Write to a sensible path (e.g.,
```
src/clients/<api-name>.ts
```
)

生成类型化客户端，包含：

每个端点对应一个方法，参数正确
从集合schema生成的请求/响应类型
从集合认证配置处理认证
基于文档化错误响应的错误处理
基于环境的配置（基础URL来自环境变量）
如果API支持，添加分页支持

代码规范:

匹配项目现有风格（导入、格式化、命名）
包含集合描述中的JSDoc/文档字符串
如果项目已有HTTP库（axios、fetch、requests等），使用该库
写入合理路径（例如
```
src/clients/<api-name>.ts
```
）

Step 5: Present

步骤5：结果展示

Generated: src/clients/users-api.ts

  Endpoints covered:
    GET    /users         -> getUsers(filters)
    POST   /users         -> createUser(data)
    GET    /users/{id}    -> getUser(id)
    PUT    /users/{id}    -> updateUser(id, data)
    DELETE /users/{id}    -> deleteUser(id)

  Types generated: User, CreateUserRequest, UpdateUserRequest, UserListResponse, ApiError
  Auth: Bearer token (from USERS_API_TOKEN env var)
  Base URL: from USERS_API_BASE_URL env var

已生成: src/clients/users-api.ts

  覆盖的端点:
    GET    /users         -> getUsers(filters)
    POST   /users         -> createUser(data)
    GET    /users/{id}    -> getUser(id)
    PUT    /users/{id}    -> updateUser(id, data)
    DELETE /users/{id}    -> deleteUser(id)

  生成的类型: User, CreateUserRequest, UpdateUserRequest, UserListResponse, ApiError
  认证: Bearer token（来自USERS_API_TOKEN环境变量）
  基础URL: 来自USERS_API_BASE_URL环境变量

Workflow: Discover APIs

工作流：发现API

Answer natural language questions about available APIs across Postman workspaces. Find endpoints, check response shapes, understand what's available.

以自然语言回答关于Postman工作空间中可用API的问题。查找端点、检查响应结构、了解可用资源。

Step 1: Search

步骤1：搜索

If workspace ID is known, call
```
getWorkspace(workspaceId)
```
directly. Otherwise ask the user.
Call
```
getCollections
```
with
```
workspace
```
parameter. Use
```
name
```
filter to narrow.
If sparse, broaden:
- ```
searchPostmanElements
```
  as fallback (public network only, not private workspaces)
- Note:
```
getTaggedEntities
```
  and
```
getCollectionTags
```
  may return 404/403 on non-Enterprise plans. Do not rely on these for discovery.

如果已知工作空间ID，直接调用
```
getWorkspace(workspaceId)
```
。否则询问用户。
使用
```
workspace
```
参数调用
```
getCollections
```
。使用
```
name
```
过滤缩小范围。
如果结果较少，扩大范围：
- 使用
```
searchPostmanElements
```
  作为回退（仅公开网络，不包括私有工作空间）
- 注意：
```
getTaggedEntities
```
  和
```
getCollectionTags
```
  在非企业版计划中可能返回404/403。请勿依赖这些工具进行发现。

Step 2: Drill Into Results

步骤2：深入分析结果

For each relevant hit:

```
getCollection
```
for overview (default returns lightweight map with
```
itemRefs
```
, not full payloads)
Scan endpoint names from the map to identify relevant folders/requests
```
getCollectionRequest
```
for specific relevant endpoints (targeted, not bulk)
```
getCollectionResponse
```
for specific response data
```
getSpecDefinition
```
if linked spec exists

对于每个相关结果：

调用
```
getCollection
```
获取概览（默认返回轻量级映射，包含
```
itemRefs
```
，而非完整负载）
从映射中扫描端点名称，识别相关文件夹/请求
调用
```
getCollectionRequest
```
获取特定相关端点（针对性调用，而非批量）
调用
```
getCollectionResponse
```
获取特定响应数据
如果存在关联规范，调用
```
getSpecDefinition
```

Step 3: Present

步骤3：结果展示

Found:

Yes, you can get a user's email via the API.

  Endpoint: GET /users/{id}
  Collection: "User Management API"
  Auth: Bearer token required

  Response includes:
    { "id": "usr_123", "email": "jane@example.com", "name": "Jane Smith" }

  Want me to generate a client for this API?

Not found: Show closest matches and explain why they don't match.

Multiple results: List collections with endpoint counts, ask which to explore.

找到匹配API:

是的，您可以通过API获取用户的邮箱。

  端点: GET /users/{id}
  集合: "User Management API"
  认证: 需要Bearer token

  响应包含:
    { "id": "usr_123", "email": "jane@example.com", "name": "Jane Smith" }

  需要我为这个API生成客户端吗？

未找到匹配API: 显示最接近的匹配并说明不匹配的原因。

多个结果: 列出带端点数量的集合，询问用户要探索哪个。

Workflow: Run Collection Tests

工作流：运行集合测试

Execute Postman collection tests, analyze results, diagnose failures, and suggest fixes.

执行Postman集合测试、分析结果、诊断失败并建议修复方案。

Step 1: Find the Collection

步骤1：查找集合

If workspace ID is known, call
```
getWorkspace(workspaceId)
```
directly. Otherwise ask the user.
Call
```
getCollections
```
with
```
workspace
```
parameter. Use
```
name
```
filter if specified.

如果已知工作空间ID，直接调用
```
getWorkspace(workspaceId)
```
。否则询问用户。
使用
```
workspace
```
参数调用
```
getCollections
```
。如果指定了名称，使用
```
name
```
过滤。

Step 2: Run Tests

步骤2：运行测试

Call

runCollection

with the collection UID in

OWNER_ID-UUID

format (from

getCollection

response's

uid

field).

If environment variables are needed:

Call
```
getEnvironments
```
to list available environments
Ask which to use or detect from naming convention
Pass the environment ID to
```
runCollection
```

使用集合UID（格式为

OWNER_ID-UUID

，来自

getCollection

响应的

uid

字段）调用

runCollection

。

如果需要环境变量：

调用
```
getEnvironments
```
列出可用环境
询问用户使用哪个环境，或根据命名 convention 检测
将环境ID传递给
```
runCollection
```

Step 3: Parse Results

步骤3：解析结果

Note:

runCollection

returns aggregate results only (total requests, passed/failed counts, duration). It does NOT include per-request detail. Present what's available:

Test Results: Pet Store API
  Requests:  15 executed
  Failed:    3
  Assertions: 24 total, 21 passed
  Duration:  12.4s

If tests failed and per-request detail is needed, examine the collection's test scripts and request definitions with

getCollectionRequest

to help diagnose. The user may also need to check the Postman app or a monitor run for detailed failure logs.

注意:

runCollection

仅返回聚合结果（总请求数、通过/失败数、耗时）。不包含每个请求的详细信息。展示可用信息：

测试结果: Pet Store API
  请求数:  15个已执行
  失败数:    3个
  断言数: 24个总断言，21个通过
  耗时:  12.4秒

如果测试失败且需要每个请求的详细信息，请使用

getCollectionRequest

检查集合的测试脚本和请求定义以帮助诊断。用户可能还需要检查Postman应用或监控运行以获取详细失败日志。

Step 4: Diagnose Failures

步骤4：诊断失败

For each failure:

```
getCollectionRequest
```
for full request definition
```
getCollectionResponse
```
for expected responses
Check if API source code is in the current project
Explain expected vs actual
If code is local, find the handler and suggest the fix

对于每个失败：

调用
```
getCollectionRequest
```
获取完整请求定义
调用
```
getCollectionResponse
```
获取预期响应
检查当前项目中是否有API源代码
说明预期与实际情况
如果代码在本地，找到处理程序并建议修复方案

Step 5: Fix and Re-run

步骤5：修复并重新运行

After fixing: offer to re-run and show before/after comparison.

修复后：主动提出重新运行并展示前后对比。

Step 6: Update Collection (if needed)

步骤6：更新集合（如有需要）

If the tests themselves need updating:

```
updateCollectionRequest
```
to fix request bodies, headers, or test scripts
```
updateCollectionResponse
```
to update expected responses

如果测试本身需要更新：

使用
```
updateCollectionRequest
```
修复请求体、请求头或测试脚本
使用
```
updateCollectionResponse
```
更新预期响应

Workflow: Create Mock Servers

工作流：创建模拟服务器

Spin up a Postman mock server from a collection or spec. Get a working mock URL for frontend development, integration testing, or demos.

从集合或规范启动Postman模拟服务器。获取可用于前端开发、集成测试或演示的可用模拟URL。

Step 1: Find the Source

步骤1：查找源

If workspace ID is known, call

getWorkspace(workspaceId)

directly. Otherwise ask the user.

From existing collection:

getCollections

with workspace ID -> select target collection

From local spec: Import first:

```
createSpec
```
with workspace, name, type, files

generateCollection

. Async (HTTP 202). Poll

getGeneratedCollectionSpecs

getSpecCollections

for completion.

如果已知工作空间ID，直接调用

getWorkspace(workspaceId)

。否则询问用户。

从现有集合: 使用工作空间ID调用

getCollections

-> 选择目标集合

从本地规范: 先导入：

使用工作空间、名称、类型、文件调用
```
createSpec
```
调用
```
generateCollection
```
。此操作是异步的（HTTP 202）。轮询
```
getGeneratedCollectionSpecs
```
或
```
getSpecCollections
```
直到完成。

Step 2: Check for Examples

步骤2：检查示例

Mock servers serve example responses. Call

getCollection

and check if requests have saved responses.

If missing, generate realistic examples:

```
getCollectionRequest
```
for each request's schema
Generate realistic example response from the schema
```
createCollectionResponse
```
to save the example

模拟服务器返回示例响应。调用

getCollection

并检查请求是否已保存响应。

如果缺少示例，生成真实示例：

调用
```
getCollectionRequest
```
获取每个请求的schema
从schema生成真实示例响应
调用
```
createCollectionResponse
```
保存示例

Step 3: Check for Existing Mocks

步骤3：检查现有模拟服务

Call

getMocks

to check if one already exists for this collection. If found, present its URL. Only create new if none exists or explicitly requested.

调用

getMocks

检查此集合是否已有模拟服务。如果找到，展示其URL。仅在不存在或用户明确要求时创建新的模拟服务。

Step 4: Create Mock Server

步骤4：创建模拟服务器

Call

createMock

with:

Workspace ID
Collection UID in
```
ownerId-collectionId
```
format (from
```
getCollection
```
response's
```
uid
```
field)
Environment ID (if applicable)
Name:
```
<api-name> Mock
```
Private: false (or true if preferred)

调用

createMock

，参数包括：

工作空间ID
集合UID（格式为
```
ownerId-collectionId
```
，来自
```
getCollection
```
响应的
```
uid
```
字段）
环境ID（如适用）
名称:
```
<api-name> Mock
```
私有: false（或根据偏好设置为true）

Step 5: Present

步骤5：结果展示

Mock server created: "Pet Store API Mock"
  URL: https://<mock-id>.mock.pstmn.io
  Status: Active

  Try it:
    curl https://<mock-id>.mock.pstmn.io/pets
    curl https://<mock-id>.mock.pstmn.io/pets/1
    curl -X POST https://<mock-id>.mock.pstmn.io/pets -d '{"name":"Buddy"}'

  The mock serves example responses from your collection.
  Update examples in Postman to change mock behavior.

模拟服务器已创建: "Pet Store API Mock"
  URL: https://<mock-id>.mock.pstmn.io
  状态: 活跃

  尝试调用:
    curl https://<mock-id>.mock.pstmn.io/pets
    curl https://<mock-id>.mock.pstmn.io/pets/1
    curl -X POST https://<mock-id>.mock.pstmn.io/pets -d '{"name":"Buddy"}'

  此模拟服务器返回您集合中的示例响应。
  在Postman中更新示例即可更改模拟服务行为。

Step 6: Integration

步骤6：集成

Quick integration:
  # Add to your project .env
  API_BASE_URL=https://<mock-id>.mock.pstmn.io

  # Or in your frontend config
  const API_URL = process.env.API_BASE_URL || 'https://<mock-id>.mock.pstmn.io';

快速集成:
  # 添加到项目.env文件
  API_BASE_URL=https://<mock-id>.mock.pstmn.io

  # 或在前端配置中
  const API_URL = process.env.API_BASE_URL || 'https://<mock-id>.mock.pstmn.io';

Step 7: Publish (optional)

步骤7：发布（可选）

If the user wants public access:

```
publishMock
```
for unauthenticated access (demos, hackathons, public docs)
```
unpublishMock
```
to make private again

如果用户需要公开访问：

调用
```
publishMock
```
以允许未认证访问（演示、黑客松、公开文档）
调用
```
unpublishMock
```
重新设为私有

Workflow: API Documentation

工作流：API文档

Analyze, improve, and publish API documentation from OpenAPI specs and Postman collections.

分析、改进并发布来自OpenAPI规范和Postman集合的API文档。

Step 1: Find the Source

步骤1：查找源

Check for API definitions in order:

Local specs: Search for

**/openapi.{json,yaml,yml}

**/swagger.{json,yaml,yml}

Postman specs:

getAllSpecs

with workspace ID, then

getSpecDefinition

for full spec

Postman collections:

getCollections

then

getCollection

for full detail

按以下顺序检查API定义：

本地规范: 搜索

**/openapi.{json,yaml,yml}

、

**/swagger.{json,yaml,yml}

Postman规范: 使用工作空间ID调用

getAllSpecs

，然后调用

getSpecDefinition

获取完整规范

Postman集合: 调用

getCollections

，然后调用

getCollection

获取完整细节

Step 2: Analyze Completeness

步骤2：分析完整性

Documentation Coverage: 60%
  Endpoints with descriptions:     8/15
  Parameters with descriptions:    22/45
  Endpoints with examples:         3/15
  Error responses documented:      2/15
  Authentication documented:       Yes
  Rate limits documented:          No

文档覆盖率: 60%
  带描述的端点:     8/15
  带描述的参数:    22/45
  带示例的端点:         3/15
  已文档化的错误响应:      2/15
  已文档化的认证:       是
  已文档化的速率限制:          否

Step 3: Generate or Improve

步骤3：生成或改进

Sparse spec: Generate documentation for each endpoint (summaries, parameter tables, request/response schemas, examples, error docs, auth requirements).

Partial spec: Fill gaps (add missing descriptions inferred from naming/schemas, generate realistic examples, add error responses, document auth and rate limits).

规范内容稀疏: 为每个端点生成文档（摘要、参数表、请求/响应schema、示例、错误文档、认证要求）。

规范内容部分完成: 填补空白（从命名/schema推断缺失的描述、生成真实示例、添加错误响应、文档化认证和速率限制）。

Step 4: Apply Changes

步骤4：应用变更

Ask the user which output:

Update the spec file - Write improved docs back into OpenAPI spec
Update in Postman -
```
updateCollectionRequest
```
to add descriptions and examples
Publish public docs -
```
publishDocumentation
```
with collection ID, returns public URL.
```
unpublishDocumentation
```
to take down.
Generate markdown - Create
```
docs/api-reference.md
```
for the project

询问用户输出方式：

更新规范文件 - 将改进后的文档写回OpenAPI规范
在Postman中更新 - 调用
```
updateCollectionRequest
```
添加描述和示例
发布公开文档 - 使用集合ID调用
```
publishDocumentation
```
，返回公开URL。调用
```
unpublishDocumentation
```
可下线。
生成Markdown - 为项目创建
```
docs/api-reference.md
```

Step 5: Sync

步骤5：同步

If both spec and collection exist, keep in sync:

```
syncCollectionWithSpec
```
to update collection from spec (async, OpenAPI 3.0 only)
```
syncSpecWithCollection
```
to update spec from collection changes

如果规范和集合都存在，保持同步：

调用
```
syncCollectionWithSpec
```
从规范更新集合（异步，仅支持OpenAPI 3.0）
调用
```
syncSpecWithCollection
```
从集合变更更新规范

Workflow: API Security Audit

工作流：API安全审计

Audit APIs for security issues against OWASP API Security Top 10. Works with local OpenAPI specs and Postman collections.

针对OWASP API安全Top 10审计API安全问题。支持本地OpenAPI规范和Postman集合。

Step 1: Find the Source

步骤1：查找源

Local spec: Search for OpenAPI/Swagger files in the project

Postman spec:

getAllSpecs

then

getSpecDefinition

Postman collection:

getCollections

then

getCollection

including auth config. Also

getEnvironment

to check for exposed secrets.

本地规范: 在项目中搜索OpenAPI/Swagger文件

Postman规范: 调用

getAllSpecs

，然后调用

getSpecDefinition

Postman集合: 调用

getCollections

，然后调用

getCollection

（包含认证配置）。同时调用

getEnvironment

检查是否有暴露的密钥。

Step 2: Run Security Checks

步骤2：运行安全检查

Authentication and Authorization:

Security schemes defined (OAuth2, API Key, Bearer, etc.)
Security applied globally or per-endpoint
No accidentally unprotected endpoints
OAuth2 scopes defined and appropriate
Admin endpoints have elevated auth

Transport Security:

All server URLs use HTTPS
No mixed HTTP/HTTPS

Sensitive Data Exposure:

No API keys, tokens, or passwords in example values
No secrets in query parameters (should be headers/body)
Password fields marked as
```
format: password
```
PII fields identified
Postman environment variables checked for leaked secrets (via
```
getEnvironment
```
)

Input Validation:

All parameters have defined types
String parameters have
```
maxLength
```
Numeric parameters have
```
minimum
```
/
```
maximum
```
Array parameters have
```
maxItems
```
Enum values used where applicable
Request body has required field validation

Rate Limiting:

Rate limits documented
Rate limit headers defined (X-RateLimit-Limit, X-RateLimit-Remaining)
429 response defined

Error Handling:

Error responses don't leak stack traces
Error schemas don't expose internal field names
401 and 403 responses properly defined

OWASP API Top 10:

API1: Broken Object Level Authorization
API2: Broken Authentication
API3: Broken Object Property Level Authorization
API4: Unrestricted Resource Consumption
API5: Broken Function Level Authorization
API6: Unrestricted Access to Sensitive Business Flows
API7: Server Side Request Forgery
API8: Security Misconfiguration
API9: Improper Inventory Management
API10: Unsafe Consumption of APIs

认证与授权:

是否已定义安全方案（OAuth2、API Key、Bearer等）
是否已全局应用或按端点应用安全
无意外未受保护的端点
是否已定义OAuth2作用域且适用
管理员端点是否有高级认证

传输安全:

所有服务器URL是否使用HTTPS
无混合HTTP/HTTPS情况

敏感数据暴露:

示例值中无API密钥、令牌或密码
查询参数中无密钥（应放在请求头/请求体中）
密码字段是否标记为
```
format: password
```
是否已识别PII字段
检查Postman环境变量是否有泄露的密钥（通过
```
getEnvironment
```
）

输入验证:

所有参数是否已定义类型
字符串参数是否有
```
maxLength
```
数值参数是否有
```
minimum
```
/
```
maximum
```
数组参数是否有
```
maxItems
```
适用的地方是否使用枚举值
请求体是否有必填字段验证

速率限制:

是否已文档化速率限制
是否已定义速率限制请求头（X-RateLimit-Limit、X-RateLimit-Remaining）
是否已定义429响应

错误处理:

错误响应是否不泄露堆栈跟踪
错误schema是否不暴露内部字段名
是否已正确定义401和403响应

OWASP API Top 10:

API1: Broken Object Level Authorization（对象级授权失效）
API2: Broken Authentication（认证失效）
API3: Broken Object Property Level Authorization（对象属性级授权失效）
API4: Unrestricted Resource Consumption（无限制资源消耗）
API5: Broken Function Level Authorization（功能级授权失效）
API6: Unrestricted Access to Sensitive Business Flows（敏感业务流无限制访问）
API7: Server Side Request Forgery（服务器端请求伪造）
API8: Security Misconfiguration（安全配置错误）
API9: Improper Inventory Management（不当资产管理）
API10: Unsafe Consumption of APIs（不安全的API使用）

Step 3: Present Results

步骤3：展示结果

API Security Audit: pet-store-api.yaml

  CRITICAL (2):
    SEC-001: 3 endpoints have no security scheme applied
      - GET /admin/users
      - DELETE /admin/users/{id}
      - PUT /admin/config
    SEC-002: Server URL uses HTTP (http://api.example.com)

  HIGH (3):
    SEC-003: No rate limiting documentation or 429 response
    SEC-004: API key sent as query parameter (use header instead)
    SEC-005: No maxLength on 8 string inputs (injection risk)

  MEDIUM (2):
    SEC-006: Password field visible in GET /users/{id} response
    SEC-007: Environment variable 'db_password' not marked secret

  Score: 48/100 - Significant Issues

API安全审计: pet-store-api.yaml

  严重问题 (2):
    SEC-001: 3个端点未应用安全方案
      - GET /admin/users
      - DELETE /admin/users/{id}
      - PUT /admin/config
    SEC-002: 服务器URL使用HTTP (http://api.example.com)

  高风险问题 (3):
    SEC-003: 无速率限制文档或429响应
    SEC-004: API密钥通过查询参数发送（建议使用请求头）
    SEC-005: 8个字符串输入无maxLength限制（存在注入风险）

  中风险问题 (2):
    SEC-006: GET /users/{id}响应中包含可见的密码字段
    SEC-007: 环境变量'db_password'未标记为密钥

  得分: 48/100 - 存在重大问题

Step 4: Fix

步骤4：修复

For each finding:

Explain the security risk in plain terms
Show the exact spec change needed
Apply the fix with user approval

For Postman-specific issues:

```
putEnvironment
```
to mark secrets properly
```
updateCollectionRequest
```
to fix auth configuration
```
updateCollectionResponse
```
to remove sensitive data from examples

对于每个发现的问题：

用通俗易懂的语言解释安全风险
展示所需的具体规范变更
经用户批准后应用修复

对于Postman特定问题：

调用
```
putEnvironment
```
正确标记密钥
调用
```
updateCollectionRequest
```
修复认证配置
调用
```
updateCollectionResponse
```
从示例中移除敏感数据

Step 5: Re-audit

步骤5：重新审计

After fixes, re-run to show improvement.

修复后，重新运行审计以展示改进效果。

Error Handling

错误处理

These patterns apply across all workflows:

Error	Response
MCP tools not available	"The Postman MCP Server isn't configured. Set your POSTMAN_API_KEY environment variable and restart your editor."
401 Unauthorized	"Your Postman API key was rejected. Generate a new one at https://postman.postman.co/settings/me/api-keys"
Network timeout	Retry once. Check https://status.postman.com for outages.
Async operation stuck	If polling shows no progress after 30 seconds, inform user and suggest checking Postman app directly.
Collection not found	"No collection matching that name. Try discovering APIs across your workspace."
Empty collection	"This collection has no requests. Add endpoints in Postman or sync from a local spec."
Invalid spec	Report specific parse errors with line numbers. Offer to fix common YAML/JSON syntax issues.
Plan limitations	"Some features may require a paid Postman plan. Core operations work on all plans."

以下模式适用于所有工作流：

错误	响应
MCP工具不可用	"Postman MCP Server未配置。请设置POSTMAN_API_KEY环境变量并重启编辑器。"
401未授权	"您的Postman API密钥被拒绝。请在https://postman.postman.co/settings/me/api-keys生成新密钥。"
网络超时	重试一次。访问https://status.postman.com检查是否有服务中断。
异步操作卡住	如果轮询30秒后无进展，通知用户并建议直接检查Postman应用。
集合未找到	"未找到匹配名称的集合。尝试跨工作空间发现API。"
空集合	"此集合无请求。请在Postman中添加端点或从本地规范同步。"
无效规范	报告具体的解析错误和行号。主动提出修复常见YAML/JSON语法问题。
计划限制	"部分功能可能需要Postman付费计划。核心操作在所有计划中可用。"

MCP Tool Reference

MCP工具参考

See

references/mcp-tools.md

for the complete tool catalog and

references/mcp-limitations.md

for known limitations and workarounds.

完整工具目录请查看

references/mcp-tools.md

，已知限制和解决方法请查看

references/mcp-limitations.md

。