Update to current Orbit API and bundle Orbit's MCP server

.claude-plugin/marketplace.json

@@ -0,0 +1,24 @@
+{
+  "name": "orbit-marketplace",
+  "owner": {
+    "name": "Postman DevRel"
+  },
+  "metadata": {
+    "description": "Agent-friendly API discovery"
+  },
+  "plugins": [
+    {
+      "name": "orbit",
+      "source": ".",
+      "description": "Discover APIs using Postman Orbit, an agent-friendly search API designed for AI-powered app design.",
+      "version": "1.1.0",
+      "author": {
+        "name": "Postman DevRel"
+      },
+      "homepage": "https://github.com/Postman-Devrel/orbit-claudecode-plugin",
+      "repository": "https://github.com/Postman-Devrel/orbit-claudecode-plugin",
+      "keywords": ["api", "discovery", "postman", "orbit", "agent", "mcp"],
+      "category": "developer-tools"
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "orbit",
+  "version": "1.1.0",
+  "description": "Discover APIs using Postman Orbit, an agent-friendly search API designed for AI-powered app design.",
+  "author": {
+    "name": "Postman DevRel"
+  },
+  "homepage": "https://github.com/Postman-Devrel/orbit-claudecode-plugin",
+  "repository": "https://github.com/Postman-Devrel/orbit-claudecode-plugin"
+}

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "orbit": {
+      "type": "http",
+      "url": "https://mcp.buildwithorbit.ai/mcp"
+    }
+  }
+}

README.md

@@ -1,15 +1,28 @@
 # Orbit Claude Code Plugin
 
-Discover APIs from the [Postman API Network](https://www.postman.com/explore) using Postman Orbit -- an agent-friendly search API designed for AI-powered app design.
+Discover APIs using Postman Orbit, an agent-friendly search API designed for AI-powered app design.
 
 ## What is Orbit?
 
-Orbit is Postman's API discovery service built specifically for AI agent consumption. Unlike browsing the Postman API Network in a browser, Orbit returns compact, structured payloads with `evaluateGuide` fields that tell agents exactly what each API endpoint can and can't do. This lets agents make integration decisions without trial-and-error.
+Orbit is Postman's API discovery service built specifically for AI agent consumption. Unlike browsing an API catalog in a browser, Orbit returns compact, structured payloads with `evaluateGuide` fields that tell agents exactly what each API endpoint can and can't do. This lets agents make integration decisions without trial-and-error.
 
 ## Install
 
 ```bash
-claude plugin add Postman-Devrel/orbit-claudecode-plugin
+claude plugin marketplace add Postman-Devrel/orbit-claudecode-plugin
+claude plugin install orbit@orbit-marketplace
+```
+
+The plugin bundles Orbit's MCP server, so there's nothing else to configure -- no API
+key, no `claude mcp add`. Installing the plugin wires up the `search` and `integrate`
+tools, and the skill drives them.
+
+Then run `/orbit:discover <capability>` in a new session.
+
+To hack on it locally without installing, point Claude Code at a checkout:
+
+```bash
+claude --plugin-dir ./orbit-claudecode-plugin
 ```
 
 ## Usage
@@ -28,14 +41,16 @@ Search for multiple capabilities at once:
 
 For each matching API, Orbit returns:
 
-- **Name** and **description** of the endpoint
+- **Name**, **description**, and **provider** of the endpoint
 - **Method** and **URL** for the API call
 - **evaluateGuide** -- structured guidance covering:
   - What the endpoint does
   - What it's best used for
   - What it does not support
 
-Results are saved to `orbit-output/` as markdown files for reference.
+Once you've picked endpoints, Orbit can also generate a **task brief** -- the auth
+requirements, base URLs, ordered request steps, and gotchas needed to write the
+integration.
 
 ## Design process
 
@@ -49,10 +64,24 @@ Orbit works best when you use it at the start of a project to build an API bluep
 
 4. **Iterate.** Use those gaps as your next round of queries. "Find me APIs that handle payment refunds" or "I need an auth provider that supports token refresh." Each round narrows the design.
 
-5. **Save the blueprint.** The agent saves results to `orbit-output/` as a structured file you can reference throughout the project. This becomes your API design document, readable by both humans and agents.
+5. **Get the task brief.** Once the endpoint set is settled, the agent sends the selected endpoints plus your task to Orbit's integrate endpoint and gets back a brief covering auth, base URLs, and the request sequence -- the implementation plan, before you write code.
 
 The goal is to make API selection decisions intentionally at design time, not discover limitations mid-sprint after you've already integrated half the stack.
 
+## How it works
+
+The plugin is a thin workflow layer over Orbit's MCP server:
+
+| | Provided by |
+|---|---|
+| `search` / `integrate` tools, request + response schemas | Orbit's MCP server (bundled) |
+| Capability decomposition, gap analysis, iteration | This plugin's skill |
+
+Keeping the API contract on the server side means Orbit can change its parameters
+without breaking installed copies of the plugin. If the MCP server is ever
+unreachable, the skill falls back to the documented REST endpoints in
+[references/orbit-api.md](skills/discover/references/orbit-api.md).
+
 ## Orbit vs postman:search
 
 | | Orbit (`orbit:discover`) | Postman Search (`postman:search`) |
@@ -64,5 +93,6 @@ The goal is to make API selection decisions intentionally at design time, not di
 
 ## Links
 
-- [Postman API Network](https://www.postman.com/explore)
+- [Orbit documentation](https://www.buildwithorbit.ai/)
+- [Orbit API reference](https://www.buildwithorbit.ai/api-reference)
 - [Claude Code Plugins](https://docs.anthropic.com/en/docs/claude-code/plugins)

skills/discover/SKILL.md

@@ -1,11 +1,19 @@
 ---
-description: "Discover APIs from the Postman API Network using Orbit's agent-friendly search. Returns endpoints with evaluateGuide fields showing what each API can and can't do."
-allowed-tools: ["Bash", "Write", "Read"]
+description: "Discover APIs using Orbit's agent-friendly search. Returns endpoints with evaluateGuide fields showing what each API can and can't do, and can generate an integration task brief for the ones you pick."
+allowed-tools:
+  - "mcp__plugin_orbit_orbit__search"
+  - "mcp__plugin_orbit_orbit__integrate"
+  - "Bash"
+  - "Read"
 ---
 
 # orbit:discover
 
-Search the Postman API Network for APIs matching a capability query.
+Search Orbit for APIs matching a capability query, then generate an
+integration task brief for the endpoints you select.
+
+This plugin bundles Orbit's MCP server, so the `search` and `integrate` tools are
+available without setup. No authentication is required.
 
 ## Input
 
@@ -14,23 +22,54 @@ Multiple capabilities: comma-separated or as separate arguments.
 
 ## Steps
 
-1. Read `references/orbit-api.md` for the API contract.
-2. For each capability query, POST to the Orbit search endpoint using curl.
-3. Parse the JSON response. For each result, extract:
-   - `name`, `method`, `url`
-   - `evaluateGuide` — the agent-oriented breakdown of what the endpoint does, what it's good for, and what it doesn't support
-4. Format results as a readable markdown table or list grouped by capability.
-5. Save output to `orbit-output/<slugified-query>.md`.
-6. Present a summary to the user highlighting the top matches and their evaluateGuide insights.
+1. **Decompose.** Break the request into one focused capability query per intent. Run
+   each as a separate `search` call — do not cram intents into one query.
+
+2. **Search.** Call `mcp__plugin_orbit_orbit__search` for each capability:
+   - `q` — the query (required, max 512 chars)
+   - `limit` — results per page (default 10, max 25)
+   - `clientName` — pass `"claude-code/orbit-plugin"` for anonymous usage analytics
+
+   Query style matters. Include the product or provider name alongside the endpoint
+   detail: `"PayPal create invoice"` or `"PayPal API to create an invoice"`. Avoid
+   jumbled keyword piles (`"paypal invoice payment delivery ordering"`) and avoid
+   `OR`-separated queries — run separate calls instead.
+
+3. **Extract.** For each result in `data`, keep:
+   - `id` — the `urn:orbit:endpoint:v1:...` identifier. Preserve it verbatim; step 5
+     needs it. Never parse, edit, or construct one.
+   - `resourceType` — needed as `type` in step 5
+   - `name`, `method`, `url`, `provider`
+   - `evaluateGuide` — the three-part breakdown: summary, `Use for:`, `Not supported:`
+
+4. **Paginate if needed.** If `meta.nextCursor` is present, call `search` again with
+   `cursor` set to that value. `nextCursor` is *absent* on the last page, not null.
+   Pagination caps at 40 results per query.
+
+5. **Integrate.** When the user has a concrete task and the endpoint set looks right,
+   call `mcp__plugin_orbit_orbit__integrate`:
+   - `task` — what they're building (required, max 512 chars)
+   - `resources` — entries of `{id, type}`, where `id` and `type` come from a search
+     result's `id` and `resourceType`. The schema allows up to 10, but **keep calls
+     narrow — 2 or 3 related endpoints**. Wide calls have been observed to return a
+     one-line restatement instead of a real brief. To cover more endpoints, make
+     several focused calls grouped by sub-task rather than one wide call.
+
+   The returned `taskBrief` covers auth requirements, base URLs, ordered request steps,
+   parameters, inter-step dependencies, and gotchas.
+
+6. **Summarize.** Present the top matches to the user, leading with the
+   `Not supported:` lines — those are the design gaps worth acting on.
 
 ## Output format
 
 For each API result:
 
 ```
-### <name>
+### <name> (<provider>)
 - **Method:** <method>
 - **URL:** <url>
+- **ID:** <id>
 - **Evaluate Guide:** <evaluateGuide summary>
 ```
 
@@ -39,5 +78,16 @@ Group results under `## <capability query>` headings when multiple queries are r
 ## Notes
 
 - If a query returns zero results, say so — don't fabricate endpoints.
-- The `evaluateGuide` field is the key value: it tells you what an API is good for and what it can't do, saving trial-and-error.
-- Orbit is designed for agent consumption (compact payloads, structured guidance) vs human browsing on the Postman API Network website.
+- Never construct or edit an `id`. Pass search `id`s to `integrate` byte-for-byte.
+- The `evaluateGuide` field is the key value: it tells you what an API is good for and
+  what it can't do, saving trial-and-error.
+- Both tools are read-only and safe to retry. On a rate-limit error, back off and retry.
+- Orbit is designed for agent consumption (compact payloads, structured guidance) vs
+  human browsing of an API catalog in a web UI.
+
+## Fallback
+
+If the MCP tools are unavailable — the server is unreachable, or you're running in an
+environment where the plugin's MCP server did not load — read
+`references/orbit-api.md` and call the equivalent REST endpoints with curl. The
+request and response shapes are identical.