Skip to content

feat: add google discovery api backends #126

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ian-pascoe wants to merge 7 commits into
base: main
Choose a base branch
from
Open

feat: add google discovery api backends #126

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
10ee981
feat: support google discovery backends
ian-pascoe Jun 16, 2026
ff68941
fix: address google discovery review feedback
ian-pascoe Jun 16, 2026
b137ec3
fix: resolve discovery scopes for remote auth
ian-pascoe Jun 16, 2026
8f39ac6
fix: harden google discovery review paths
ian-pascoe Jun 16, 2026
4d6c21b
fix: finish google discovery review follow-ups
ian-pascoe Jun 16, 2026
a9e2812
fix: harden google discovery auth follow-ups
ian-pascoe Jun 17, 2026
0f8e13f
fix: cover google discovery upload edge cases
ian-pascoe Jun 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .changeset/google-discovery-media.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
"@caplets/core": minor
"caplets": minor
"@caplets/opencode": minor
"@caplets/pi": minor
---

Add Google Discovery API Caplets with inferred OAuth scopes, operation filters, media upload/download handling, and shared HTTP-like media artifacts.
13 changes: 13 additions & 0 deletions CONTEXT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Caplets

Caplets is a capability gateway for coding agents. This glossary names the product concepts used when describing Caplet configuration and runtime behavior.

## Language

**Google Discovery API backend**:
A Caplets backend family for Google APIs whose machine-readable contract is a Google Discovery document rather than an OpenAPI document.
_Avoid_: Discovery backend, discovery document backend, OpenAPI-backed Google API

**Media artifact**:
A file-backed Caplets result for response content that should not be returned inline, such as binary media or oversized textual content.
_Avoid_: Inline blob, base64 result, download blob
14 changes: 12 additions & 2 deletions apps/docs/src/content/docs/capabilities.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,9 @@ title: Capabilities
description: Add capability sources for agents.
---

Caplets can wrap MCP servers, OpenAPI specs, GraphQL endpoints, simple HTTP APIs, curated
CLI commands, and shared Markdown Caplet files such as `CAPLET.md`.
Caplets can wrap MCP servers, OpenAPI specs, Google Discovery APIs, GraphQL endpoints,
simple HTTP APIs, curated CLI commands, and shared Markdown Caplet files such as
`CAPLET.md`.

## Start with OSV

Expand All @@ -30,11 +31,16 @@ Examples:
```sh
caplets add mcp docs --command npx --arg -y --arg @upstash/context7-mcp
caplets add openapi users --spec ./openapi.json --base-url https://api.example.com
caplets add google-discovery drive --discovery-url https://www.googleapis.com/discovery/v1/apis/drive/v3/rest
caplets add graphql catalog --endpoint-url https://api.example.com/graphql --schema ./schema.graphql
caplets add http status-api --base-url https://api.example.com --action get_status:GET:/status/{service}
caplets add cli repo-tools --repo . --include git,gh,package
```

Google Discovery Caplets use Google's Discovery documents directly. They can infer request
base URLs and OAuth scopes from the final exposed operation set, so narrow broad APIs with
`includeOperations` and `excludeOperations` when a capability only needs a subset.

Inspect from the CLI:

```sh
Expand All @@ -50,5 +56,9 @@ caplets call-tool osv query_package_version --args '{"ecosystem":"npm","name":"r
Good Caplets are narrow and named by the job they help an agent do. Prefer a few focused
capabilities over one broad catch-all backend.

HTTP-like Caplets return small JSON and text inline. Binary downloads, Google media
downloads, and oversized responses are returned as media artifact metadata with local paths
or artifact references that agents can pass into later upload calls.

Use [Configuration](/configuration/) when a capability should be shared through
`.caplets/config.json`.
39 changes: 20 additions & 19 deletions apps/docs/src/content/docs/reference/caplet-files.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,25 +58,26 @@ Use this Caplet when an agent needs the current repository's local test signal.

## Top-level fields

| Field | Status | Type | Description |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `$schema` | Optional | string | Optional JSON Schema URL for editor validation. |
| `name` | Required | string | Human-readable Caplet display name. |
| `description` | Required | string | Compact capability description shown before the full Caplet card is disclosed. |
| `tags` | Optional | array | Optional tags for grouping or searching Caplets. |
| `exposure` | Optional | "direct" \| "progressive" \| "code_mode" \| "direct_and_code_mode" \| "progressive_and_code_mode" | How this Caplet is exposed to agents. |
| `shadowing` | Optional | "forbid" \| "allow" | Whether attached local Caplets may shadow this remote Caplet ID. |
| `useWhen` | Optional | string | When agents should prefer this Caplet or configured action. |
| `avoidWhen` | Optional | string | When agents should avoid this Caplet or configured action. |
| `setup` | Optional | object | Optional explicit setup and verification metadata for this Caplet. |
| `projectBinding` | Optional | object | Project Binding requirements for Caplets that need an attached project. |
| `runtime` | Optional | object | Runtime feature and resource requirements for hosted execution. |
| `mcpServer` | Optional | object | MCP server backend configuration for this Caplet. |
| `openapiEndpoint` | Optional | object | OpenAPI endpoint backend configuration for this Caplet. |
| `graphqlEndpoint` | Optional | object | GraphQL endpoint backend configuration for this Caplet. |
| `httpApi` | Optional | object | HTTP API backend configuration for this Caplet. |
| `cliTools` | Optional | object | CLI tools backend configuration for this Caplet. |
| `capletSet` | Optional | object | Nested Caplet collection backend configuration for this Caplet. |
| Field | Status | Type | Description |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `$schema` | Optional | string | Optional JSON Schema URL for editor validation. |
| `name` | Required | string | Human-readable Caplet display name. |
| `description` | Required | string | Compact capability description shown before the full Caplet card is disclosed. |
| `tags` | Optional | array | Optional tags for grouping or searching Caplets. |
| `exposure` | Optional | "direct" \| "progressive" \| "code_mode" \| "direct_and_code_mode" \| "progressive_and_code_mode" | How this Caplet is exposed to agents. |
| `shadowing` | Optional | "forbid" \| "allow" | Whether attached local Caplets may shadow this remote Caplet ID. |
| `useWhen` | Optional | string | When agents should prefer this Caplet or configured action. |
| `avoidWhen` | Optional | string | When agents should avoid this Caplet or configured action. |
| `setup` | Optional | object | Optional explicit setup and verification metadata for this Caplet. |
| `projectBinding` | Optional | object | Project Binding requirements for Caplets that need an attached project. |
| `runtime` | Optional | object | Runtime feature and resource requirements for hosted execution. |
| `mcpServer` | Optional | object | MCP server backend configuration for this Caplet. |
| `openapiEndpoint` | Optional | object | OpenAPI endpoint backend configuration for this Caplet. |
| `googleDiscoveryApi` | Optional | object | Google Discovery API backend configuration for this Caplet. |
| `graphqlEndpoint` | Optional | object | GraphQL endpoint backend configuration for this Caplet. |
| `httpApi` | Optional | object | HTTP API backend configuration for this Caplet. |
| `cliTools` | Optional | object | CLI tools backend configuration for this Caplet. |
| `capletSet` | Optional | object | Nested Caplet collection backend configuration for this Caplet. |

## Major sections

Expand Down
29 changes: 15 additions & 14 deletions apps/docs/src/content/docs/reference/config.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,20 +62,21 @@ Public OpenAPI endpoint:

## Top-level fields

| Field | Status | Type | Description |
| -------------------- | -------- | ------- | ------------------------------------------------------ |
| `$schema` | Optional | string | Optional JSON Schema URL for editor validation. |
| `version` | Optional | number | Caplets config schema version. |
| `defaultSearchLimit` | Optional | integer | Default maximum number of same-server search results. |
| `maxSearchLimit` | Optional | integer | Maximum accepted search_tools limit. |
| `completion` | Optional | object | Shell completion discovery timeout and cache settings. |
| `options` | Optional | object | Global Caplets runtime options. |
| `mcpServers` | Optional | object | Downstream MCP servers keyed by stable server ID. |
| `openapiEndpoints` | Optional | object | OpenAPI endpoints keyed by stable Caplet ID. |
| `graphqlEndpoints` | Optional | object | GraphQL endpoints keyed by stable Caplet ID. |
| `httpApis` | Optional | object | HTTP APIs keyed by stable Caplet ID. |
| `cliTools` | Optional | object | CLI tools keyed by stable Caplet ID. |
| `capletSets` | Optional | object | Nested Caplet collections keyed by stable Caplet ID. |
| Field | Status | Type | Description |
| --------------------- | -------- | ------- | ------------------------------------------------------ |
| `$schema` | Optional | string | Optional JSON Schema URL for editor validation. |
| `version` | Optional | number | Caplets config schema version. |
| `defaultSearchLimit` | Optional | integer | Default maximum number of same-server search results. |
| `maxSearchLimit` | Optional | integer | Maximum accepted search_tools limit. |
| `completion` | Optional | object | Shell completion discovery timeout and cache settings. |
| `options` | Optional | object | Global Caplets runtime options. |
| `mcpServers` | Optional | object | Downstream MCP servers keyed by stable server ID. |
| `openapiEndpoints` | Optional | object | OpenAPI endpoints keyed by stable Caplet ID. |
| `googleDiscoveryApis` | Optional | object | Google Discovery APIs keyed by stable Caplet ID. |
| `graphqlEndpoints` | Optional | object | GraphQL endpoints keyed by stable Caplet ID. |
| `httpApis` | Optional | object | HTTP APIs keyed by stable Caplet ID. |
| `cliTools` | Optional | object | CLI tools keyed by stable Caplet ID. |
| `capletSets` | Optional | object | Nested Caplet collections keyed by stable Caplet ID. |

## Major sections

Expand Down
26 changes: 26 additions & 0 deletions apps/docs/src/content/docs/troubleshooting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,32 @@ return await h.callTool("query_package_version", {
Use the returned `error.code`, `error.message`, and Caplet ID to repair the call. Do not
paste a full raw downstream payload back to the agent unless the error depends on it.

### Google auth asks for login again

Expected symptom: a Google Discovery Caplet worked before, but `auth login` or a tool call
now reports missing scopes after you changed operation filters or the Discovery document.

Google Discovery Caplets infer OAuth scopes from the exposed operation set unless
`auth.scopes` is configured. Re-run login for that Caplet so the stored token metadata
matches the current scope set:

```sh
caplets auth login <caplet-id>
caplets doctor
```

If the Caplet should never ask for newly inferred scopes, configure `auth.scopes`
explicitly and keep `includeOperations` narrow.

### Download returned an artifact

Expected symptom: a tool result contains `body.artifact` instead of inline bytes or text.

Binary downloads, Google media downloads, and oversized HTTP-like responses are written as
Caplets media artifacts. Use the artifact `path` locally, or pass the artifact URI back to
another media-capable tool as `media.artifact`. If you need a specific destination for a
download, retry with `filename` or `outputPath` when the tool schema exposes those fields.

### Remote attach fails

Expected symptom: remote mode starts, but attach cannot reach the runtime or authenticate.
Expand Down
Loading