feat: add 8 API lifecycle commands

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>
2026-04-16 10:29:58 +00:00 · 2026-02-12 17:55:22 -08:00
parent 9bbd6ca26a
commit 3f03fc19d3
9 changed files with 758 additions and 302 deletions
--- a/commands/codegen.md
+++ b/commands/codegen.md
@@ -0,0 +1,93 @@
+---
+description: Generate typed client code from Postman collections. Reads your private APIs and writes production-ready code.
+allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__*
+---
+
+# Generate Client Code
+
+Generate typed client code from Postman collections. Reads your private API definitions and writes production-ready code that matches your project's conventions.
+
+## 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 API
+
+1. Call `getWorkspaces` to get the user's workspace ID. If multiple workspaces exist, ask which to use.
+2. Call `getCollections` with the `workspace` parameter. Use the `name` filter if the user specified an API name.
+3. If no results in private workspace, fall back to `searchPostmanElements` to search the public Postman network.
+4. If multiple matches, list them and ask which one.
+5. Call `getCollection` to get the full collection.
+6. Call `getSpecDefinition` if a linked spec exists (richer type info).
+
+### Step 2: Understand the API Shape
+
+For the target collection:
+1. Call `getCollectionFolder` for each folder to understand resource grouping
+2. Call `getCollectionRequest` for each relevant endpoint to get:
+   - HTTP method and URL
+   - Request headers and auth
+   - Request body schema
+   - Path and query parameters
+3. Call `getCollectionResponse` for each request to get:
+   - Response status codes
+   - Response body shapes (for typing)
+   - Error response formats
+4. Call `getEnvironment` to understand base URLs and variables
+5. Call `getCodeGenerationInstructions` for any Postman-specific codegen guidance
+
+### Step 3: Detect Project Language
+
+If the user doesn't specify a language, 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
+
+### Step 4: Generate Code
+
+Generate a typed client class or module 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 file path (e.g., `src/clients/<api-name>.ts`)
+
+### Step 5: Present
+
+```
+Generated: src/clients/users-api.ts
+
+  Endpoints covered:
+    GET    /users         → getUsers(filters)
+    GET    /users/{id}    → getUser(id)
+    POST   /users         → createUser(data)
+    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
+```
+
+## 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 APIs."
+- **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`."
+- **Empty collection:** "This collection has no requests. Add endpoints in Postman or use `/postman:sync` to push a spec."
+- **Language not detected:** Ask the user what language to generate.
--- a/commands/docs.md
+++ b/commands/docs.md
@@ -0,0 +1,88 @@
+---
+description: Generate, improve, and publish API documentation from Postman collections.
+allowed-tools: Read, Glob, Grep, mcp__postman__*
+---
+
+# 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. 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://postman.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.
--- a/commands/mock.md
+++ b/commands/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__*
+---
+
+# 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. 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://postman.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."
--- a/commands/postman.md
+++ b/commands/postman.md
@@ -1,302 +0,0 @@
---
-description: Manage Postman collections, environments, monitors, and APIs
---
-
-# Postman Command
-
-Execute Postman API operations to manage your API lifecycle. This command provides access to Postman collections, environments, monitors, and more through Python scripts.
-
-## Documentation Intelligence
-
-This plugin includes the **Postman Learning Center MCP** (`postman-docs`) for documentation access. Use it when:
-
- User asks "how do I..." questions about Postman features
- User needs best practices or guidance
- User asks about V12, Agent Mode, or new features
- User wants to understand a concept before executing
-
-**For "how do I" questions**: Query the `postman-docs` MCP first to get accurate documentation, then execute the operation.
-
-**For execution requests**: Run the scripts directly, but reference docs if the user seems confused.
-
-## Prerequisites
-
-Before using this command, ensure:
-1. A `.env` file exists in the `postman-slash-command/` directory with `POSTMAN_API_KEY` set
-2. Python 3 is available
-3. `curl` is installed (usually pre-installed on macOS and Linux)
-4. Optional: `python-dotenv` for easier .env loading (has fallback if not available)
-
-If the user hasn't set up their environment yet, guide them through:
-```bash
-cd postman-slash-command
-cp .env.example .env
-# Edit .env and add POSTMAN_API_KEY=PMAK-your-key-here
-```
-
-## Available Operations
-
-### Discovery & Listing
-
-**List all resources:**
-```bash
-python postman-slash-command/scripts/list_collections.py --all
-```
-
-**List collections only:**
-```bash
-python postman-slash-command/scripts/list_collections.py
-```
-
-**List environments:**
-```bash
-python postman-slash-command/scripts/list_collections.py --environments
-```
-
-**List monitors:**
-```bash
-python postman-slash-command/scripts/list_collections.py --monitors
-```
-
-**List APIs:**
-```bash
-python postman-slash-command/scripts/list_collections.py --apis
-```
-
-### Collection Management
-
-**List collections:**
-```bash
-python postman-slash-command/scripts/manage_collections.py --list
-```
-
-**Get collection details:**
-```bash
-python postman-slash-command/scripts/manage_collections.py --get <collection-id>
-```
-
-**Create new collection:**
-```bash
-python postman-slash-command/scripts/manage_collections.py --create --name="My Collection"
-```
-
-**Update collection:**
-```bash
-python postman-slash-command/scripts/manage_collections.py --update <collection-id> --name="New Name"
-```
-
-**Delete collection:**
-```bash
-python postman-slash-command/scripts/manage_collections.py --delete <collection-id>
-```
-
-**Duplicate collection:**
-```bash
-python postman-slash-command/scripts/manage_collections.py --duplicate <collection-id> --name="Copy"
-```
-
-### Environment Management
-
-**List environments:**
-```bash
-python postman-slash-command/scripts/manage_environments.py --list
-```
-
-**Create environment:**
-```bash
-python postman-slash-command/scripts/manage_environments.py --create --name="Development"
-```
-
-**Get environment details:**
-```bash
-python postman-slash-command/scripts/manage_environments.py --get <environment-id>
-```
-
-**Update environment:**
-```bash
-python postman-slash-command/scripts/manage_environments.py --update <environment-id> --name="New Name"
-```
-
-**Delete environment:**
-```bash
-python postman-slash-command/scripts/manage_environments.py --delete <environment-id>
-```
-
-**Duplicate environment:**
-```bash
-python postman-slash-command/scripts/manage_environments.py --duplicate <environment-id> --name="Copy"
-```
-
-### Monitor Management
-
-**List monitors:**
-```bash
-python postman-slash-command/scripts/manage_monitors.py --list
-```
-
-**Get monitor details:**
-```bash
-python postman-slash-command/scripts/manage_monitors.py --get <monitor-id>
-```
-
-**Analyze monitor runs:**
-```bash
-python postman-slash-command/scripts/manage_monitors.py --analyze <monitor-id> --limit 10
-```
-
-### Test Execution
-
-**Run collection tests:**
-```bash
-python postman-slash-command/scripts/run_collection.py --collection="Collection Name"
-```
-
-**Run with environment:**
-```bash
-python postman-slash-command/scripts/run_collection.py --collection="Collection Name" --environment="Environment Name"
-```
-
-### Agent-Readiness Analysis
-
-Analyze APIs to determine if they're ready for AI agents to discover, understand, and self-heal from errors. Uses Clara, the AI Agent API Readiness Analyzer.
-
-**Analyze a local OpenAPI spec:**
-```bash
-python postman-slash-command/scripts/analyze_agent_readiness.py ./openapi.yaml
-```
-
-**Analyze a spec from URL:**
-```bash
-python postman-slash-command/scripts/analyze_agent_readiness.py --url https://petstore3.swagger.io/api/v3/openapi.json
-```
-
-**Analyze a Postman collection:**
-```bash
-python postman-slash-command/scripts/analyze_agent_readiness.py --collection <collection-id>
-```
-
-**Get detailed JSON output:**
-```bash
-python postman-slash-command/scripts/analyze_agent_readiness.py ./openapi.yaml --json
-```
-
-**Save reports to files:**
-```bash
-python postman-slash-command/scripts/analyze_agent_readiness.py ./openapi.yaml -o report.json -o report.md
-```
-
-#### What Clara Checks
-
-Clara analyzes APIs across 8 pillars:
-1. **Metadata** - operationIds, summaries, descriptions
-2. **Errors** - Structured error responses with codes and details
-3. **Introspection** - Parameter types, required fields, examples
-4. **Naming** - Consistent casing, RESTful paths
-5. **Predictability** - Response schemas, pagination patterns
-6. **Documentation** - Auth docs, rate limits
-7. **Performance** - Response times, rate limit headers
-8. **Discoverability** - Server URLs, spec accessibility
-
-#### Understanding Results
-
- **Score 70%+ with no critical failures** = Agent Ready
- **Below 70% or critical failures** = Not Agent Ready
- **Priority Fixes** = Most impactful improvements, ranked by severity x endpoints affected
-
-For conceptual questions about agent-ready APIs, refer to `skills/knowledge/agent-ready-apis.md`.
-
-## How to Respond
-
-When the user asks about Postman:
-
-1. **Understand the intent** - What do they want?
-
-   **For "how do I" / conceptual questions:**
-   - "How do I set up OAuth?" → Query `postman-docs` MCP for authentication docs
-   - "What's the best way to organize collections?" → Query `postman-docs` MCP for best practices
-   - "What's new in V12?" → Query `postman-docs` MCP for V12 features
-   - "How do monitors work?" → Query `postman-docs` MCP, then offer to show their monitors
-
-   **For action/execution requests:**
-   - List resources? → Use list_collections.py
-   - Manage collections? → Use manage_collections.py
-   - Manage environments? → Use manage_environments.py
-   - Check monitors? → Use manage_monitors.py
-   - Run tests? → Use run_collection.py
-   - Check agent-readiness? → Use analyze_agent_readiness.py
-   - Ask about API design for AI? → Reference skills/knowledge/agent-ready-apis.md
-
-2. **Execute the appropriate action** - Query docs OR run scripts based on intent
-
-3. **Parse and present results** - Format the output in a user-friendly way
-
-4. **Suggest next steps** - Based on what they accomplished, suggest related actions
-
-## Examples
-
-### Example 1: User wants to see their collections
-
-**User:** "Show me my Postman collections"
-
-**You should:**
-1. Run: `python postman-slash-command/scripts/list_collections.py`
-2. Parse the output
-3. Present in a clear format
-4. Ask if they want to do anything with the collections
-
-### Example 2: User wants to create a new collection
-
-**User:** "Create a new collection called 'Payment API Tests'"
-
-**You should:**
-1. Run: `python postman-slash-command/scripts/manage_collections.py --create --name="Payment API Tests"`
-2. Confirm success
-3. Show the collection ID
-4. Ask if they want to add requests to it
-
-### Example 3: User wants to check monitor status
-
-**User:** "How is my API monitoring doing?"
-
-**You should:**
-1. First list monitors: `python postman-slash-command/scripts/manage_monitors.py --list`
-2. For each monitor, analyze runs: `python postman-slash-command/scripts/manage_monitors.py --analyze <monitor-id> --limit 5`
-3. Summarize the health (success rates, response times, recent failures)
-4. Alert if any monitors are failing
-
-### Example 4: User wants to check if their API is agent-ready
-
-**User:** "Is my Payment API ready for AI agents?"
-
-**You should:**
-1. Find or ask for the OpenAPI spec location
-2. Run: `python postman-slash-command/scripts/analyze_agent_readiness.py ./payment-api.yaml`
-3. Present the overall score and agent-ready status
-4. Highlight critical issues that block agent usage
-5. Show top priority fixes with specific recommendations
-6. Offer to explain any pillar in more detail
-
-**User:** "Why can't AI agents use my API well?"
-
-**You should:**
-1. Run agent-readiness analysis
-2. Focus on failed checks, especially critical ones
-3. Explain the impact: "Missing operationIds means agents can't reference your endpoints uniquely"
-4. Reference `skills/knowledge/agent-ready-apis.md` for detailed explanations
-5. Suggest specific fixes with examples
-
-## Error Handling
-
-If a script fails:
-1. Check if `.env` file exists and has `POSTMAN_API_KEY`
-2. Verify the API key is valid (starts with `PMAK-`)
-3. Check if the resource ID/name is correct
-4. Provide helpful error messages to the user
-
-## Notes
-
- All scripts automatically load configuration from `.env` file
- Scripts use retry logic for rate limits
- Collection/environment IDs are UUIDs (e.g., `12345678-1234-1234-1234-123456789012`)
- Monitor IDs are shorter alphanumeric strings
- Use `--help` flag on any script to see all available options
--- a/commands/search.md
+++ b/commands/search.md
@@ -0,0 +1,79 @@
+---
+description: Discover APIs across your Postman workspaces. Ask natural language questions about available endpoints and capabilities.
+allowed-tools: Read, Glob, Grep, mcp__postman__*
+---
+
+# 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
+
+1. Call `getWorkspaces` to get the user's workspace ID. If multiple workspaces exist, ask which to use.
+2. Call `getCollections` with the `workspace` parameter. Use the `name` filter to narrow results.
+3. If results are sparse, broaden the search:
+   - Call `getTaggedEntities` to find collections by tag
+   - Call `getWorkspaces` to search across all workspaces
+   - As a fallback for public APIs, call `searchPostmanElements` with the user's query
+
+**Important:** `searchPostmanElements` only searches the PUBLIC Postman network, not private workspaces. Always search private workspace first using `getCollections`.
+
+### 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"
+    }
+
+  Want me to generate a client for this API? → /postman:codegen
+```
+
+**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 in your workspace. Try different keywords, or search the public Postman network with broader terms."
+- **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`."
+- **Too many results:** Ask the user to be more specific. Suggest filtering by workspace or using tags.
--- a/commands/security.md
+++ b/commands/security.md
@@ -0,0 +1,129 @@
+---
+description: Security audit your APIs against OWASP API Top 10. Finds vulnerabilities and provides remediation guidance.
+allowed-tools: Read, Glob, Grep, mcp__postman__*
+---
+
+# API Security Audit
+
+Audit your API for security issues: missing auth, exposed sensitive data, insecure transport, weak validation, and OWASP API Security Top 10 alignment. Works with local OpenAPI specs and Postman collections.
+
+## Prerequisites
+
+For collection auditing, the Postman MCP Server must be connected. Local spec auditing 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.
+
+**Local spec:**
+- Search for `**/openapi.{json,yaml,yml}`, `**/swagger.{json,yaml,yml}`
+
+**Postman spec (via MCP):**
+- Call `getAllSpecs` with the workspace ID to find specs
+- Call `getSpecDefinition` for the full spec content
+
+**Postman collection (via MCP):**
+- Call `getCollections` with the `workspace` parameter
+- Call `getCollection` for full detail including auth config
+- Call `getEnvironment` to check for exposed secrets
+
+### Step 2: Run Security Checks
+
+**Authentication and Authorization:**
+- Security schemes defined (OAuth2, API Key, Bearer, etc.)
+- Security applied globally or per-endpoint
+- No endpoints accidentally unprotected
+- OAuth2 scopes defined and appropriate
+- Admin endpoints have elevated auth requirements
+
+**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 Too Many Requests 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
+- Error messages don't reveal implementation details
+
+**OWASP API Top 10 Alignment:**
+- 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
+
+### Step 3: Present Results
+
+```
+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
+```
+
+### Step 4: Fix
+
+For each finding:
+1. Explain the security risk in plain terms
+2. Show the exact spec change needed
+3. Apply the fix with user approval
+
+For Postman-specific issues:
+- Call `putEnvironment` to mark secrets properly
+- Call `updateCollectionRequest` to fix auth configuration
+- Call `updateCollectionResponse` to remove sensitive data from examples
+
+### Step 5: Re-audit
+
+After fixes, re-run the audit to show improvement.
+
+## Error Handling
+
+- **MCP not configured:** Local spec auditing works without MCP. For Postman-specific checks: "Run `/postman:setup` to configure the Postman MCP Server."
+- **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`."
+- **No spec found:** Ask the user for the path. Offer to audit a Postman collection directly via MCP.
+- **Spec too large:** For large specs (100+ endpoints), audit in batches by tag or path prefix.
+- **Plan limitations:** "Some audit features may require a paid Postman plan. Check https://www.postman.com/pricing/"
--- a/commands/setup.md
+++ b/commands/setup.md
@@ -0,0 +1,99 @@
+---
+description: Set up Postman MCP Server. Configure API key, verify connection, select workspace.
+allowed-tools: mcp__postman__*
+---
+
+# 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 3 (workspace verification).
+
+**If it fails or tools aren't available:** Proceed to Step 2.
+
+### Step 2: Configure API Key
+
+```
+Let's set up Postman for Claude Code.
+
+1. Go to: https://postman.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.
+```
+
+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://postman.postman.co/settings/me/api-keys"
+
+**If timeout:** "Can't reach the Postman MCP Server. Check your network and https://status.postman.com"
+
+### Step 3: Workspace Verification
+
+After successful connection:
+
+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 the public Postman API Network
+```
+
+### Step 4: 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
+  /postman:codegen  — Generate client code from a collection
+```
+
+**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."
+- **API key not set:** Walk through Step 2 above.
+- **401 Unauthorized:** "Your API key was rejected. Generate a new one at https://postman.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."
--- a/commands/sync.md
+++ b/commands/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__*
+---
+
+# 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."
--- a/commands/test.md
+++ b/commands/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__*
+---
+
+# 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://postman.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."