CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

The Postman Plugin for Claude Code — a pure-markdown, configuration-driven plugin that provides full API lifecycle management via the Postman MCP Server. No compiled code, no runtime dependencies, no build step.

Repository Structure

.claude-plugin/plugin.json   # Plugin manifest (name, version, metadata)
.mcp.json                    # MCP server auto-config (Postman MCP at mcp.postman.com)
commands/*.md                # 11 slash commands (/postman:<name>)
skills/*/SKILL.md            # 7 skills (routing, knowledge, agent-ready APIs, CLI, send-request, generate-spec, run-collection)
agents/readiness-analyzer.md # Sub-agent for API readiness analysis
examples/                    # Sample output (readiness report)
assets/                      # GIFs for README

How the Plugin Works

Claude Code discovers components via .claude-plugin/plugin.json manifest
.mcp.json auto-configures the Postman MCP server, providing mcp__postman__* tools (111 tools)
MCP commands use the cloud Postman MCP Server — requires POSTMAN_API_KEY environment variable
CLI commands use the locally installed Postman CLI (npm install -g postman-cli) — requires postman login
Plugin is loaded with claude --plugin-dir /path/to/postman-claude-code-plugin

Component Conventions

Commands (commands/*.md): YAML front matter with description and allowed-tools. Each defines a structured workflow invoked as /postman:<name>.

MCP commands: setup, sync, codegen, search, test, mock, docs, security
CLI commands: request, generate-spec, run-collection

Skills (skills/*/SKILL.md): YAML front matter with name, description, user-invocable. Auto-injected context, not directly invoked. postman-routing routes requests to commands; postman-knowledge provides MCP tool guidance; agent-ready-apis provides readiness criteria; postman-cli provides CLI and git sync file structure knowledge.

Agent (agents/readiness-analyzer.md): YAML front matter with name, description, model, allowed-tools. Runs as a sub-agent (sonnet model) for deep API readiness analysis (8 pillars, 48 checks).

Key MCP Limitations

These are documented in skills/postman-knowledge/mcp-limitations.md and must be respected in all commands:

searchPostmanElements searches PUBLIC network only — use getWorkspaces + getCollections for private content
generateCollection and syncCollectionWithSpec return HTTP 202 — must poll for completion
syncCollectionWithSpec supports OpenAPI 3.0 only — use updateSpecFile + generateCollection for Swagger 2.0 or OpenAPI 3.1
createCollection creates flat collections — nest via createCollectionFolder + createCollectionRequest
createSpec struggles with specs >50KB — decompose into collection items instead

Postman CLI Commands

Three commands use the Postman CLI instead of MCP. They require postman-cli installed locally (npm install -g postman-cli) and authenticated (postman login). If CLI is not found, show install instructions and stop.

/postman:request — Send HTTP requests via postman request <METHOD> <URL>
/postman:generate-spec — Scan code for API routes, generate OpenAPI 3.0 YAML, validate with postman spec lint
/postman:run-collection — Run collection tests via postman collection run <id> using cloud IDs from .postman/resources.yaml

CLI commands work with Postman's git sync structure: postman/collections/ (v3 folder format), postman/environments/, postman/specs/, and .postman/resources.yaml for cloud ID mapping.

Development Notes

There is no build, lint, or test suite — all "code" is instructional markdown
Changes are purely editing markdown files with YAML front matter
When adding a new command, follow the existing front matter pattern in commands/
When adding a new skill, create skills/<name>/SKILL.md with proper front matter
The allowed-tools field in front matter controls what tools a command/agent can use
CLI commands need Bash in allowed-tools; MCP commands need mcp__postman__*

4.2 KiB Raw Blame History