mirror of
https://github.com/Postman-Devrel/postman-claude-code-plugin.git
synced 2026-04-16 10:29:58 +00:00
3f03fc19d3
Replace monolithic postman.md with focused, namespaced commands: - setup: guided API key config and workspace verification - sync: create/update collections from OpenAPI specs - codegen: generate typed client code from collections - search: discover APIs across private workspaces - test: run collection tests and diagnose failures - mock: create mock servers with auto-generated examples - docs: analyze, improve, and publish API documentation - security: OWASP API Top 10 security audit Each command has proper frontmatter, error handling with actionable next steps, and handles known MCP limitations (async polling, private search, etc.). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
86 lines
3.8 KiB
Markdown
86 lines
3.8 KiB
Markdown
---
|
|
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__*
|
|
---
|
|
|
|
# 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.
|
|
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.
|
|
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://postman.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."
|