zhanj/postman-claude-code-plugin
1
0
Fork 0
mirror of https://github.com/Postman-Devrel/postman-claude-code-plugin.git synced 2026-04-16 10:29:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Revert "Search Strategy update to utilise private network search"

Browse Source 
This reverts commit 4737c9f758.
This commit is contained in:
chirag-yaduwanshi
2026-03-26 11:44:43 +05:30
parent 6bfe4e99f7
commit a371f6f316
6 changed files with 30 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
README.md
View File

@@ -58,16 +58,16 @@ Get your API key at [postman.postman.co/settings/me/api-keys](https://postman.po
<img src="assets/postman-plugin-codegen.gif" alt="Postman Plugin generating code from a collection" width="800">
</p>
| 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

6
commands/codegen.md
View File

@@ -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).

15
commands/search.md
View File

@@ -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.

2
commands/setup.md
View File

@@ -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

4
skills/postman-knowledge/SKILL.md
View File

@@ -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.

6
skills/postman-knowledge/mcp-limitations.md
View File

@@ -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.