postman

Postman Agent Skill

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

版本：2.0.1 要求：Postman MCP Server

前提条件

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

设置检查：通过 MCP 调用 getAuthenticatedUser。如果调用成功，则表示已连接。如果失败，请按照下方的设置步骤操作。

重要：MCP 工具的行为

使用以下工作流前，请注意这些行为：

• getWorkspaces 会返回所有工作空间。 对于大型组织，返回内容可能超过 300KB。如果你已有工作空间 ID，请直接使用 getWorkspace(workspaceId)。
• getCollection 默认返回轻量级映射，其中包含 itemRefs（文件夹/请求树）。这有助于高效发现内容。只有在需要完整请求/响应正文时才使用 model=full，并注意大型集合的返回内容可能超过 300KB。对于特定端点，优先使用定向的 getCollectionRequest 和 getCollectionResponse 调用。
• 缺少标签时，getTaggedEntities 会返回 404，而不是空数组。请妥善处理这种情况。标签功能可能需要 Enterprise 计划。
• runCollection 只返回汇总结果（请求总数、通过数、失败数、耗时）。它不会返回每个请求的详细信息或错误消息。如需调试特定失败，请在运行后使用 getCollectionRequest 和 getCollectionResponse 检查各个请求。
• searchPostmanElements 只会搜索 Postman 公共网络，不会搜索私有工作空间。请始终先使用 getCollections 搜索私有工作空间。

设置

如果 MCP 工具不可用，或 getAuthenticatedUser 调用失败：

1. 获取 Postman API 密钥：

   • 前往 https://postman.postman.co/settings/me/api-keys
   • 点击“Generate API Key”，并将其命名为“Claude Code”
   • 复制密钥（以 PMAK- 开头）

2. 设置环境变量：

   export POSTMAN_API_KEY=PMAK-your-key-here
   

   添加到 ~/.zshrc 或 ~/.bashrc 中以便持久保存。

3. 验证：调用 getAuthenticatedUser。成功后，调用 getWorkspaces 列出工作空间，然后使用工作空间 ID 调用 getCollections，统计资源数量。

呈现：

Connected as: <user name>

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

You're all set.

路由

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

用户意图	工作流
导入规范、将规范推送到 Postman、根据规范创建集合、同步、推送更改	同步集合
生成客户端代码、SDK、封装程序、类型化客户端、使用 API	生成客户端代码
查找 API、搜索端点、了解可用内容、发现 API	发现 API
运行测试、检查测试是否通过、验证 API、测试集合	运行集合测试
创建模拟服务、假 API、供前端使用的模拟、模拟 URL	创建模拟服务
生成文档、改进文档、发布文档、API 文档	API 文档
安全审计、漏洞、OWASP、安全检查	API 安全审计
我的 API 是否已为 Agent 做好准备？扫描我的 API，分析面向 AI 的规范	使用 postman-api-readiness 技能

路由规则：

1. 优先使用特定工作流。如果意图明确对应某个工作流，就使用该工作流。
2. 请求含糊不清时，询问用户的具体需求。
3. 多步骤请求应串联工作流。“导入我的规范并运行测试”＝先同步，再测试。
4. 只有在进行单项定向更新或用户明确要求时，才直接使用 mcp__postman__* 工具。

---

工作流：同步集合

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

步骤 1：了解发生了哪些变更

检测或询问：

• 是否存在本地 OpenAPI 规范？搜索 **/openapi.{json,yaml,yml}、**/swagger.{json,yaml,yml}
• 用户是否添加、移除或修改了端点？
• 是否已有要更新的 Postman 集合，还是需要新建集合？

步骤 2：解析工作区

如果用户提供了工作区 ID，直接调用 getWorkspace(workspaceId)。否则，如果已知工作区 ID，则使用该 ID 调用 getCollections；如果不知道，则询问用户要使用哪个工作区。对于大型组织账户，请避免不带筛选条件地调用 getWorkspaces，因为它会返回所有工作区（300KB 以上）。

步骤 3：查找或创建集合

更新现有集合：

1. 使用 workspace 参数调用 getCollections
2. 按名称匹配，或询问用户要使用哪个集合
3. 调用 getCollection 获取当前状态

从规范创建：

1. 读取本地 OpenAPI 规范
2. 调用 createSpec，并提供 workspaceId、name、type（可选值为 OPENAPI:2.0、OPENAPI:3.0、OPENAPI:3.1、ASYNCAPI:2.0）以及 files（{path, content} 数组）
3. 从规范调用 generateCollection。**这是异步操作（HTTP 202）。**轮询 getGeneratedCollectionSpecs 或 getSpecCollections，直到操作完成。
4. 使用规范中的变量调用 createEnvironment：
   • base_url 来自 servers[0].url
   • 来自 securitySchemes 的身份验证变量（标记为 secret）
   • 常见路径参数

步骤 4：同步

规范同步到集合（最常见）：

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

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

1. 调用 syncSpecWithCollection，根据集合变更更新规范
2. 将更新后的规范写回本地文件

手动更新（无规范）：

1. 使用 createCollectionRequest 添加新端点
2. 使用 updateCollectionRequest 修改现有端点
3. 使用 createCollectionFolder 按资源整理
4. 使用 createCollectionResponse 添加示例响应

步骤 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

---

工作流：生成客户端代码

从 Postman 集合生成类型化客户端代码。读取私有 API 定义，并按照项目惯例编写可用于生产环境的代码。

步骤 1：查找 API

1. 如果已知工作区 ID，调用 getWorkspace(workspaceId)，通过一次调用获取完整清单（集合、规范、环境）。否则询问用户要使用哪个工作区。
2. 使用 workspace 参数调用 getCollections。如果指定了 name，则使用该筛选条件。
3. 如果私有工作区中没有结果，则回退到 searchPostmanElements（仅限公共网络）
4. 调用 getCollection 获取轻量级映射（默认值，不带 model 参数）
5. 如果存在关联的规范，则调用 getSpecDefinition（可获取更丰富的类型信息）

步骤 2：了解 API 结构

对于每个相关端点：

1. 调用 getCollectionFolder，了解资源分组
2. 调用 getCollectionRequest，获取方法、URL、请求头、身份验证、请求体结构和参数
3. 调用 getCollectionResponse，获取状态码、响应结构和错误格式
4. 调用 getEnvironment，获取基础 URL 和变量
5. 调用 getCodeGenerationInstructions，获取 Postman 专用代码生成指南

步骤 3：检测项目语言

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

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

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

比较集合变量与环境变量。常见问题：集合使用 {{baseUrl}}，但环境定义的是 base_url（反之亦然）。在生成代码前，将任何命名不匹配的情况告知用户，因为这可能导致运行时静默失败。

第 4 步：生成代码

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

• 为每个端点提供带有适当参数的方法
• 根据集合架构定义请求和响应类型
• 根据集合身份验证配置处理身份验证
• 根据文档中说明的错误响应处理错误
• 基于环境的配置（从环境变量获取基础 URL）
• 如果 API 使用分页，则支持分页

代码规范：

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

第 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

---

工作流：发现 API

用自然语言回答有关 Postman 工作区中可用 API 的问题。查找端点、检查响应结构并了解可用内容。

第 1 步：搜索

1. 如果已知工作区 ID，直接调用 getWorkspace(workspaceId)。否则询问用户。
2. 使用 workspace 参数调用 getCollections。使用 name 筛选器缩小范围。
3. 如果结果稀少，则扩大搜索范围：
   • 使用 searchPostmanElements 作为后备方案（仅限公共网络，不适用于私有工作区）
   • 注意：在非 Enterprise 计划中，getTaggedEntities 和 getCollectionTags 可能返回 404/403。不要依赖它们来发现内容。

第 2 步：深入查看结果

对于每个相关结果：

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

第 3 步：呈现

已找到：

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": "[email protected]", "name": "Jane Smith" }

  Want me to generate a client for this API?

未找到： 展示最接近的匹配项，并解释它们为何不匹配。

有多个结果： 列出集合及其端点数量，并询问要查看哪个。

---

工作流：运行集合测试

执行 Postman 集合测试、分析结果、诊断故障并提出修复建议。

第 1 步：查找集合

1. 如果已知工作区 ID，直接调用 getWorkspace(workspaceId)。否则询问用户。
2. 使用 workspace 参数调用 getCollections。如果指定了 name，则使用该筛选器。

第 2 步：运行测试

使用集合 UID 调用 runCollection，UID 格式为 OWNER_ID-UUID（来自 getCollection 响应的 uid 字段）。

如果需要环境变量：

1. 调用 getEnvironments 列出可用环境
2. 询问使用哪个环境，或根据命名约定判断
3. 将环境 ID 传递给 runCollection

第 3 步：解析结果

注意： runCollection 仅返回汇总结果（请求总数、通过/失败数量、持续时间），不包含逐个请求的详细信息。展示可用内容：

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

如果测试失败且需要逐个请求的详细信息，请使用 getCollectionRequest 检查集合的测试脚本和请求定义，以帮助诊断问题。用户也可能需要查看 Postman 应用或监视器运行记录，以获取详细的失败日志。

第 4 步：诊断故障

对于每个故障：

1. 调用 getCollectionRequest 获取完整请求定义
2. 调用 getCollectionResponse 获取预期响应
3. 检查当前项目中是否包含 API 源代码
4. 说明预期结果与实际结果
5. 如果代码在本地，则找到处理程序并提出修复建议

第 5 步：修复并重新运行

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

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

如果需要更新测试本身：

• 使用 updateCollectionRequest 修复请求正文、标头或测试脚本
• 使用 updateCollectionResponse 更新预期响应

---

工作流：创建模拟服务

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

步骤 1：查找源

如果已知工作区 ID，直接调用 getWorkspace(workspaceId)。否则询问用户。

从现有集合获取： 使用工作区 ID 调用 getCollections -> 选择目标集合

从本地规范获取： 先导入：

1. 使用工作区、名称、类型和文件调用 createSpec
2. generateCollection。异步（HTTP 202）。 轮询 getGeneratedCollectionSpecs 或 getSpecCollections，等待完成。

步骤 2：检查示例

模拟服务会提供示例响应。调用 getCollection，检查请求是否包含已保存的响应。

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

1. 为每个请求调用 getCollectionRequest 获取其架构
2. 根据架构生成真实的示例响应
3. 调用 createCollectionResponse 保存示例

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

调用 getMocks，检查此集合是否已有模拟服务。如果有，则提供其 URL。只有在不存在模拟服务或用户明确要求时，才创建新的模拟服务。

步骤 4：创建模拟服务

使用以下参数调用 createMock：

• 工作区 ID
• ownerId-collectionId 格式的集合 UID（来自 getCollection 响应的 uid 字段）
• 环境 ID（如适用）
• 名称：<api-name> Mock
• 私有：false（或按需设为 true）

步骤 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.

步骤 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';

步骤 7：发布（可选）

如果用户需要公开访问：

• 对于无需身份验证的访问（演示、黑客马拉松、公开文档），使用 publishMock
• 使用 unpublishMock 重新设为私有

---

工作流：API 文档

根据 OpenAPI 规范和 Postman 集合分析、改进并发布 API 文档。

步骤 1：查找源

按以下顺序检查 API 定义：

本地规范： 搜索 **/openapi.{json,yaml,yml}、**/swagger.{json,yaml,yml}

Postman 规范： 使用工作区 ID 调用 getAllSpecs，然后调用 getSpecDefinition 获取完整规范

Postman 集合： 调用 getCollections，然后调用 getCollection 获取完整详情

步骤 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

步骤 3：生成或改进

内容稀疏的规范： 为每个端点生成文档（摘要、参数表、请求/响应架构、示例、错误文档、身份验证要求）。

部分完整的规范： 补全缺失内容（根据命名/架构推断并添加缺失描述，生成真实示例，添加错误响应，记录身份验证和速率限制）。

步骤 4：应用更改

询问用户希望采用哪种输出方式：

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

步骤 5：同步

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

• 使用 syncCollectionWithSpec，根据规范更新集合（异步，仅支持 OpenAPI 3.0）
• 使用 syncSpecWithCollection，根据集合更改更新规范

---

工作流：API 安全审计

依据 OWASP API Security Top 10 审计 API 安全问题。适用于本地 OpenAPI 规范和 Postman 集合。

步骤 1：查找源

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

Postman 规范： 调用 getAllSpecs，然后调用 getSpecDefinition

Postman 集合： 调用 getCollections，然后调用 getCollection，包括身份验证配置。还要调用 getEnvironment，检查是否存在暴露的机密信息。

第 2 步：运行安全检查

身份验证和授权：

• 已定义安全方案（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 响应

错误处理：

• 错误响应不会泄露堆栈跟踪
• 错误架构不会暴露内部字段名称
• 已正确定义 401 和 403 响应

OWASP API Top 10：

• API1：对象级授权失效
• API2：身份验证失效
• API3：对象属性级授权失效
• API4：资源消耗不受限制
• API5：功能级授权失效
• API6：敏感业务流程访问不受限制
• API7：服务器端请求伪造
• API8：安全配置错误
• API9：库存管理不当
• API10：不安全地使用 API

第 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

第 4 步：修复

针对每项发现：

1. 用通俗的语言说明安全风险
2. 展示所需的具体规范更改
3. 经用户批准后应用修复

针对 Postman 特定问题：

• 使用 putEnvironment 正确标记机密
• 使用 updateCollectionRequest 修复身份验证配置
• 使用 updateCollectionResponse 从示例中移除敏感数据

第 5 步：重新审计

修复后重新运行，以展示改进情况。

---

错误处理

这些模式适用于所有工作流：

错误	响应
MCP 工具不可用	“Postman MCP Server 尚未配置。请设置 POSTMAN_API_KEY 环境变量并重启编辑器。”
401 Unauthorized	“你的 Postman API 密钥未通过验证。请前往 https://postman.postman.co/settings/me/api-keys 生成新密钥。”
网络超时	重试一次。请查看 https://status.postman.com 了解服务中断情况。
异步操作卡住	如果轮询 30 秒后仍无进展，请告知用户，并建议直接检查 Postman 应用。
未找到集合	“没有与该名称匹配的集合。请尝试在整个工作区中发现 API。”
集合为空	“此集合没有请求。请在 Postman 中添加端点，或从本地规范同步。”
规范无效	报告包含行号的具体解析错误。提供修复常见 YAML/JSON 语法问题的选项。
计划限制	“某些功能可能需要付费的 Postman 计划。所有计划均支持核心操作。”

MCP 工具参考

完整的工具目录请参阅 references/mcp-tools.md，已知限制和解决方法请参阅 references/mcp-limitations.md。