caplets 0.7.0 → 0.9.0

package/README.md

@@ -1,7 +1,7 @@
 # Caplets
 
 Caplets is a progressive-disclosure gateway for Model Context Protocol (MCP) servers,
-native OpenAPI endpoints, and native GraphQL endpoints.
+native OpenAPI endpoints, native GraphQL endpoints, and explicitly configured HTTP APIs.
 
 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.
@@ -28,8 +28,8 @@ the agent chooses that server and asks to search, list, inspect, or call them.
 
 ## What It Does
 
-- 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.
+- Reads downstream MCP server definitions, native OpenAPI endpoint definitions, native GraphQL endpoint definitions, and explicit HTTP API action definitions from the user config file.
+- Registers one generated MCP tool for each enabled MCP server, OpenAPI endpoint, GraphQL endpoint, or HTTP API.
 - 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 MCP servers and loads OpenAPI specs lazily when an operation needs them.
@@ -37,6 +37,7 @@ the agent chooses that server and asks to search, list, inspect, or call them.
 - 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.
+- Converts explicitly configured HTTP actions into MCP-style tool metadata and executes HTTP calls directly.
 - 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.
@@ -58,7 +59,7 @@ pnpm build
 
 ## Configure
 
-Create a starter `~/.caplets/config.json`:
+Create a starter user config at `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms or `%APPDATA%\caplets\config.json` on Windows:
 
 ```sh
 caplets init
@@ -118,11 +119,31 @@ you want Caplets to expose:
         "issuer": "https://login.example.com"
       }
     }
+  },
+  "httpApis": {
+    "status": {
+      "name": "Status API",
+      "description": "Read deployment status from a simple HTTP API.",
+      "baseUrl": "https://api.example.com",
+      "auth": { "type": "none" },
+      "actions": {
+        "get_status": {
+          "method": "GET",
+          "path": "/status/{service}",
+          "description": "Fetch status for one service.",
+          "inputSchema": {
+            "type": "object",
+            "properties": { "service": { "type": "string" } },
+            "required": ["service"]
+          }
+        }
+      }
+    }
   }
 }
 ```
 
-The default config path can be overridden with `CAPLETS_CONFIG`:
+The default config path is `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms and `%APPDATA%\caplets\config.json` on Windows. It can be overridden with `CAPLETS_CONFIG`:
 
 ```sh
 CAPLETS_CONFIG=/path/to/config.json caplets init
@@ -150,8 +171,8 @@ 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 exactly one executable backend: `mcpServer`, `openapiEndpoint`, or
-`graphqlEndpoint`;
+file must include exactly one executable backend: `mcpServer`, `openapiEndpoint`,
+`graphqlEndpoint`, or `httpApi`;
 serverless Caplets are intentionally out of scope.
 
 Top-level files derive the Caplet ID from the filename:
@@ -208,6 +229,32 @@ graphqlEndpoint:
 # Catalog GraphQL
 ```
 
+HTTP action Caplet files use `httpApi`:
+
+```md
+---
+name: Status API
+description: Read deployment status from a simple HTTP API.
+httpApi:
+  baseUrl: https://api.example.com
+  auth:
+    type: none
+  actions:
+    get_status:
+      method: GET
+      path: /status/{service}
+      description: Fetch status for one service.
+      inputSchema:
+        type: object
+        properties:
+          service:
+            type: string
+        required: [service]
+---
+
+# Status API
+```
+
 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`.
@@ -232,11 +279,13 @@ caplets install spiritledsoftware/caplets github linear
 ```
 
 `caplets install` accepts a GitHub `owner/repo` shorthand, a Git URL, or a local repository path.
-It installs into your user Caplets root, which is `~/.caplets` by default or the parent directory
-of `CAPLETS_CONFIG` when that environment variable is set. Existing Caplets are not overwritten
-unless `--force` is passed.
+It installs into your user Caplets root, which is `${XDG_CONFIG_HOME:-~/.config}/caplets` on Unix-like platforms,
+`%APPDATA%\caplets` on Windows, or the parent directory of `CAPLETS_CONFIG` when that environment variable is set.
+Existing Caplets are not overwritten unless `--force` is passed.
+
+On Unix-like platforms, relative `XDG_CONFIG_HOME` and `XDG_STATE_HOME` values are ignored.
 
-Caplets always loads user Caplet files from `~/.caplets`. Project `./.caplets/config.json`
+Caplets always loads user Caplet files from the user Caplets root. Project `./.caplets/config.json`
 is still loaded as project config, but project Markdown Caplet files are executable
 configuration and are ignored unless explicitly trusted:
 
@@ -255,8 +304,8 @@ caplets init --force
 
 ### Caplet IDs
 
-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:
+Each key under `mcpServers`, `openapiEndpoints`, `graphqlEndpoints`, or `httpApis` is the
+stable Caplet ID. It becomes the generated MCP tool name exactly, so keep it short and specific:
 
 ```json
 {
@@ -272,7 +321,7 @@ generated MCP tool name exactly, so keep it short and specific:
 ```
 
 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.
+`openapiEndpoints`, `graphqlEndpoints`, and `httpApis`. Spaces, dots, slashes, colons, and Unicode IDs are rejected.
 
 ### Stdio Servers
 
@@ -391,6 +440,57 @@ Every GraphQL endpoint can set:
 - `selectionDepth`: maximum depth for generated selection sets. Defaults to `2`; maximum `5`.
 - `disabled`: omit the endpoint from Caplets discovery. Defaults to `false`.
 
+### HTTP APIs
+
+Use `httpApis` for simple HTTP APIs that do not have an OpenAPI spec. Each action is an
+explicitly configured tool; Caplets does not discover routes, import curl commands, or execute
+shell snippets.
+
+```json
+{
+  "name": "Status API",
+  "description": "Read and update deployment status through HTTP actions.",
+  "baseUrl": "https://api.example.com",
+  "auth": { "type": "bearer", "token": "$env:STATUS_API_TOKEN" },
+  "maxResponseBytes": 1000000,
+  "actions": {
+    "get_status": {
+      "method": "GET",
+      "path": "/status/{service}",
+      "description": "Fetch status for one service.",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "service": { "type": "string" }, "verbose": { "type": "boolean" } },
+        "required": ["service"]
+      },
+      "query": { "verbose": "$input.verbose" }
+    },
+    "set_status": {
+      "method": "POST",
+      "path": "/status/{service}",
+      "jsonBody": { "state": "$input.state", "note": "$input.note" }
+    }
+  }
+}
+```
+
+HTTP API actions support `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. `baseUrl` must be HTTPS
+except loopback URLs, must not include credentials, query, or fragment, and action `path` values
+must start with `/` and be URL paths that cannot change origin or escape the base URL path.
+
+Action mappings can set `query`, `headers`, and `jsonBody`. `query` and `headers` must resolve
+to object maps whose values are strings, numbers, or booleans. `jsonBody` may use literals,
+nested arrays/objects, `$input.field` references, or `$input` for the whole argument object.
+Path placeholders such as `{service}` are read directly from `call_tool.arguments` and URL-encoded.
+Configured action headers cannot set managed headers such as `authorization`, `host`,
+`content-length`, `connection`, or `content-type`; JSON bodies set `content-type` automatically.
+
+HTTP API auth supports `none`, `bearer`, `headers`, `oauth2`, and `oidc`, matching OpenAPI and
+GraphQL. Responses are returned as structured content with `status`, `statusText`, safe headers,
+parsed `body` when present, and `elapsedMs`; non-2xx responses set `isError`, redirects are rejected,
+timeouts are enforced, response bodies are capped by `maxResponseBytes` (default `1000000`), and
+errors redact secrets.
+
 ### Authentication
 
 Remote servers can use:
@@ -401,7 +501,7 @@ Remote servers can use:
 - `{"type": "oauth2", ...}`
 - `{"type": "oidc", ...}`
 
-For OAuth/OIDC-backed MCP, OpenAPI, and GraphQL Caplets, authenticate once with:
+For OAuth/OIDC-backed MCP, OpenAPI, GraphQL, and HTTP API Caplets, authenticate once with:
 
 ```sh
 caplets auth login <server>
@@ -413,10 +513,11 @@ For headless terminals:
 caplets auth login <server> --no-open
 ```
 
-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.
+OAuth/OIDC tokens are stored under `${XDG_STATE_HOME:-~/.local/state}/caplets/auth/<server>.json`
+on Unix-like platforms and `%LOCALAPPDATA%\caplets\auth\<server>.json` on Windows.
+Token files use 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: