From 3f03fc19d3483dc6a564eee12d695d19a4324270 Mon Sep 17 00:00:00 2001 From: Sterling Chin Date: Thu, 12 Feb 2026 17:55:22 -0800 Subject: [PATCH] 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 --- commands/codegen.md | 93 +++++++++++++ commands/docs.md | 88 +++++++++++++ commands/mock.md | 101 +++++++++++++++ commands/postman.md | 302 ------------------------------------------- commands/search.md | 79 +++++++++++ commands/security.md | 129 ++++++++++++++++++ commands/setup.md | 99 ++++++++++++++ commands/sync.md | 85 ++++++++++++ commands/test.md | 84 ++++++++++++ 9 files changed, 758 insertions(+), 302 deletions(-) create mode 100644 commands/codegen.md create mode 100644 commands/docs.md create mode 100644 commands/mock.md delete mode 100644 commands/postman.md create mode 100644 commands/search.md create mode 100644 commands/security.md create mode 100644 commands/setup.md create mode 100644 commands/sync.md create mode 100644 commands/test.md diff --git a/commands/codegen.md b/commands/codegen.md new file mode 100644 index 0000000..b884d71 --- /dev/null +++ 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/.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. diff --git a/commands/docs.md b/commands/docs.md new file mode 100644 index 0000000..0882538 --- /dev/null +++ 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. diff --git a/commands/mock.md b/commands/mock.md new file mode 100644 index 0000000..1020dd7 --- /dev/null +++ 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: ` Mock` +- Private: false (or true if user prefers) + +### Step 5: Present Mock URL + +``` +Mock server created: "Pet Store API Mock" + URL: https://.mock.pstmn.io + Status: Active + + Try it: + curl https://.mock.pstmn.io/pets + curl https://.mock.pstmn.io/pets/1 + curl -X POST https://.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.pstmn.io + + # Or in your frontend config + const API_URL = process.env.API_BASE_URL || 'https://.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." diff --git a/commands/postman.md b/commands/postman.md deleted file mode 100644 index f898274..0000000 --- a/commands/postman.md +++ /dev/null @@ -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 -``` - -**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 --name="New Name" -``` - -**Delete collection:** -```bash -python postman-slash-command/scripts/manage_collections.py --delete -``` - -**Duplicate collection:** -```bash -python postman-slash-command/scripts/manage_collections.py --duplicate --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 -``` - -**Update environment:** -```bash -python postman-slash-command/scripts/manage_environments.py --update --name="New Name" -``` - -**Delete environment:** -```bash -python postman-slash-command/scripts/manage_environments.py --delete -``` - -**Duplicate environment:** -```bash -python postman-slash-command/scripts/manage_environments.py --duplicate --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 -``` - -**Analyze monitor runs:** -```bash -python postman-slash-command/scripts/manage_monitors.py --analyze --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 -``` - -**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 --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 diff --git a/commands/search.md b/commands/search.md new file mode 100644 index 0000000..2367578 --- /dev/null +++ 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. diff --git a/commands/security.md b/commands/security.md new file mode 100644 index 0000000..0bb8273 --- /dev/null +++ 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/" diff --git a/commands/setup.md b/commands/setup.md new file mode 100644 index 0000000..3a7426e --- /dev/null +++ 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: + +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." diff --git a/commands/sync.md b/commands/sync.md new file mode 100644 index 0000000..3b55ea8 --- /dev/null +++ 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." diff --git a/commands/test.md b/commands/test.md new file mode 100644 index 0000000..27ad1f3 --- /dev/null +++ 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."