From 191fbf067351391f2760a7a67704cf5ae0952d27 Mon Sep 17 00:00:00 2001 From: chirag-yaduwanshi Date: Thu, 25 Jun 2026 12:12:19 +0530 Subject: [PATCH 1/2] Update Search tool and strategy --- CLAUDE.md | 2 +- README.md | 4 ++-- commands/search.md | 23 +++++++++++++++-------- commands/setup.md | 2 +- skills/postman-context/SKILL.md | 2 +- skills/postman-knowledge/SKILL.md | 4 ++-- 6 files changed, 22 insertions(+), 15 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3ac0b64..1769e1a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,7 +43,7 @@ Large skills use progressive disclosure: a lean SKILL.md holds the workflow, and 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 +- `searchPostmanElements` is the unified search tool — pass `ownership: organization` (default) for the user's org resources, `external` for the public Postman network, or `all` for both. Use the `privateNetwork` filter to restrict to the Private API Network. - `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` diff --git a/README.md b/README.md index d79ea96..4f3b9db 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,7 @@ That's it. The plugin auto-configures the Postman MCP Server, verifies your conn |---------|-------------| | `/postman:setup` | Configure API key, verify connection, select workspace | | `/postman:sync` | Create or update Postman collections from OpenAPI specs | -| `/postman:search` | Find APIs across your org's private network, your workspaces and the public Postman network | +| `/postman:search` | Find APIs across your org's resources, your workspaces, and the public Postman network | | `/postman:context` | Fetch real API definitions, generate and maintain typed client code | | `/postman:test` | Run collection tests, diagnose failures, suggest fixes | | `/postman:mock` | Create mock servers for frontend development | @@ -76,7 +76,7 @@ That's it. The plugin auto-configures the Postman MCP Server, verifies your conn ### Search across your workspace ``` "Is there an endpoint that returns user emails?" -→ Searches private collections, drills into endpoint details, shows response shapes +→ Searches across your org's collections, drills into endpoint details, shows response shapes ``` ### Run API tests diff --git a/commands/search.md b/commands/search.md index 6ae19f2..b3aa89d 100644 --- a/commands/search.md +++ b/commands/search.md @@ -1,6 +1,6 @@ --- description: Discover APIs across your Postman workspaces. Ask natural language questions about available endpoints and capabilities. -allowed-tools: Read, Glob, Grep, mcp__postman__searchPostmanElementsInPrivateNetwork, mcp__postman__searchPostmanElementsInPublicNetwork, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getTaggedEntities, mcp__postman__getCollection, mcp__postman__getCollectionRequest, mcp__postman__getCollectionResponse, mcp__postman__getSpecDefinition +allowed-tools: Read, Glob, Grep, mcp__postman__searchPostmanElements, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getTaggedEntities, mcp__postman__getCollection, mcp__postman__getCollectionRequest, mcp__postman__getCollectionResponse, mcp__postman__getSpecDefinition --- # Discover APIs @@ -15,13 +15,20 @@ 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. +Use the unified `searchPostmanElements` tool. It searches across requests, collections, workspaces, specs, and flows in a single call. Choose `entityType`, `ownership`, and `filters` based on the user's intent. -**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. +1. Call `searchPostmanElements` with the user's query. Pick the parameters from the user's intent: + - `entityType`: `requests` (default), `collections`, `workspaces`, `specs`, or `flows`. + - `ownership`: `organization` (default — your org's resources), `external` (public Postman network, third-party APIs), or `all` (both). + - `filters`: Optional structured `$and` expression to narrow results — e.g., restrict to the Private API Network, a workspace, or HTTP method. +2. If results are sparse, broaden the search — widen `ownership` to `all`, drop or relax filters, or try a different `entityType`. You can also fall back to `getWorkspaces` + `getCollections` for browsing, or `getTaggedEntities` to find collections by tag. + +**Filter examples:** + +- Search only the trusted Private API Network: `ownership: organization` with `filters: {"$and":[{"privateNetwork":{"$eq":true}}]}` +- Find a third-party public API (e.g. "Stripe API"): `ownership: external` with `filters: {"$and":[{"visibility":{"$eq":"public"}}]}` +- Restrict to a specific workspace: `filters: {"$and":[{"workspaceId":{"$eq":"ws-abc123"}}]}` +- GET requests only: `entityType: requests` with `filters: {"$and":[{"method":{"$eq":"GET"}}]}` ### Step 2: Drill Into Results @@ -71,6 +78,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 your query. Try different keywords, broaden `ownership` to `all`, or browse the user's workspaces with `getWorkspaces` + `getCollections`." - **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`." - **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 0d9fe24..d8422e6 100644 --- a/commands/setup.md +++ b/commands/setup.md @@ -103,7 +103,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 for APIs across your org's resources or the public Postman network ``` ### Step 5: Suggest First Command diff --git a/skills/postman-context/SKILL.md b/skills/postman-context/SKILL.md index 694026f..46f1805 100644 --- a/skills/postman-context/SKILL.md +++ b/skills/postman-context/SKILL.md @@ -69,7 +69,7 @@ Meet the user where they are. The workflow below describes the full path from se ### Step 1: Find the API -**Public APIs:** For well-known third-party APIs, use `searchPostmanElementsInPublicNetwork` to search the public API network. Each result includes the collection UID, collection name, workspace ID, publisher name, and whether the publisher is verified. When presenting results, include Postman links (`https://go.postman.co/collection/`) so the user can explore in Postman if they want. +**Public APIs:** For well-known third-party APIs, use `searchPostmanElements` with `ownership: external` to search the public API network. Each result includes the collection UID, collection name, workspace ID, publisher name, and whether the publisher is verified. When presenting results, include Postman links (`https://go.postman.co/collection/`) so the user can explore in Postman if they want. **Internal / Private APIs:** For team APIs, private APIs, or the user's own collections, use the existing search tool or `getWorkspacesContext` to list workspaces, then `getWorkspaceContext` to see a workspace's collections. If the user says "my" (e.g. "my APIs", "my workspaces"), filter to personal workspaces only — this dramatically reduces noise when the team has many workspaces. diff --git a/skills/postman-knowledge/SKILL.md b/skills/postman-knowledge/SKILL.md index 48e23ec..412a6f4 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 | Use `searchPostmanElements` (set `ownership` to `organization`, `external`, or `all`), 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` (unified — set `ownership` to `organization` for org resources, `external` for the public network, or `all`; use the `privateNetwork` filter to restrict to the Private API Network), `getTaggedEntities` **User:** `getAuthenticatedUser` See `mcp-limitations.md` in this skill folder for known limitations and workarounds. From 504c430800fd012601305c8aadaa76cc7b2a64f3 Mon Sep 17 00:00:00 2001 From: chirag-yaduwanshi Date: Mon, 29 Jun 2026 17:07:27 +0530 Subject: [PATCH 2/2] Update Search tool and strategy --- commands/search.md | 2 +- skills/postman-knowledge/SKILL.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/commands/search.md b/commands/search.md index b3aa89d..a4fcc0d 100644 --- a/commands/search.md +++ b/commands/search.md @@ -15,7 +15,7 @@ The Postman MCP Server must be connected. If MCP tools aren't available, tell th ### Step 1: Search -Use the unified `searchPostmanElements` tool. It searches across requests, collections, workspaces, specs, and flows in a single call. Choose `entityType`, `ownership`, and `filters` based on the user's intent. +Use the unified `searchPostmanElements` tool. It can search across various entity types like requests, collections, workspaces, specs, flows, environments and mocks. Choose `entityType`, `ownership`, and `filters` based on the user's intent. 1. Call `searchPostmanElements` with the user's query. Pick the parameters from the user's intent: - `entityType`: `requests` (default), `collections`, `workspaces`, `specs`, or `flows`. diff --git a/skills/postman-knowledge/SKILL.md b/skills/postman-knowledge/SKILL.md index 412a6f4..581b0f7 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 | Use `searchPostmanElements` (set `ownership` to `organization`, `external`, or `all`), then drill into details | +| Find an API | Use `searchPostmanElements`, 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` (unified — set `ownership` to `organization` for org resources, `external` for the public network, or `all`; use the `privateNetwork` filter to restrict to the Private API Network), `getTaggedEntities` +**Search:** `searchPostmanElements` , `getTaggedEntities` **User:** `getAuthenticatedUser` See `mcp-limitations.md` in this skill folder for known limitations and workarounds.