From 980897e901e9ed5df19a5561b9c2fc76feb533b4 Mon Sep 17 00:00:00 2001 From: chirag-yaduwanshi Date: Thu, 26 Mar 2026 11:48:42 +0530 Subject: [PATCH] Search Strategy update to utilise private network search --- README.md | 2 +- commands/codegen.md | 6 +++--- commands/search.md | 15 +++++++-------- commands/setup.md | 2 +- skills/postman-knowledge/SKILL.md | 4 ++-- skills/postman-knowledge/mcp-limitations.md | 6 ------ 6 files changed, 14 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 75ba317..cb9631b 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ Get your API key at [postman.postman.co/settings/me/api-keys](https://postman.po | `/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: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 | diff --git a/commands/codegen.md b/commands/codegen.md index b884d71..5fd3d42 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 `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. +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. 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 2367578..03abe90 100644 --- a/commands/search.md +++ b/commands/search.md @@ -15,14 +15,13 @@ The Postman MCP Server must be connected. If MCP tools aren't available, tell th ### Step 1: Search -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 +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. -**Important:** `searchPostmanElements` only searches the PUBLIC Postman network, not private workspaces. Always search private workspace first using `getCollections`. +**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. ### Step 2: Drill Into Results @@ -74,6 +73,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 workspace. Try different keywords, or search the public Postman network with broader terms." +- **No results:** "Nothing matched in your private API network. Try different keywords, browse in user's workspaces, or search the public Postman network." - **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 3a7426e..0f9a950 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 the public Postman API Network + /postman:search — Search for APIs across your org's private network or the public Postman network ``` ### Step 4: Suggest First Command diff --git a/skills/postman-knowledge/SKILL.md b/skills/postman-knowledge/SKILL.md index a3e4d78..48e23ec 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, then drill into details | +| Find an API | Search workspace collections in private network/user's workspaces/public network, 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:** `searchPostmanElements` (public network only), `getTaggedEntities` +**Search:** `searchPostmanElementsInPrivateNetwork` (private/org APIs, default), `searchPostmanElementsInPublicNetwork` (public network), `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 cb90229..6027aa7 100644 --- a/skills/postman-knowledge/mcp-limitations.md +++ b/skills/postman-knowledge/mcp-limitations.md @@ -2,12 +2,6 @@ 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.