@postman/postman-plugin 0.1.1-rc.0 → 0.1.2-rc.0

package/skills/flows/reference/flow_cli_flags.md

@@ -0,0 +1,111 @@
+# Flows CLI Flags
+
+Captured from `postman flows <subcommand> -h` and verified on CLI
+**1.58.0**. Live `-h` output is authoritative over this file — re-run it if
+the installed CLI is newer, since `flows` is an actively changing surface.
+
+Every subcommand below also accepts `--verbose`, `--debug`, and `--json`.
+
+**Short flags are not stable across subcommands.** `-f` is `--filter` on
+`list`, `--input-file` on `trigger` and `run`, and `--flow` on `list-runs`;
+`-r` is `--result` on `trigger`, `--range` on `list-runs`, and `--run-id` on
+`get-run`; `-t` is `--timeout` on `deploy` but `--trigger` on `update`. Read
+the table for the subcommand you are actually invoking, and prefer the long
+form when composing a command from more than one table.
+
+## `flows list`
+
+| Flag | Notes |
+| --- | --- |
+| `-w, --workspace <workspaceId>` | **Required** — the CLI exits 1 with `required option '-w, --workspace <workspaceId>' not specified`. |
+| `-f, --filter <pattern>` | Name prefix **or** regex, e.g. `--filter "^Test.*"`. |
+| `-s, --sort <criteria>` | `name` or `updated`. Default `updated`. |
+| `-p, --paginate` | Page through all flows. |
+
+## `flows trigger <flowId>`
+
+| Flag | Notes |
+| --- | --- |
+| `-i, --input <key=value>` | Repeatable. Trigger payload values. |
+| `-f, --input-file <path.json>` | Repeatable. Payload from JSON files. Combines with `-i`, which overrides. |
+| `-q, --query <key=value>` | Repeatable. Query parameters. |
+| `--headers <key=value>` | Repeatable. Custom headers. |
+| `-s, --scenario <name>` | Named scenario from the flow definition; builds payload, headers and query. **`--headers` and `--query` override it.** |
+| `-n, --dry-run` | Print request URL + payload, send nothing. |
+| `--show-secrets` | Unmask auth tokens in dry-run output. Masked by default. |
+| `-r, --result` | Print only the response body. |
+
+## `flows deploy <flowId>`
+
+| Flag | Notes |
+| --- | --- |
+| `-p, --path <path>` | **Required** — `-h` carries no `(required)` annotation, but omitting it exits 1. A suffix appended to a generated base URL, e.g. `/my-trigger`. |
+| `-t, --timeout <timeout>` | HTTP session timeout, **5000ms–60000ms**, default `"10000ms"`. Value carries units — `5000ms`, not `5000`. |
+| `-a, --auth` | Boolean switch. Enables auth on the trigger. Default off. |
+
+Note the asymmetry with `update`: here `--auth` is a bare flag; on `update` it
+takes `on|off`.
+
+## `flows update <flowId>`
+
+| Flag | Notes |
+| --- | --- |
+| `-t, --trigger <on\|off>` | Enable/disable the trigger. Takes an explicit value. |
+| `-a, --auth <on\|off>` | Enable/disable authentication on the trigger. Takes an explicit value. |
+
+**At least one of the two is required**: a bare `flows update <flowId>` exits 1
+with `Invalid command parameters: trigger: At least one option is required:
+--trigger or --auth`.
+
+Both are mutating and confirmation-gated. `--auth off` strips authentication
+from a live trigger — never run it as a convenience.
+
+## `flows run <path>`
+
+Runs a flow **file** locally — documented as available on Postman **Enterprise**
+plans, and requires `postman login`. Inputs work as on `trigger`; the rest is
+execution and reporting. Takes the path positionally; a bad path fails with
+`Error: Flow file not found: <path>` and exit 1.
+
+| Flag | Notes |
+| --- | --- |
+| `-i, --input <key=value>` | Repeatable. |
+| `-f, --input-file <path.json>` | Repeatable. |
+| `-s, --scenario <name>` | Pre-built scenario as inputs; `-i`/`-f` override values. |
+| `-e, --environment <path>` | Postman environment file, JSON or YAML. |
+| `--working-dir <path>` | Working directory for the run. |
+| `--workspace <workspaceId>` | **Required for flows containing connector blocks.** |
+| `--output <format>` | Save execution result to file. `json` only. |
+| `--reporters <format>` | Save a test results report. `html` only. |
+| `-x, --suppress-exit-code` | Overrides the run's exit code. Defeats CI gating. |
+| `--verbose` | Per-request detail: method, URL, assertions. |
+| `--no-truncate` | Full output, no truncated long values. |
+| `--no-report-events` | Don't send analytics. `--report-events` exists for compatibility; analytics are on by default. |
+
+### BETA: dataset iteration
+
+Runs the flow once per row of a dataset view. All three are marked `[BETA]` in
+the CLI's own help — confirm against live `-h` before relying on them.
+
+| Flag | Notes |
+| --- | --- |
+| `--iteration-data-dataset <pathOrId>` | Local `.dataset.yaml` path or a cloud dataset id (cloud requires login). **Requires `--iteration-data-view`.** |
+| `--iteration-data-view <nameOrId>` | The view within that dataset whose rows drive the run. |
+| `-m, --map-column <input=column>` | Repeatable. Binds a flow input to a dataset column. Inputs whose name already matches a column bind automatically, so only map the mismatches. |
+| `--no-insecure-file-read` | Blocks reading dataset files outside the working directory. |
+
+## `flows list-runs`
+
+| Flag | Notes |
+| --- | --- |
+| `-w, --workspace <workspaceId>` | **Required**, same as on `list`. |
+| `-f, --flow <flowId>` | Filter sessions to one flow. |
+| `-r, --range <range>` | Time range, e.g. `30m`, `2h`, `3d`. **Default `1h`** — widen it before concluding a run is missing. |
+
+## `flows get-run`
+
+| Flag | Notes |
+| --- | --- |
+| `-r, --run-id <runId>` | **Required.** The id `trigger` or `list-runs` reported. Shapes vary across Postman's own material (`session-abc123`, `main/1a123ab1`) — pass it verbatim rather than reformatting. |
+| `-l, --logs` | Detailed event log. Off by default. |
+| `--filter <blockId>` | Repeatable. Matches a block ID **prefix**, not an exact id. |

package/skills/performance-testing/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: performance-testing
+description: Load-tests a collection with concurrent virtual users, a chosen load profile, and pass/fail thresholds on latency or error rate — run locally or on Postman's cloud runners. Use when the user asks to "load test this API," "run a performance test," "check how this holds up under load," or "benchmark this collection." Covers `postman performance run`. This generates real traffic against a real target — confirm the target and scale before running, the same way any action with effects outside this session gets confirmed.
+---
+
+# Performance Testing
+
+## Overview
+
+`performance run <collectionId>` is not `collection run` with more
+iterations — it's a dedicated load-test mode: many virtual users hitting the
+collection concurrently for a set duration, shaped by a load profile, scored
+against thresholds you define, on infrastructure you choose. The collection
+under test is authored the normal way — see the `collection-schema-v3` skill
+if it needs edits before the load test is meaningful (e.g. an assertion
+that would fail every VU's request identically).
+
+## Core knowledge
+
+- **Load profile is what you're actually testing.** `fixed` holds steady
+  concurrency (does this hold up at N users, sustained); `ramp-up` increases
+  gradually (where does it start to degrade); `spike` bursts suddenly (does
+  a sudden surge break it); `peak` sustains near-maximum load (does it
+  survive staying there). Pick based on the failure mode being probed, not
+  by default.
+- **`--runner` chooses where load originates.** `local` runs from the
+  current machine/CI runner — bounded by its own resources, fine for
+  internal or low-scale targets. `postman-cloud` runs from Postman's
+  infrastructure — needed for realistic external-scale load, or once local
+  resources would cap the achievable VU count. `postman-cloud-static-ip`
+  is the same, from a static-IP range — needed when the target allowlists
+  by IP.
+- **`--pass-if "less_than(p95, 500)"` turns a load test into a gate.**
+  Metrics: `avg`, `p90`, `p95`, `p99`, `error_rate`, `rps`. Checked after the
+  run completes, not enforced live — a bad configuration still generates its
+  full load before the gate fails.
+- **`--use-mock` points the test at a mock instead of a real backend** — for
+  load-testing collection/script logic itself, or to baseline mock-only
+  latency and isolate app/network slowness from what the mock adds.
+- **`--setup-collection`/`--teardown-collection`** (cloud runner only) run
+  once before/after the whole test — for provisioning or cleanup, not
+  per-iteration setup.
+- **`--dataset-id`/`--dataset-view-id`** drive iteration data from a Postman
+  Dataset instead of a flat `--data-file`; `--dataset-distribution` controls
+  whether rows are spread round-robin, fixed, or randomly across VUs.
+
+## Critical Rules
+
+1. **Running this against a real, non-mock backend generates real load with
+   real consequences — confirm the target, VU count, and duration with the
+   user before running,** the same way any action with effects outside this
+   session gets confirmed. Default to a low `--vu-count` and short
+   `--duration` for a first run against anything live, or point it at a mock
+   (`--use-mock`) when the goal is testing the collection, not the backend.
+2. **A `--pass-if` gate doesn't stop the load early.** The full VU count and
+   duration run regardless of whether the threshold will ultimately pass —
+   plan for that cost, don't assume a failing gate means less traffic was
+   sent.
+3. **Cloud runners come from Postman's IP ranges.** Before assuming a
+   `postman-cloud` run will reach a target, check whether it's IP-allowlisted
+   — use `postman-cloud-static-ip` if so, rather than discovering the
+   mismatch as a wall of connection failures.
+
+## Verification
+
+State the actual metrics the run produced (p95, error rate, rps — whatever
+the `--pass-if` checked, plus the ones it didn't) and whether the gate
+passed, not just that the run completed. State which runner actually
+executed it (`local`/`postman-cloud`/`postman-cloud-static-ip`) — that
+determines whether the numbers reflect the target's real-world reachability
+or only local-network conditions.

package/skills/postman-mcp-server/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: postman-mcp-server
+description: Postman concepts and MCP tool guidance. Loaded when working with Postman MCP tools to make better decisions about tool selection and workarounds.
+user-invocable: false
+---
+
+# Postman Knowledge
+
+Reference for Postman concepts and MCP tool selection. Use this context when working with Postman MCP tools to make better decisions.
+
+See `references/setup.md` for how to to setup postman mcp server and auth.
+
+## Core Concepts
+
+- **Collection:** A group of API requests organized in folders. The primary unit of work in Postman. Contains requests, examples, tests, and documentation.
+- **Environment:** Key-value pairs (variables) scoped to a context (dev, staging, prod). Used to swap base URLs, auth tokens, and config without changing requests.
+- **Workspace:** Container for collections, environments, and specs. Can be personal, team, or public.
+- **Spec (Spec Hub):** An OpenAPI or AsyncAPI definition stored in Postman. Can generate collections and stay synced.
+- **Request:** A single API call definition (method, URL, headers, body, tests).
+- **Response:** A saved example response for a request. Used by mock servers and documentation.
+- **Folder:** A grouping within a collection, typically by resource (e.g., "Users", "Orders").
+- **Tags:** Labels on collections for categorization and search.
+- **Monitor:** A scheduled collection runner that checks API health.
+- **Mock Server:** A fake API that serves example responses from a collection.
+
+## Decision Guide
+
+| Goal | Approach |
+|------|----------|
+| Push code changes to Postman | Create/update spec in Spec Hub, then sync to collection |
+| Consume a Postman API | Read collection + generate client code |
+| Find an API | Use `searchPostmanElements`, then drill into details |
+| Test an API | Run collection with `runCollection` |
+| Create a fake API for frontend | Create mock server from collection with examples |
+| Document an API | Analyze collection completeness, fill gaps, optionally publish |
+| Audit API security | Run security checks against spec or collection |
+| Learn how to use a Postman feature | Search Postman docs with `searchLearningCenter` (Full mode) |
+
+## MCP Tool Selection
+
+**Workspace operations:** `getWorkspaces`, `getWorkspace`, `createWorkspace`
+**Collection CRUD:** `getCollections`, `getCollection`, `createCollection`, `putCollection`, `patchCollection`, `deleteCollection`
+**Request/Response:** `getCollectionRequest`, `createCollectionRequest`, `updateCollectionRequest`, `getCollectionResponse`, `createCollectionResponse`, `updateCollectionResponse`
+**Folder management:** `getCollectionFolder`, `createCollectionFolder`, `updateCollectionFolder`
+**Spec Hub:** `getAllSpecs`, `getSpec`, `createSpec`, `getSpecDefinition`, `updateSpecFile`, `getSpecFiles`
+**Sync:** `generateCollection`, `syncCollectionWithSpec`, `syncSpecWithCollection`
+**Environments:** `getEnvironments`, `getEnvironment`, `createEnvironment`, `putEnvironment`
+**Mocks:** `getMocks`, `getMock`, `createMock`, `publishMock`, `unpublishMock`
+**Tests:** `runCollection`
+**Docs:** `publishDocumentation`, `unpublishDocumentation`
+**Search:** `searchPostmanElements` , `getTaggedEntities`
+**Learning Center:** `searchLearningCenter` (Full mode only — searches Postman product docs for how-to guidance)
+**User:** `getAuthenticatedUser`
+
+See `references/mcp-limitations.md` for known limitations and workarounds.
+
+## Workflows
+
+Each reference below is a full MCP-tool workflow for one goal — the tool
+call sequence, what to present at each step, and error handling. Reach for
+one once the Decision Guide above has picked a goal; they assume MCP tools
+only, no `postman` CLI.
+
+- `references/setup.md` — first-run auth (OAuth or API key) and workspace verification.
+- `references/search.md` — discover APIs across workspaces with `searchPostmanElements`.
+- `references/sync.md` — create/update collections from specs, or sync a spec from collection changes.
+- `references/mock.md` — create a mock server from a collection or spec.
+- `references/test.md` — run collection tests and diagnose failures.
+- `references/docs.md` — generate, improve, and publish API documentation.
+- `references/security.md` — audit a spec or collection against the OWASP API Top 10.
+- `references/learn.md` — search the Postman Learning Center for how-to guidance.

package/skills/postman-mcp-server/references/docs.md

@@ -0,0 +1,88 @@
+---
+description: Generate, improve, and publish API documentation from Postman collections.
+allowed-tools: Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getAllSpecs, mcp__postman__getSpecDefinition, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__updateCollectionRequest, mcp__postman__publishDocumentation, mcp__postman__unpublishDocumentation, mcp__postman__syncCollectionWithSpec, mcp__postman__syncSpecWithCollection, mcp__postman__getCollectionUpdatesTasks
+---
+
+# API Documentation
+
+Analyze, improve, and publish API documentation from OpenAPI specs and Postman collections.
+
+## Prerequisites
+
+The Postman MCP Server must be connected for Postman operations. Local spec analysis works without MCP. If needed, tell the user: "Run `/postman:setup` to configure the Postman MCP Server."
+
+## Workflow
+
+### Step 1: Find the Source
+
+Call `getWorkspaces` to get the user's workspace ID. If multiple workspaces exist, ask which to use.
+
+Check for API definitions in this order:
+
+**Local specs:**
+- Search for `**/openapi.{json,yaml,yml}`, `**/swagger.{json,yaml,yml}`
+
+**Postman specs:**
+- Call `getAllSpecs` with the workspace ID to find specs in Postman
+- Call `getSpecDefinition` to pull the full spec
+
+**Postman collections:**
+- Call `getCollections` with the `workspace` parameter
+- Call `getCollection` for full detail
+
+### Step 2: Analyze Documentation Completeness
+
+Read the spec/collection and assess:
+
+```
+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
+```
+
+### Step 3: Generate or Improve
+
+**Sparse spec:** Generate documentation for each endpoint:
+- Operation summary and description
+- Parameter table (name, type, required, description)
+- Request body schema with examples
+- Response schemas with examples for each status code
+- Error response documentation
+- Authentication requirements per endpoint
+
+**Partial spec:** Fill the gaps:
+- Add missing descriptions (infer from naming and schemas)
+- Generate realistic examples from schemas
+- Add error responses
+- Document authentication and rate limits
+
+### Step 4: Apply Changes
+
+Ask the user which output they want:
+
+1. **Update the spec file** - Write improved docs back into the OpenAPI spec
+2. **Update in Postman** - Use `updateCollectionRequest` to add descriptions and examples to each request
+3. **Publish public docs** - Call `publishDocumentation` with:
+   - `collectionId`: the collection's unique ID
+   - `customColor` and `customization` for branding
+   - Returns a public URL for the docs
+   - To unpublish later, call `unpublishDocumentation` with the collection ID
+4. **Generate markdown** - Create a `docs/api-reference.md` file for the project
+
+### Step 5: Sync Spec and Collection
+
+If both a spec and collection exist, keep them in sync:
+- Call `syncCollectionWithSpec` to update collection from spec. **Async (HTTP 202).** Poll `getCollectionUpdatesTasks` for completion with increasing waits between polls. Only supports OpenAPI 3.0.
+- Or call `syncSpecWithCollection` to update spec from collection changes.
+
+## Error Handling
+
+- **MCP not configured:** Local markdown docs can be generated without MCP. For Postman publishing: "Run `/postman:setup` to configure the Postman MCP Server."
+- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys and run `/postman:setup`."
+- **Invalid spec:** Report parse errors and offer to fix common YAML/JSON syntax issues.
+- **Plan limitations:** "Publishing documentation may require a paid Postman plan. Check https://www.postman.com/pricing/"
+- **Too many results:** Ask the user to specify a collection by name.

package/skills/postman-mcp-server/references/learn.md

@@ -0,0 +1,73 @@
+---
+description: Search the Postman Learning Center for how-to guidance, feature explanations, and suggested workflows. Use for "how do I..." questions about the Postman product.
+allowed-tools: Read, mcp__postman__searchLearningCenter, mcp__postman__getEnabledTools
+---
+
+# Learn Postman
+
+Answer "how do I..." questions about the Postman product by searching the official Postman Learning Center (https://learning.postman.com). Explain features, walk through workflows, and cite authoritative sources.
+
+Use this to learn *about Postman itself* — not to search the user's own collections, workspaces, or specs (that's `/postman:search`).
+
+## Prerequisites
+
+This command uses `searchLearningCenter`, which the Postman MCP Server exposes only in **Full mode**.
+
+The mode is fixed by the endpoint in each route's MCP config, not by the environment. A route pinned to `https://mcp.postman.com/mcp` has the tool; a route pinned to `https://mcp.postman.com/minimal` does not. Read it off the route's own MCP config rather than inferring it from the agent's name — which endpoint an agent gets is a per-route product decision, and new routes are added. **`POSTMAN_MCP_MODE` is not read on any route** — never tell the user to set or unset it to change the tool set.
+
+- If MCP tools aren't available at all, tell the user: "Run `/postman:setup` to configure the Postman MCP Server."
+- If `searchLearningCenter` is missing, call `getEnabledTools` to confirm the active tool set, then split on which endpoint the route is pinned to. On a `/minimal` route it is absent by design and the user cannot change it from the client: say the Learning Center tool isn't part of that route's tool set and point them at https://learning.postman.com to search directly. On a `/mcp` route its absence is not a mode problem — the server isn't connected as configured: "Run `/postman:setup` to configure the Postman MCP Server."
+
+Do not answer a "how do I..." question from memory when the tool is unavailable. Cite only URLs the tool returned, or send the user to the Learning Center.
+
+## Workflow
+
+### Step 1: Search
+
+Call `searchLearningCenter` with a focused `query` derived from the user's question. Prefer the product vocabulary from `postman-mcp-server` (mock server, environment, monitor, collection variable, etc.) over the user's exact phrasing.
+
+- Turn a broad request into a specific query — "how to create a mock server", "write a test script", "set a collection variable", "schedule a monitor".
+- If results are thin or off-target, refine: try a different feature term, split a multi-part question into separate searches, or broaden a narrow query.
+
+### Step 2: Synthesize
+
+Read the returned passages and compose a direct answer to the user's question. Do not just dump raw results.
+
+- Lead with the answer or the concrete steps.
+- Keep steps in the order the user would perform them.
+- If the docs reveal a better or officially recommended workflow than what the user asked, surface it.
+- Always cite the source URLs the tool returns so the user can read more.
+
+### Step 3: Connect to the Plugin
+
+When a workflow maps to a plugin command, point the user there so they can act immediately:
+
+- Creating/updating collections from a spec → `/postman:sync`
+- Finding APIs in their org or the public network → `/postman:search`
+- Running collection tests → `/postman:test`
+- Creating mock servers → `/postman:mock`
+- Generating or publishing docs → `/postman:docs`
+- Security auditing → `/postman:security`
+
+## Output
+
+```
+To create a mock server in Postman:
+
+  1. Open the collection you want to mock (it needs saved example responses).
+  2. Select the collection → "Mock collection".
+  3. Name the mock, pick an environment, and choose visibility.
+  4. Postman returns a mock URL that serves your examples.
+
+  Mock servers read from saved examples, so add examples first if you
+  have none — the plugin can do this for you via /postman:mock.
+
+  Source: https://learning.postman.com/docs/design-apis/mock-apis/set-up-mock-servers/
+```
+
+## Error Handling
+
+- **MCP not configured:** "Run `/postman:setup` to configure the Postman MCP Server."
+- **`searchLearningCenter` unavailable:** Confirm with `getEnabledTools`. Expected on any route pinned to the `minimal` endpoint — say the tool isn't in that route's tool set and point the user at https://learning.postman.com. On a `/mcp` route: "Run `/postman:setup` to configure the Postman MCP Server."
+- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys and run `/postman:setup`."
+- **No results:** "Nothing matched in the Learning Center. Try rephrasing with the Postman feature name, or ask about a more specific step."

package/skills/postman-mcp-server/references/mcp-limitations.md

@@ -0,0 +1,38 @@
+# Known MCP Limitations
+
+These limitations are documented so they are handled correctly in all commands and workflows.
+
+## generateCollection is Async
+
+`generateCollection` returns HTTP 202 (accepted), not the collection directly.
+
+**Workaround:** Poll `getGeneratedCollectionSpecs` or `getSpecCollections` for completion. Note: `getAsyncSpecTaskStatus` may return 403 on some plans; use the alternatives.
+
+## syncCollectionWithSpec is Async and OpenAPI 3.0 Only
+
+`syncCollectionWithSpec` returns HTTP 202 and only supports OpenAPI 3.0 specifications.
+
+**Workaround for async:** Poll `getCollectionUpdatesTasks` for completion.
+
+**Workaround for non-3.0 specs:** For Swagger 2.0 or OpenAPI 3.1 specs, use `updateSpecFile` to update the spec and regenerate the collection with `generateCollection`.
+
+## createCollection Cannot Nest Folders
+
+`createCollection` creates a flat collection. You cannot nest folders in a single call.
+
+**Workaround:** Decompose the operation:
+1. `createCollection` to create the collection
+2. `createCollectionFolder` to add folders
+3. `createCollectionRequest` to add requests to folders
+
+## putCollection Auth Enum Lacks "noauth"
+
+The `putCollection` auth type enum does not include "noauth" as a valid value.
+
+**Workaround:** Endpoints that need no auth should inherit from collection-level settings or use a different auth type as a placeholder.
+
+## createSpec Impractical for Large Specs
+
+`createSpec` struggles with specs larger than ~50KB due to request size limits.
+
+**Workaround:** For large APIs, parse the spec locally and create collection items directly using `createCollection` + `createCollectionFolder` + `createCollectionRequest` + `createCollectionResponse`.

package/skills/postman-mcp-server/references/mock.md

@@ -0,0 +1,101 @@
+---
+description: Create Postman mock servers for frontend development. Generates missing examples, provides integration config.
+allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__getCollectionRequest, mcp__postman__createCollectionResponse, mcp__postman__createSpec, mcp__postman__generateCollection, mcp__postman__getGeneratedCollectionSpecs, mcp__postman__getSpecCollections, mcp__postman__getAsyncSpecTaskStatus, mcp__postman__getMocks, mcp__postman__getMock, mcp__postman__createMock, mcp__postman__publishMock, mcp__postman__unpublishMock
+---
+
+# 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.
+
+## Prerequisites
+
+The Postman MCP Server must be connected. If MCP tools aren't available, tell the user: "Run `/postman:setup` to configure the Postman MCP Server."
+
+## Workflow
+
+### Step 1: Find the Source
+
+Call `getWorkspaces` to get the user's workspace ID. If multiple workspaces exist, ask which to use.
+
+**From existing collection:**
+- Call `getCollections` with the `workspace` parameter
+- Select the target collection
+
+**From local spec:**
+- Find OpenAPI spec in the project
+- Import it first:
+  1. Call `createSpec` with `workspaceId`, `name`, `type`, and `files`
+  2. Call `generateCollection`. **Async (HTTP 202).** Poll `getGeneratedCollectionSpecs` or `getSpecCollections` for completion, with increasing waits between polls (2s, 4s, 8s). Note: `getAsyncSpecTaskStatus` may return 403 on some plans.
+
+### Step 2: Check for Examples
+
+Mock servers serve example responses. Call `getCollection` and check if requests have saved responses.
+
+If examples are missing:
+```
+Your collection doesn't have response examples. Mock servers need
+these to know what to return.
+
+Generating realistic examples from your schemas...
+```
+
+For each request without examples:
+1. Call `getCollectionRequest` to get the schema
+2. Generate a realistic example response from the schema
+3. Call `createCollectionResponse` to save the example
+
+### Step 3: Check for Existing Mocks
+
+Before creating a new mock, call `getMocks` to check if one already exists for this collection. If found, call `getMock` to get its URL and present it. Only create a new mock if none exists or the user explicitly wants a new one.
+
+### Step 4: Create Mock Server
+
+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 user prefers)
+
+### Step 5: Present Mock URL
+
+```
+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.
+```
+
+### Step 6: Integration
+
+```
+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';
+```
+
+### Step 7: Publish (optional)
+
+If the user wants the mock publicly accessible:
+- Call `publishMock` to make it available without authentication
+- Useful for demos, hackathons, or public documentation
+- Call `unpublishMock` to make it private again
+
+## Error Handling
+
+- **MCP not configured:** "Run `/postman:setup` to configure the Postman MCP Server."
+- **No examples in collection:** Auto-generate from schemas (Step 2). If no schemas either, ask the user to provide sample responses.
+- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys and run `/postman:setup`."
+- **MCP timeout:** Retry once. If it still fails, check https://status.postman.com for outages.
+- **Plan limitations:** "Mock server creation may require a Postman Basic plan or higher for increased usage limits."

package/skills/postman-mcp-server/references/search.md

@@ -0,0 +1,83 @@
+---
+description: Discover APIs across your Postman workspaces. Ask natural language questions about available endpoints and capabilities.
+allowed-tools: Read, Glob, Grep, mcp__postman__searchPostmanElements, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getTaggedEntities, mcp__postman__getCollection, mcp__postman__getCollectionRequest, mcp__postman__getCollectionResponse, mcp__postman__getSpecDefinition
+---
+
+# Discover APIs
+
+Answer natural language questions about available APIs across Postman workspaces. Find endpoints, check response shapes, and understand what's available.
+
+## Prerequisites
+
+The Postman MCP Server must be connected. If MCP tools aren't available, tell the user: "Run `/postman:setup` to configure the Postman MCP Server."
+
+## Workflow
+
+### Step 1: Search
+
+Use the unified `searchPostmanElements` tool. It can search across various entity types like requests, collections, workspaces, specs, flows, environments and mocks. Choose `entityType`, `ownership`, and `filters` based on the user's intent.
+
+1. Call `searchPostmanElements` with the user's query. Pick the parameters from the user's intent:
+   - `entityType`: `requests` (default), `collections`, `workspaces`, `specs`, or `flows`.
+   - `ownership`: `organization` (default — your org's resources), `external` (public Postman network, third-party APIs), or `all` (both).
+   - `filters`: Optional structured `$and` expression to narrow results — e.g., restrict to the Private API Network, a workspace, or HTTP method.
+2. If results are sparse, broaden the search — widen `ownership` to `all`, drop or relax filters, or try a different `entityType`. You can also fall back to `getWorkspaces` + `getCollections` for browsing, or `getTaggedEntities` to find collections by tag.
+
+**Filter examples:**
+
+- Search only the trusted Private API Network: `ownership: organization` with `filters: {"$and":[{"privateNetwork":{"$eq":true}}]}`
+- Find a third-party public API (e.g. "Stripe API"): `ownership: external` with `filters: {"$and":[{"visibility":{"$eq":"public"}}]}`
+- Restrict to a specific workspace: `filters: {"$and":[{"workspaceId":{"$eq":"ws-abc123"}}]}`
+- GET requests only: `entityType: requests` with `filters: {"$and":[{"method":{"$eq":"GET"}}]}`
+
+### Step 2: Drill Into Results
+
+For each relevant hit:
+1. Call `getCollection` to get the overview
+2. Scan endpoint names and descriptions for relevance
+3. Call `getCollectionRequest` for the most relevant endpoints
+4. Call `getCollectionResponse` to show what data is available
+5. Call `getSpecDefinition` if a linked spec exists for richer detail
+
+### Step 3: Present
+
+Format results as a clear answer to the user's question.
+
+**When 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",
+      "role": "admin"
+    }
+```
+
+**When not found:**
+```
+No endpoint returns user emails.
+
+  Closest matches:
+  - GET /users/{id}/profile — returns name, avatar (no email)
+  - GET /users — list view doesn't include email
+
+  The email field might require a different permission scope,
+  or it may not be exposed via API yet.
+```
+
+**When multiple results:**
+List relevant collections with endpoint counts, then ask which to explore further.
+
+## Error Handling
+
+- **MCP not configured:** "Run `/postman:setup` to configure the Postman MCP Server."
+- **No results:** "Nothing matched your query. Try different keywords, broaden `ownership` to `all`, or browse the user's workspaces with `getWorkspaces` + `getCollections`."
+- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys and run `/postman:setup`."
+- **Too many results:** Ask the user to be more specific. Suggest filtering by workspace or using tags.