diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..423d695 --- /dev/null +++ b/.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" + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..0e9a488 --- /dev/null +++ b/.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" +} diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..d736b0c --- /dev/null +++ b/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "orbit": { + "type": "http", + "url": "https://mcp.buildwithorbit.ai/mcp" + } + } +} diff --git a/README.md b/README.md index 0316c35..8a59c82 100644 --- a/README.md +++ b/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 ` 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) diff --git a/plugin.json b/plugin.json deleted file mode 100644 index bc0215a..0000000 --- a/plugin.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "name": "orbit", - "version": "1.0.0", - "description": "Discover APIs from the Postman API Network using Postman Orbit, an agent-friendly search API designed for AI-powered app design.", - "skills": "./skills/" -} diff --git a/skills/discover/SKILL.md b/skills/discover/SKILL.md index 052d47c..e0807d1 100644 --- a/skills/discover/SKILL.md +++ b/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/.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: ``` -### +### () - **Method:** - **URL:** +- **ID:** - **Evaluate Guide:** ``` @@ -39,5 +78,16 @@ Group results under `## ` 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. diff --git a/skills/discover/references/orbit-api.md b/skills/discover/references/orbit-api.md index 07591b7..eaf7864 100644 --- a/skills/discover/references/orbit-api.md +++ b/skills/discover/references/orbit-api.md @@ -1,78 +1,230 @@ -# Orbit API Reference +# Orbit API Reference — REST fallback -## Endpoint +Docs: https://www.buildwithorbit.ai/api-reference +OpenAPI: https://www.buildwithorbit.ai/openapi.json -``` -POST https://fabric-gateway.postmanlabs.com/api/search -Content-Type: application/json -``` +> **Prefer the MCP tools.** This plugin bundles Orbit's MCP server, so +> `mcp__plugin_orbit_orbit__search` and `mcp__plugin_orbit_orbit__integrate` are +> normally available and carry live, self-describing schemas. Use the REST calls below +> only when those tools are unavailable. See [MCP tools](#mcp-tools) at the end for the +> mapping. + +**Base URL:** `https://api.buildwithorbit.ai` + +No authentication is required. Only `Content-Type: application/json` is needed. + +There are two endpoints: `/v1/search` finds candidate endpoints, `/v1/integrate` turns +the ones you pick into a task brief. + +--- + +## POST /v1/search + +Describe your goal in `q`. Returns matching public endpoints, each with an +`evaluateGuide` explaining what it does, when to use it, and its limitations. -## Request +### Query parameters + +| Parameter | Type | Default | Notes | +|-----------|------|---------|-------| +| `limit` | integer | 10 | Results per page. Min 1, max 25. | +| `cursor` | string | — | Pass `meta.nextCursor` from the previous response. Omit for the first page. | + +### Request body + +| Field | Type | Required | Notes | +|-------|------|----------|-------| +| `q` | string | Yes | Natural language query, keywords, an API name, or a question. 1–512 characters. | + +`q` is the only accepted body field — unknown fields return `400`. ```json -{ - "q": "your search query" -} +{ "q": "Add tracking details for an existing paypal order" } ``` -The query should describe the capability you need — e.g., "payment processing for subscriptions", "send transactional email", "geocoding addresses". - -## Example curl +### Example curl ```bash -curl -s -X POST https://fabric-gateway.postmanlabs.com/api/search \ - -H "Content-Type: application/json" \ +curl -s -X POST 'https://api.buildwithorbit.ai/v1/search?limit=10' \ + -H 'Content-Type: application/json' \ -d '{"q": "payment processing"}' | jq . ``` -## Response schema +### Response (200) ```json { "data": [ { - "id": "string", - "name": "string", + "id": "urn:orbit:endpoint:v1:...:brevo:send-a-transactional-ema", + "resourceType": "endpoint", + "name": "Send a transactional email", "description": "string", - "method": "GET | POST | PUT | PATCH | DELETE", - "url": "string (the API endpoint URL)", - "evaluateGuide": "string (agent-oriented usage guidance)" + "method": "POST", + "url": "https://api.brevo.com/v3/smtp/email", + "evaluateGuide": "string", + "provider": "Brevo", + "product": "Brevo" } ], "meta": { - "q": "string (echo of search query)", - "total": "number (total matching results)", - "nextCursor": "string | null (pagination cursor)" + "q": "send transactional email", + "total": 2, + "nextCursor": "eyJmcm9tIjoyfQ==" } } ``` -## Field descriptions - | Field | Description | |-------|-------------| -| `id` | Unique identifier for the API endpoint | +| `id` | Opaque identifier of the form `urn:orbit:endpoint:v1:...`. Pass it back verbatim to `/v1/integrate` — never parse or construct it. | +| `resourceType` | Kind of entity, e.g. `endpoint`. Pass it to `/v1/integrate` as the resource's `type`. | | `name` | Human-readable name of the endpoint | -| `description` | Brief description of what the endpoint does | -| `method` | HTTP method (GET, POST, PUT, PATCH, DELETE) | -| `url` | The API endpoint URL | -| `evaluateGuide` | Agent-oriented guidance — what the endpoint does, what it's good for ("Use for"), and what it can't do ("Not supported"). This is the key differentiator for AI agent consumption | +| `description` | What the endpoint does (may be empty) | +| `method` | HTTP method used to call the endpoint | +| `url` | URL the endpoint is called at | +| `evaluateGuide` | Three-part evaluation: brief summary, recommended use cases, unsupported use cases/limitations | +| `provider` / `product` | Owning provider and product (returned by the live API; not in the published OpenAPI spec, so treat as optional) | -## The evaluateGuide field +`meta` carries `q`, `total`, and `nextCursor`. **`nextCursor` is absent on the last +page** — check for its presence rather than comparing to `null`. + +### Pagination + +Pass `nextCursor` as the `cursor` **query parameter** (not a body field): + +```bash +curl -s -X POST 'https://api.buildwithorbit.ai/v1/search?cursor=eyJmcm9tIjoyfQ==' \ + -H 'Content-Type: application/json' \ + -d '{"q": "payment processing"}' +``` + +Pagination stops at 40 results total; a cursor past 40 is rejected. + +### Errors -The `evaluateGuide` is what makes Orbit results agent-friendly. It provides structured guidance so an AI agent can quickly decide whether an API fits its needs without trial-and-error: +`400` invalid input · `429` rate limited · `500` server error. +Error bodies are RFC 9457 problem details: `type`, `title`, `status`, `detail`, `instance`. -- **What it does** — a concise description of the endpoint's purpose -- **Use for** — specific scenarios where this endpoint is the right choice -- **Not supported** — capabilities this endpoint does not cover, preventing wasted integration effort +--- -## Pagination +## POST /v1/integrate -When `meta.nextCursor` is non-null, pass it as `"cursor"` in the next request body to fetch more results: +After selecting endpoints from `/v1/search`, send them here along with the task you +want to accomplish. Returns a **task brief** with the information and steps needed to +call those endpoints. + +Takes no query parameters. + +### Request body + +| Field | Type | Required | Notes | +|-------|------|----------|-------| +| `task` | string | Yes | What you want to accomplish. 1–512 characters, must contain non-whitespace. | +| `resources` | array | Yes | Endpoints to integrate, 1–10 items. Each item needs `id` and `type`. The MCP tool schema enforces a max of 10; the published OpenAPI spec omits the limit, so assume it applies to REST too and split larger sets across calls. | +| `resources[].id` | string | Yes | The `id` from a `/v1/search` result, verbatim. | +| `resources[].type` | string | Yes | The result's `resourceType`. Currently only `endpoint`. | ```json { - "q": "payment processing", - "cursor": "value-from-nextCursor" + "task": "Build an app to post current weather to Slack", + "resources": [ + { "id": "urn:orbit:endpoint:v1:...:weatherapi-com:current-weather-json", "type": "endpoint" }, + { "id": "urn:orbit:endpoint:v1:...:slack:send-message-to-slack", "type": "endpoint" } + ] } ``` + +### Example curl + +```bash +curl -s -X POST https://api.buildwithorbit.ai/v1/integrate \ + -H 'Content-Type: application/json' \ + -d '{ + "task": "Send a transactional email when a user signs up", + "resources": [ + { "id": "urn:orbit:endpoint:v1:...:sendmux:send-a-single-email", "type": "endpoint" } + ] + }' | jq -r '.data[0].taskBrief' +``` + +### Response (200) + +```json +{ + "data": [ + { "taskBrief": "string" } + ] +} +``` + +The `taskBrief` is a multi-line document covering FIT, AUTH (including which +credentials you must supply), BASE URL, STEPS with parameters and expected responses, +dependencies between steps, and important considerations. It is built from the +selected endpoints' schemas plus shared variables, auth settings, and descriptions +defined by their parent APIs. + +### Errors + +`400` invalid input · `404` none of the `id`s could be resolved · `429` rate limited · +`500` server error. + +--- + +## Idempotency + +Both endpoints are read-only and never create or mutate data, so retries are safe and +no idempotency key is needed. Search results may change as the public catalog changes; +task brief wording may vary between otherwise identical calls. + +## The evaluateGuide field + +`evaluateGuide` is what makes Orbit results agent-friendly. It is a newline-separated +string in three parts, so an agent can decide whether an API fits without +trial-and-error: + +- **Summary** — a concise description of the endpoint's purpose +- **`Use for:`** — specific scenarios where this endpoint is the right choice +- **`Not supported:`** — capabilities this endpoint does not cover, preventing wasted + integration effort + +Example: + +``` +Sends a transactional email through Brevo's SMTP API, enabling an agent to deliver an email payload to recipients. +Use for: send transactional messages, deliver notifications, send account emails +Not supported: inbound email processing, contact management, campaign analytics +``` + +--- + +## MCP tools + +The plugin bundles Orbit's MCP server (`https://mcp.buildwithorbit.ai/mcp`, HTTP +transport, no auth) via `.mcp.json`. It exposes two tools that map one-to-one onto the +REST endpoints and return identical payloads: + +| MCP tool | REST equivalent | +|----------|-----------------| +| `mcp__plugin_orbit_orbit__search` | `POST /v1/search` | +| `mcp__plugin_orbit_orbit__integrate` | `POST /v1/integrate` | + +Differences from REST: + +- `limit` and `cursor` are ordinary tool arguments, not query parameters. +- Both tools accept an optional `clientName` string for anonymous usage analytics. + Pass `"claude-code/orbit-plugin"`. +- `integrate` declares `resources` as 1–10 items in its schema. + +The tool schemas are the authoritative contract — they are fetched live from the +server, so they stay correct even when this file drifts. + +### Query guidance (from the tool description) + +- Use focused keyword queries including the product or provider name plus the endpoint + detail — e.g. `"PayPal create invoice"`. +- Natural language works too — e.g. `"PayPal API to create an invoice"`. +- Avoid jumbled queries cramming unrelated keywords together — e.g. + `"paypal invoice payment delivery payments ordering"`. +- Avoid `OR`-separated queries — e.g. `"paypal invoice OR paypal create invoice"`. +- To explore multiple intents, make a separate call per intent.