caplets 0.3.0 → 0.5.0

package/README.md

@@ -1,11 +1,12 @@
 # Caplets
 
-Caplets is a progressive-disclosure gateway for Model Context Protocol (MCP) servers.
+Caplets is a progressive-disclosure gateway for Model Context Protocol (MCP) servers,
+native OpenAPI endpoints, and native GraphQL endpoints.
 
-Instead of connecting an MCP client to many downstream servers and exposing every tool up
-front, Caplets exposes one top-level tool per configured server. An agent first chooses a
-capability domain, then asks Caplets to list, search, inspect, or call that server's
-underlying tools.
+Instead of connecting an MCP client to many downstream servers or HTTP APIs and exposing
+every operation up front, Caplets exposes one top-level tool per configured capability.
+An agent first chooses a capability domain, then asks Caplets to list, search, inspect,
+or call that backend's underlying tools or operations.
 
 This keeps the initial MCP tool list small, makes tool selection easier, and avoids
 flattened tool-name collisions across servers.
@@ -27,13 +28,15 @@ the agent chooses that server and asks to search, list, inspect, or call them.
 
 ## What It Does
 
-- Reads downstream MCP server definitions from `~/.caplets/config.json`.
-- Registers one generated MCP tool for each enabled server.
+- Reads downstream MCP server definitions, native OpenAPI endpoint definitions, and native GraphQL endpoint definitions from `~/.caplets/config.json`.
+- Registers one generated MCP tool for each enabled MCP server, OpenAPI endpoint, or GraphQL endpoint.
 - Uses the configured server ID as the generated tool name.
 - Uses the configured `name` and `description` as the capability card shown to agents.
-- Starts downstream servers lazily when an operation needs them.
+- Starts downstream MCP servers and loads OpenAPI specs lazily when an operation needs them.
 - Supports stdio, Streamable HTTP, and legacy HTTP+SSE downstream servers.
-- Lets agents `list_tools`, `search_tools`, `get_tool`, and `call_tool` within one selected server namespace.
+- Lets agents `list_tools`, `search_tools`, `get_tool`, and `call_tool` within one selected Caplet namespace.
+- Converts OpenAPI operations into MCP-style tool metadata and executes HTTP calls directly.
+- Converts configured GraphQL operations into MCP-style tool metadata, and can auto-generate GraphQL tools from schema root query and mutation fields.
 - Preserves downstream tool results instead of rewriting them into a custom format.
 - Redacts secrets from structured errors.
 - Supports static remote auth and OAuth token storage for remote servers.
@@ -91,6 +94,30 @@ you want Caplets to expose:
         "token": "$env:DOCS_MCP_TOKEN"
       }
     }
+  },
+  "openapiEndpoints": {
+    "users": {
+      "name": "Users API",
+      "description": "Manage users through the internal HTTP API.",
+      "specPath": "./openapi.json",
+      "baseUrl": "https://api.example.com",
+      "auth": {
+        "type": "bearer",
+        "token": "$env:USERS_API_TOKEN"
+      }
+    }
+  },
+  "graphqlEndpoints": {
+    "catalog": {
+      "name": "Catalog GraphQL",
+      "description": "Query and update catalog records through GraphQL.",
+      "endpointUrl": "https://api.example.com/graphql",
+      "introspection": true,
+      "auth": {
+        "type": "oidc",
+        "issuer": "https://login.example.com"
+      }
+    }
   }
 }
 ```
@@ -112,8 +139,9 @@ the committed schema stays in sync with the Zod config validator.
 ### Caplet Files
 
 For richer skill-like cards, add Markdown Caplet files beside `config.json`. Every Caplet
-file must include an `mcpServer` backend; serverless Caplets are intentionally out of
-scope.
+file must include exactly one executable backend: `mcpServer`, `openapiEndpoint`, or
+`graphqlEndpoint`;
+serverless Caplets are intentionally out of scope.
 
 Top-level files derive the Caplet ID from the filename:
 
@@ -135,7 +163,41 @@ mcpServer:
 Use this Caplet for repository, issue, pull request, and code review workflows.
 ```
 
-That file is exposed as the `github` Caplet. Directory-style Caplets use
+OpenAPI-backed Caplet files use `openapiEndpoint`:
+
+```md
+---
+name: Users API
+description: Manage users through the internal HTTP API.
+openapiEndpoint:
+  specPath: ./openapi.json
+  baseUrl: https://api.example.com
+  auth:
+    type: bearer
+    token: $env:USERS_API_TOKEN
+---
+
+# Users API
+```
+
+GraphQL-backed Caplet files use `graphqlEndpoint`:
+
+```md
+---
+name: Catalog GraphQL
+description: Query and update catalog records through GraphQL.
+graphqlEndpoint:
+  endpointUrl: https://api.example.com/graphql
+  schemaPath: ./schema.graphql
+  auth:
+    type: oidc
+    issuer: https://login.example.com
+---
+
+# Catalog GraphQL
+```
+
+Top-level files derive their Caplet ID from the filename. Directory-style Caplets use
 `linear/CAPLET.md`, which is exposed as `linear`; sibling files can be referenced with
 normal Markdown links from `CAPLET.md`.
 
@@ -156,10 +218,10 @@ project `config.json`, and, only when trusted, project Caplet files.
 caplets init --force
 ```
 
-### Server IDs
+### Caplet IDs
 
-Each key under `mcpServers` is the stable server ID. It becomes the generated MCP tool
-name exactly, so keep it short and specific:
+Each key under `mcpServers` or `openapiEndpoints` is the stable Caplet ID. It becomes the
+generated MCP tool name exactly, so keep it short and specific:
 
 ```json
 {
@@ -174,8 +236,8 @@ name exactly, so keep it short and specific:
 }
 ```
 
-Server IDs must match `^[a-zA-Z0-9_-]{1,64}$`. Spaces, dots, slashes, colons, and
-Unicode IDs are rejected.
+Caplet IDs must match `^[a-zA-Z0-9_-]{1,64}$` and must be unique across `mcpServers`,
+`openapiEndpoints`, and `graphqlEndpoints`. Spaces, dots, slashes, colons, and Unicode IDs are rejected.
 
 ### Stdio Servers
 
@@ -216,6 +278,84 @@ Use `transport` and `url` for remote MCP servers.
 `transport` can be `http` for MCP Streamable HTTP or `sse` for legacy HTTP+SSE. Remote
 URLs must use `https://`, except loopback development URLs such as `http://localhost`.
 
+### OpenAPI Endpoints
+
+Use `openapiEndpoints` for native HTTP APIs described by OpenAPI 3 specs. Each entry
+points at one spec through either `specPath` or `specUrl`, and may override the request
+base URL with `baseUrl`.
+
+```json
+{
+  "name": "Users API",
+  "description": "Manage users through the internal HTTP API.",
+  "specPath": "./openapi.json",
+  "baseUrl": "https://api.example.com",
+  "auth": { "type": "none" }
+}
+```
+
+OpenAPI auth is explicit and supports:
+
+- `{"type": "none"}`
+- `{"type": "bearer", "token": "$env:TOKEN"}`
+- `{"type": "headers", "headers": {"x-api-key": "$env:API_KEY"}}`
+- `{"type": "oauth2", ...}`
+- `{"type": "oidc", ...}`
+
+OpenAPI `call_tool.arguments` uses grouped HTTP inputs:
+
+```json
+{
+  "operation": "call_tool",
+  "tool": "GET /users/{id}",
+  "arguments": {
+    "path": { "id": "42" },
+    "query": { "active": true },
+    "body": { "name": "Ada" }
+  }
+}
+```
+
+Every OpenAPI endpoint can set:
+
+- `requestTimeoutMs`: timeout for HTTP calls. Defaults to `60000`.
+- `operationCacheTtlMs`: how long OpenAPI operation metadata stays fresh. Defaults to `30000`; `0` refreshes every time.
+- `disabled`: omit the endpoint from Caplets discovery. Defaults to `false`.
+
+### GraphQL Endpoints
+
+Use `graphqlEndpoints` for native GraphQL APIs. Each entry points at a GraphQL HTTP
+endpoint and exactly one schema source: `schemaPath`, `schemaUrl`, or `introspection: true`.
+
+```json
+{
+  "name": "Catalog GraphQL",
+  "description": "Query and update catalog records through GraphQL.",
+  "endpointUrl": "https://api.example.com/graphql",
+  "schemaPath": "./schema.graphql",
+  "auth": { "type": "oidc", "issuer": "https://login.example.com" },
+  "operations": {
+    "product": {
+      "document": "query Product($id: ID!) { product(id: $id) { id name } }",
+      "operationName": "Product",
+      "description": "Fetch a product by ID."
+    }
+  }
+}
+```
+
+When `operations` is omitted or empty, Caplets auto-generates tools from schema root
+fields: `query_<field>` and `mutation_<field>`. Generated tools use bounded scalar
+selection sets and pass `call_tool.arguments` directly as GraphQL variables/root-field
+arguments.
+
+Every GraphQL endpoint can set:
+
+- `requestTimeoutMs`: timeout for HTTP calls. Defaults to `60000`.
+- `operationCacheTtlMs`: how long GraphQL operation metadata stays fresh. Defaults to `30000`; `0` refreshes every time.
+- `selectionDepth`: maximum depth for generated selection sets. Defaults to `2`; maximum `5`.
+- `disabled`: omit the endpoint from Caplets discovery. Defaults to `false`.
+
 ### Authentication
 
 Remote servers can use:
@@ -224,8 +364,9 @@ Remote servers can use:
 - `{"type": "bearer", "token": "$env:TOKEN"}`
 - `{"type": "headers", "headers": {"x-api-key": "$env:API_KEY"}}`
 - `{"type": "oauth2", ...}`
+- `{"type": "oidc", ...}`
 
-For OAuth-backed remote servers, authenticate once with:
+For OAuth/OIDC-backed MCP, OpenAPI, and GraphQL Caplets, authenticate once with:
 
 ```sh
 caplets auth login <server>
@@ -237,8 +378,9 @@ For headless terminals:
 caplets auth login <server> --no-open
 ```
 
-OAuth tokens are stored under `~/.caplets/auth/<server>.json` with owner-only file
-permissions where the platform supports them. When an OAuth token expires, run
+OAuth/OIDC tokens are stored under `~/.caplets/auth/<server>.json` with owner-only file
+permissions where the platform supports them. Caplets supports well-known OAuth/OIDC
+discovery and dynamic client registration when advertised. When a token expires, run
 `caplets auth login <server>` again.
 
 To inspect or remove stored OAuth credentials:
@@ -277,8 +419,9 @@ starts the MCP server. `serve` is explicit and recommended for clarity.
 
 ## How Agents Use It
 
-Caplets initially exposes one MCP tool per enabled Caplet. If the config has `filesystem`
-and `docs`, the client sees two top-level tools: `filesystem` and `docs`.
+Caplets initially exposes one MCP tool per enabled Caplet. If the config has `filesystem`,
+`docs`, and `users`, the client sees three top-level tools: `filesystem`, `docs`, and
+`users`.
 
 Each generated Caplet tool accepts an `operation`:
 
@@ -322,9 +465,10 @@ Call one exact downstream tool:
 Available operations:
 
 - `get_caplet`: return the configured capability card without starting the downstream server.
-- `check_mcp_server`: start or connect to the downstream server and verify its tool list.
+- `check_backend`: verify the selected backend, whether MCP, OpenAPI, or GraphQL.
+- `check_mcp_server`: start or connect to an MCP server and verify its tool list.
 - `list_tools`: return compact downstream tool metadata.
-- `search_tools`: search downstream tool names and descriptions within this server.
+- `search_tools`: search downstream tool names and descriptions within this Caplet.
 - `get_tool`: return full metadata for one exact downstream tool.
 - `call_tool`: invoke one exact downstream tool with JSON object arguments.