mirror of
https://github.com/Postman-Devrel/postman-claude-code-plugin.git
synced 2026-04-16 19:08:20 +00:00
67 lines
4.2 KiB
Markdown
67 lines
4.2 KiB
Markdown
|
# 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__*`
|