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

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

@@ -0,0 +1,141 @@
+---
+description: Set up Postman MCP Server. Authenticate via OAuth or API key, verify connection, select workspace.
+allowed-tools: mcp__postman__authenticate, mcp__postman__complete_authentication, mcp__postman__getAuthenticatedUser, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getAllSpecs
+---
+
+# First-Run Configuration
+
+Walk the user through Postman setup for Claude Code. Validate everything works before they use other commands.
+
+## Workflow
+
+### Step 1: Check MCP Connection
+
+Verify the Postman MCP Server is available by calling `getAuthenticatedUser`.
+
+**If it works:** Skip to Step 4 (workspace verification).
+
+**If it fails:** Check whether `mcp__postman__authenticate` is available.
+- Available → offer the user a choice: **OAuth (recommended)** or **API key**. Default to OAuth unless they ask for API key.
+- Not available → the MCP server isn't loaded. Show the "MCP tools not available" error below and stop.
+
+### Step 2: OAuth Authentication (Recommended)
+
+Present:
+```
+Let's connect your Postman account via OAuth — no key copying required.
+
+I'll generate an authorization URL. Open it in your browser, sign in, and paste the callback URL back here.
+```
+
+1. Call `mcp__postman__authenticate` — it returns an authorization URL.
+2. Show the URL:
+   ```
+   Open this URL in your browser:
+   <authorization URL>
+
+   After you authorize, your browser will redirect to a localhost URL.
+   The page may not load — that's expected. Copy the full URL from the address bar and paste it here.
+   ```
+3. Wait for the user to paste the callback URL.
+4. Call `mcp__postman__complete_authentication` with the pasted URL as `callback_url`.
+5. The MCP server may restart after saving the OAuth token, temporarily dropping the connection. This is expected.
+   - Wait a few seconds, then retry `getAuthenticatedUser` up to 3 times with short pauses between attempts.
+   - If tools become unavailable (server disconnected), tell the user:
+     ```
+     The MCP server is restarting after saving your credentials — this is normal.
+     Give it a moment and I'll retry the connection...
+     ```
+   - If tools are still unavailable after retries:
+     ```
+     The server hasn't reconnected yet. Restart Claude Code and run /postman:setup again.
+     Your OAuth token is already saved — you won't need to re-authorize.
+     ```
+6. Once `getAuthenticatedUser` succeeds, proceed to Step 4.
+
+**If OAuth fails:** "OAuth didn't complete. You can try again or use an API key instead — just say 'use API key'." → offer Step 3.
+
+### Step 3: API Key Authentication (Alternative)
+
+Present:
+```
+Let's set up Postman using an API key.
+
+1. Go to: https://go.postman.co/settings/me/api-keys
+2. Click "Generate API Key"
+3. Name it "Claude Code"
+4. Copy the key (starts with PMAK-)
+
+Then set it as an environment variable:
+
+  export POSTMAN_API_KEY=PMAK-your-key-here
+
+Add it to your shell profile (~/.zshrc or ~/.bashrc) to persist across sessions.
+When done, let me know and I'll verify the connection.
+```
+
+Wait for the user to confirm they've set the key. Then verify with `getAuthenticatedUser`.
+
+**If 401:** "API key was rejected. Check for extra spaces or generate a new one at https://go.postman.co/settings/me/api-keys"
+
+**If timeout:** "Can't reach the Postman MCP Server. Check your network and https://status.postman.com"
+
+### Step 4: Workspace Verification
+
+After successful connection (either auth method):
+
+1. Call `getWorkspaces` to list workspaces.
+2. Call `getCollections` with the first workspace ID to count collections.
+3. Call `getAllSpecs` with the workspace ID to count specs.
+
+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.
+```
+
+If workspace is empty:
+```
+Your workspace is empty. You can:
+  /postman:sync     — Push a local OpenAPI spec to Postman
+  /postman:search   — Search for APIs across your org's resources or the public Postman network
+```
+
+### Step 5: Suggest First Command
+
+Based on what the user has:
+
+**Has collections:**
+```
+Try one of these:
+  /postman:search   — Find APIs across your workspace
+  /postman:test     — Run collection tests
+```
+
+**Has specs but no collections:**
+```
+Try this:
+  /postman:sync — Generate a collection from one of your specs
+```
+
+**Empty workspace:**
+```
+Try this:
+  /postman:sync — Import an OpenAPI spec from your project
+```
+
+## Error Handling
+
+- **MCP tools not available:** "The Postman MCP Server isn't loaded. Make sure the plugin is installed and restart Claude Code."
+- **OAuth callback invalid:** "That URL doesn't look right — make sure you copied the full address bar URL including `?code=` and `&state=`."
+- **OAuth flow expired:** "The authorization URL has expired. Run `/postman:setup` again to get a fresh one."
+- **MCP server disconnected after OAuth:** The server restarts after saving credentials. Retry `getAuthenticatedUser` up to 3 times. If still unavailable, tell the user to restart Claude Code — the token is saved, no re-auth needed.
+- **API key not set:** Walk through Step 3 above.
+- **401 Unauthorized:** "Authentication failed. Try `/postman:setup` to re-authenticate via OAuth, or generate a new API key at https://go.postman.co/settings/me/api-keys"
+- **Network timeout:** "Can't reach the Postman MCP Server. Check your network and https://status.postman.com for outages."
+- **Plan limitations:** "Some features (team workspaces, monitors) require a paid Postman plan. Core commands work on all plans."

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

@@ -0,0 +1,85 @@
+---
+description: Sync Postman collections with your API code. Create collections from specs, push updates, keep everything in sync.
+allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__createSpec, mcp__postman__updateSpecFile, mcp__postman__generateCollection, mcp__postman__getAsyncSpecTaskStatus, mcp__postman__getGeneratedCollectionSpecs, mcp__postman__syncCollectionWithSpec, mcp__postman__syncSpecWithCollection, mcp__postman__getCollectionUpdatesTasks, mcp__postman__createEnvironment, mcp__postman__createCollectionRequest, mcp__postman__updateCollectionRequest, mcp__postman__createCollectionFolder, mcp__postman__createCollectionResponse
+---
+
+# Sync Collections
+
+Keep Postman collections in sync with your API code. Create new collections from OpenAPI specs, update existing ones when specs change, or push manual endpoint changes.
+
+## 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: Understand What Changed
+
+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?
+
+### Step 2: Resolve Workspace
+
+Call `getWorkspaces` to get the user's workspace ID. If multiple workspaces exist, ask which to use.
+
+### Step 3: Find or Create the Collection
+
+**If updating an existing collection:**
+1. Call `getCollections` with the `workspace` parameter to list collections
+2. Match by name or ask the user which collection
+3. Call `getCollection` to get current state
+
+**If creating a new collection from a spec:**
+1. Read the local OpenAPI spec
+2. Call `createSpec` with:
+   - `workspaceId`: the workspace ID
+   - `name`: from the spec's `info.title`
+   - `type`: one of `OPENAPI:2.0`, `OPENAPI:3.0`, `OPENAPI:3.1`, `ASYNCAPI:2.0`
+   - `files`: array of `{path, content}` objects
+3. Call `generateCollection` from the spec. **This is async (HTTP 202).** Poll `getAsyncSpecTaskStatus` or `getGeneratedCollectionSpecs` until complete, with increasing waits between polls (2s, 4s, 8s). Don't narrate intermediate poll results — report only the final outcome.
+4. Call `createEnvironment` with variables extracted from the spec:
+   - `base_url` from `servers[0].url`
+   - Auth variables from `securitySchemes` (mark as `secret`)
+   - Common path parameters
+
+### Step 4: Sync
+
+**Spec to Collection (most common):**
+1. Call `createSpec` or `updateSpecFile` with local spec content
+2. Call `syncCollectionWithSpec` to update the collection. **Async (HTTP 202).** Poll `getCollectionUpdatesTasks` for completion with increasing waits between polls.
+3. **Note:** `syncCollectionWithSpec` only supports OpenAPI 3.0. For Swagger 2.0 or OpenAPI 3.1, use `updateSpecFile` and regenerate the collection.
+4. Report what changed
+
+**Collection to Spec (reverse sync):**
+1. Call `syncSpecWithCollection` to update the spec from collection changes
+2. Write the updated spec back to the local file
+
+**Manual updates (no spec):**
+For individual endpoint changes:
+1. `createCollectionRequest` to add new endpoints
+2. `updateCollectionRequest` to modify existing ones
+3. `createCollectionFolder` to organize by resource
+4. `createCollectionResponse` to add example responses
+
+### Step 5: Confirm
+
+```
+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
+```
+
+## Error Handling
+
+- **MCP not configured:** "Run `/postman:setup` to configure the Postman MCP Server."
+- **MCP timeout:** Retry once. If `generateCollection` or `syncCollectionWithSpec` times out, the spec may be too large. Suggest breaking it into smaller specs by domain.
+- **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 specific parse errors with line numbers. Offer to fix common YAML/JSON syntax issues.
+- **Async operation stuck:** If polling shows no progress after 30 seconds, inform the user and suggest checking the Postman app directly.
+- **Plan limitations:** "Workspace creation may be limited on free plans. Using your default workspace instead."

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

@@ -0,0 +1,84 @@
+---
+description: Run Postman collection tests, analyze results, diagnose failures, and suggest fixes.
+allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__runCollection, mcp__postman__getEnvironments, mcp__postman__getCollectionRequest, mcp__postman__getCollectionResponse, mcp__postman__updateCollectionRequest, mcp__postman__updateCollectionResponse
+---
+
+# Run Collection Tests
+
+Execute Postman collection tests directly from Claude Code. Analyze results, diagnose failures, and suggest code fixes.
+
+## 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 Collection
+
+1. Call `getWorkspaces` to find the target workspace
+2. Call `getCollections` with the `workspace` parameter. Use the `name` filter if the user specified a collection.
+3. If the user provides a collection ID directly, skip to Step 2.
+
+### Step 2: Run Tests
+
+Call `runCollection` with the collection UID in `OWNER_ID-UUID` format. Get the UID from the `getCollection` response's `uid` field.
+
+If the collection uses environment variables:
+1. Call `getEnvironments` to list available environments
+2. Ask which environment to use (or detect from naming convention)
+3. Pass the environment ID to `runCollection`
+
+### Step 3: Parse Results
+
+Present results clearly:
+
+```
+Test Results: Pet Store API
+  Requests:  15 executed
+  Passed:    12 (80%)
+  Failed:    3
+  Avg time:  245ms
+
+  Failures:
+  1. POST /users → "Status code is 201" → Got 400
+     Request: createUser
+     Folder: User Management
+
+  2. GET /users/{id} → "Response has email field" → Missing
+     Request: getUser
+     Folder: User Management
+
+  3. DELETE /users/{id} → "Status code is 204" → Got 403
+     Request: deleteUser
+     Folder: User Management
+```
+
+### Step 4: Diagnose Failures
+
+For each failure:
+1. Call `getCollectionRequest` to see the full request definition
+2. Call `getCollectionResponse` to see expected responses
+3. Check if the API source code is in the current project
+4. Explain what the test expected vs what happened
+5. If code is local, find the handler and suggest the fix
+
+### Step 5: Fix and Re-run
+
+After fixing code:
+1. Offer to re-run: "Tests fixed. Want me to run the collection again?"
+2. Call `runCollection` again
+3. Show before/after comparison
+
+### Step 6: Update Collection (if needed)
+
+If the tests themselves need updating (not the API):
+- Call `updateCollectionRequest` to fix request bodies, headers, or test scripts
+- Call `updateCollectionResponse` to update expected responses
+
+## Error Handling
+
+- **MCP not configured:** "Run `/postman:setup` to configure the Postman MCP Server."
+- **Collection not found:** "No collection matching that name. Run `/postman:search` to find available collections, or `/postman:sync` to create one."
+- **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. For large collections, suggest running a single folder to narrow the test run.
+- **Plan limitations:** "Collection runs may require a Postman Basic plan or higher for increased limits."