diff --git a/README.md b/README.md index 2e29ff4..75ba317 100644 --- a/README.md +++ b/README.md @@ -58,16 +58,16 @@ Get your API key at [postman.postman.co/settings/me/api-keys](https://postman.po Postman Plugin generating code from a collection

-| Command | What It Does | -|---------|---------------------------------------------------------------------------------------------| -| `/postman:setup` | Configure API key, verify connection, select workspace | -| `/postman:sync` | Create or update Postman collections from OpenAPI specs | -| `/postman:codegen` | Generate typed client code from any Postman collection | -| `/postman:search` | Find APIs across your org's private network, your workspaces and the public Postman network | -| `/postman:test` | Run collection tests, diagnose failures, suggest fixes | -| `/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 | +| Command | What It Does | +|---------|-------------| +| `/postman:setup` | Configure API key, verify connection, select workspace | +| `/postman:sync` | Create or update Postman collections from OpenAPI specs | +| `/postman:codegen` | Generate typed client code from any Postman collection | +| `/postman:search` | Find APIs across your private workspaces | +| `/postman:test` | Run collection tests, diagnose failures, suggest fixes | +| `/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 | ## What You Can Do diff --git a/commands/codegen.md b/commands/codegen.md index 5fd3d42..b884d71 100644 --- a/commands/codegen.md +++ b/commands/codegen.md @@ -15,9 +15,9 @@ The Postman MCP Server must be connected. If MCP tools aren't available, tell th ### Step 1: Find the API -1. Call `searchPostmanElementsInPrivateNetwork` with the API name to find it in the organization's private network. -2. If no results, call `getWorkspaces` to get the user's workspace ID. If multiple workspaces exist, ask which to use. Then use `getCollections` with the `workspace` parameter and `name` filter if the user specified an API name. -3. If still no results, fall back to `searchPostmanElementsInPublicNetwork` to search the public Postman network. +1. Call `getWorkspaces` to get the user's workspace ID. If multiple workspaces exist, ask which to use. +2. Call `getCollections` with the `workspace` parameter. Use the `name` filter if the user specified an API name. +3. If no results in private workspace, fall back to `searchPostmanElements` to search the public Postman network. 4. If multiple matches, list them and ask which one. 5. Call `getCollection` to get the full collection. 6. Call `getSpecDefinition` if a linked spec exists (richer type info). diff --git a/commands/search.md b/commands/search.md index 03abe90..2367578 100644 --- a/commands/search.md +++ b/commands/search.md @@ -15,13 +15,14 @@ The Postman MCP Server must be connected. If MCP tools aren't available, tell th ### Step 1: Search -1. Call `searchPostmanElementsInPrivateNetwork` with the user's query. This searches the organization's private API network and is the **primary** search path. -2. If private network results are sparse or private network search is not available, broaden the search: - - Call `getWorkspaces` to get the user's workspace ID. If multiple workspaces exist, ask which to use. Then use `getCollections` with the `workspace` parameter. Use the `name` filter to narrow results. - - Call `getTaggedEntities` to find collections by tag. -3. If the user is looking for a public/third-party API (e.g., Stripe, GitHub, Twilio), call `searchPostmanElementsInPublicNetwork` with the user's query. +1. Call `getWorkspaces` to get the user's workspace ID. If multiple workspaces exist, ask which to use. +2. Call `getCollections` with the `workspace` parameter. Use the `name` filter to narrow results. +3. If results are sparse, broaden the search: + - Call `getTaggedEntities` to find collections by tag + - Call `getWorkspaces` to search across all workspaces + - As a fallback for public APIs, call `searchPostmanElements` with the user's query -**Important:** Default to `searchPostmanElementsInPrivateNetwork` for trusted APIs in user's organisation. Only use `searchPostmanElementsInPublicNetwork` when the user explicitly wants public/third-party APIs or private search returns no results. +**Important:** `searchPostmanElements` only searches the PUBLIC Postman network, not private workspaces. Always search private workspace first using `getCollections`. ### Step 2: Drill Into Results @@ -73,6 +74,6 @@ List relevant collections with endpoint counts, then ask which to explore furthe ## Error Handling - **MCP not configured:** "Run `/postman:setup` to configure the Postman MCP Server." -- **No results:** "Nothing matched in your private API network. Try different keywords, browse in user's workspaces, or search the public Postman network." +- **No results:** "Nothing matched in your workspace. Try different keywords, or search the public Postman network with broader terms." - **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`." - **Too many results:** Ask the user to be more specific. Suggest filtering by workspace or using tags. diff --git a/commands/setup.md b/commands/setup.md index 0f9a950..3a7426e 100644 --- a/commands/setup.md +++ b/commands/setup.md @@ -63,7 +63,7 @@ If workspace is empty: ``` Your workspace is empty. You can: /postman:sync — Push a local OpenAPI spec to Postman - /postman:search — Search for APIs across your org's private network or the public Postman network + /postman:search — Search the public Postman API Network ``` ### Step 4: Suggest First Command diff --git a/skills/postman-knowledge/SKILL.md b/skills/postman-knowledge/SKILL.md index 48e23ec..a3e4d78 100644 --- a/skills/postman-knowledge/SKILL.md +++ b/skills/postman-knowledge/SKILL.md @@ -27,7 +27,7 @@ Reference for Postman concepts and MCP tool selection. Use this context when wor |------|----------| | Push code changes to Postman | Create/update spec in Spec Hub, then sync to collection | | Consume a Postman API | Read collection + generate client code | -| Find an API | Search workspace collections in private network/user's workspaces/public network, then drill into details | +| Find an API | Search workspace collections, then drill into details | | Test an API | Run collection with `runCollection` | | Create a fake API for frontend | Create mock server from collection with examples | | Document an API | Analyze collection completeness, fill gaps, optionally publish | @@ -45,7 +45,7 @@ Reference for Postman concepts and MCP tool selection. Use this context when wor **Mocks:** `getMocks`, `getMock`, `createMock`, `publishMock`, `unpublishMock` **Tests:** `runCollection` **Docs:** `publishDocumentation`, `unpublishDocumentation` -**Search:** `searchPostmanElementsInPrivateNetwork` (private/org APIs, default), `searchPostmanElementsInPublicNetwork` (public network), `getTaggedEntities` +**Search:** `searchPostmanElements` (public network only), `getTaggedEntities` **User:** `getAuthenticatedUser` See `mcp-limitations.md` in this skill folder for known limitations and workarounds. diff --git a/skills/postman-knowledge/mcp-limitations.md b/skills/postman-knowledge/mcp-limitations.md index 6027aa7..cb90229 100644 --- a/skills/postman-knowledge/mcp-limitations.md +++ b/skills/postman-knowledge/mcp-limitations.md @@ -2,6 +2,12 @@ These limitations are documented so they are handled correctly in all commands and workflows. +## searchPostmanElements is Public-Only + +`searchPostmanElements` searches the PUBLIC Postman network only, not the user's private workspaces. + +**Workaround:** For private content, use `getWorkspaces` + `getCollections` + `getCollection`. Use `searchPostmanElements` only as a fallback when searching for public APIs. + ## generateCollection is Async `generateCollection` returns HTTP 202 (accepted), not the collection directly.