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>
102 lines
3.6 KiB
Markdown
102 lines
3.6 KiB
Markdown
---
|
|
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."
|