diff --git a/CLAUDE.md b/CLAUDE.md index 1769e1a..bcfd762 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,7 @@ The Postman Plugin for Claude Code — a pure-markdown, configuration-driven plu ``` .claude-plugin/plugin.json # Plugin manifest (name, version, metadata) .mcp.json # MCP server auto-config (Postman MCP at mcp.postman.com) -commands/*.md # 10 slash commands (/postman:) +commands/*.md # 11 slash commands (/postman:) skills/*/SKILL.md # 7 skills (knowledge, agent-ready APIs, CLI, send-request, generate-spec, run-collection, context) skills/*/references/*.md # On-demand reference files loaded by skills only when needed agents/readiness-analyzer.md # Sub-agent for API readiness analysis @@ -30,7 +30,7 @@ examples/ # Sample output (readiness report) ## Component Conventions **Commands** (`commands/*.md`): YAML front matter with `description` and `allowed-tools`. Each defines a structured workflow invoked as `/postman:`. -- MCP commands: setup, sync, search, test, mock, docs, security +- MCP commands: setup, sync, search, test, mock, docs, security, learn (learn requires Full mode — `searchLearningCenter` is absent in `minimal`/`code`) - 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-knowledge` provides MCP tool guidance; `agent-ready-apis` provides readiness criteria; `postman-cli` provides CLI and git sync file structure knowledge; `postman-context` provides API discovery, exploration, and code generation from real API definitions. diff --git a/README.md b/README.md index 4f3b9db..3aab1da 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,7 @@ That's it. The plugin auto-configures the Postman MCP Server, verifies your conn | `/postman:mock` | Create mock servers for frontend development | | `/postman:docs` | Generate, improve, and publish API documentation | | `/postman:security` | Security audit against OWASP API Top 10 | +| `/postman:learn` | Search the Postman Learning Center for how-to guidance and suggested workflows (Full mode) | ## What You Can Do diff --git a/commands/learn.md b/commands/learn.md new file mode 100644 index 0000000..650770c --- /dev/null +++ b/commands/learn.md @@ -0,0 +1,69 @@ +--- +description: Search the Postman Learning Center for how-to guidance, feature explanations, and suggested workflows. Use for "how do I..." questions about the Postman product. +allowed-tools: Read, mcp__postman__searchLearningCenter, mcp__postman__getEnabledTools +--- + +# Learn Postman + +Answer "how do I..." questions about the Postman product by searching the official Postman Learning Center (https://learning.postman.com). Explain features, walk through workflows, and cite authoritative sources. + +Use this to learn *about Postman itself* — not to search the user's own collections, workspaces, or specs (that's `/postman:search`). + +## Prerequisites + +This command uses `searchLearningCenter`, which is only exposed when the Postman MCP Server runs in **Full mode** (`POSTMAN_MCP_MODE=mcp`, the default). It is **not** available in `minimal` or `code` mode. + +- If MCP tools aren't available at all, tell the user: "Run `/postman:setup` to configure the Postman MCP Server." +- If `searchLearningCenter` specifically is missing, call `getEnabledTools` to confirm the active tool set, then tell the user: "Searching the Learning Center requires Full mode. Unset `POSTMAN_MCP_MODE` (or set it to `mcp`) and restart Claude Code." + +## Workflow + +### Step 1: Search + +Call `searchLearningCenter` with a focused `query` derived from the user's question. Prefer the product vocabulary from `postman-knowledge` (mock server, environment, monitor, collection variable, etc.) over the user's exact phrasing. + +- Turn a broad request into a specific query — "how to create a mock server", "write a test script", "set a collection variable", "schedule a monitor". +- If results are thin or off-target, refine: try a different feature term, split a multi-part question into separate searches, or broaden a narrow query. + +### Step 2: Synthesize + +Read the returned passages and compose a direct answer to the user's question. Do not just dump raw results. + +- Lead with the answer or the concrete steps. +- Keep steps in the order the user would perform them. +- If the docs reveal a better or officially recommended workflow than what the user asked, surface it. +- Always cite the source URLs the tool returns so the user can read more. + +### Step 3: Connect to the Plugin + +When a workflow maps to a plugin command, point the user there so they can act immediately: + +- Creating/updating collections from a spec → `/postman:sync` +- Finding APIs in their org or the public network → `/postman:search` +- Running collection tests → `/postman:test` +- Creating mock servers → `/postman:mock` +- Generating or publishing docs → `/postman:docs` +- Security auditing → `/postman:security` + +## Output + +``` +To create a mock server in Postman: + + 1. Open the collection you want to mock (it needs saved example responses). + 2. Select the collection → "Mock collection". + 3. Name the mock, pick an environment, and choose visibility. + 4. Postman returns a mock URL that serves your examples. + + Mock servers read from saved examples, so add examples first if you + have none — the plugin can do this for you via /postman:mock. + + Source: https://learning.postman.com/docs/design-apis/mock-apis/set-up-mock-servers/ +``` + +## Error Handling + +- **MCP not configured:** "Run `/postman:setup` to configure the Postman MCP Server." +- **Tool unavailable (wrong mode):** Confirm with `getEnabledTools`, then: "Searching the Learning Center requires Full mode. Unset `POSTMAN_MCP_MODE` (or set it to `mcp`) and restart Claude Code." +- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys and run `/postman:setup`." +- **No results:** "Nothing matched in the Learning Center. Try rephrasing with the Postman feature name, or ask about a more specific step." diff --git a/skills/postman-knowledge/SKILL.md b/skills/postman-knowledge/SKILL.md index 581b0f7..1729589 100644 --- a/skills/postman-knowledge/SKILL.md +++ b/skills/postman-knowledge/SKILL.md @@ -32,6 +32,7 @@ Reference for Postman concepts and MCP tool selection. Use this context when wor | Create a fake API for frontend | Create mock server from collection with examples | | Document an API | Analyze collection completeness, fill gaps, optionally publish | | Audit API security | Run security checks against spec or collection | +| Learn how to use a Postman feature | Search Postman docs with `searchLearningCenter` (Full mode) | ## MCP Tool Selection @@ -46,6 +47,7 @@ Reference for Postman concepts and MCP tool selection. Use this context when wor **Tests:** `runCollection` **Docs:** `publishDocumentation`, `unpublishDocumentation` **Search:** `searchPostmanElements` , `getTaggedEntities` +**Learning Center:** `searchLearningCenter` (Full mode only — searches Postman product docs for how-to guidance) **User:** `getAuthenticatedUser` See `mcp-limitations.md` in this skill folder for known limitations and workarounds.