postman-cursor-rules / rules

---
description: "Postman MCP integration for API development workflows"
globs: ["**/api/**/*", "**/routes/**/*", "**/routers/**/*", "**/endpoints/**/*", "**/controllers/**/*", "openapi.yaml", "openapi.json", "swagger.yaml", "swagger.json"]
alwaysApply: false
---

# Postman MCP Integration

## Workspace
- Workspace: <your-workspace-name>
- Workspace ID: <your-workspace-id>

Get your workspace ID from the Postman URL: `https://go.postman.co/workspace/<workspace-id>`

## MCP Server
This project uses the Postman MCP server at `https://mcp.postman.com/code`.

Three server modes are available:

| Mode | URL | Use Case |
|------|-----|----------|
| Minimal | `https://mcp.postman.com/minimal` | Basic collection operations |
| Code | `https://mcp.postman.com/code` | API search + client code generation |
| Full | `https://mcp.postman.com/mcp` | Everything (100+ Postman API tools) |

## When to Sync with Postman

Update the Postman collection when:
1. Adding a new endpoint
2. Changing request or response schemas
3. Adding or modifying query parameters or headers
4. Updating authentication requirements
5. Changing error response formats

## Sync Workflow

### Code to Postman
After implementing a new endpoint:
1. Use the Postman MCP server to add the request to the collection
2. Include example request body (if applicable)
3. Add example success and error responses
4. Write a clear description for the endpoint
5. Group the request under the appropriate resource folder

### Postman to Code
When the API spec changes in Postman:
1. Fetch the spec via MCP
2. Compare with local models and schemas
3. Update code to match the spec
4. Verify request and response schemas align

## Collection Standards
- Group requests by resource (Users, Orders, Products, etc.)
- Every request needs a description
- Include example responses for success and error cases
- Use environment variables: `{{base_url}}`, `{{api_key}}`
- Tag requests by category when applicable

## Example Prompts

**Add an endpoint to the collection:**
> "Using the Postman MCP server, add a new GET /users/{id}/orders endpoint to my collection. Include pagination query params and an example response."

**Check for drift between code and Postman:**
> "Fetch the API spec from my Postman workspace and compare it to my local schemas. Are there any fields that are out of sync?"

**Bulk sync after changes:**
> "I updated the Orders router with 3 new endpoints. Add all of them to the Postman collection with descriptions and example responses."

**Generate client code:**
> "Using the Postman MCP server, find the Users API in my workspace and generate a TypeScript client for it."