caplets 0.6.0 → 0.8.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 `~/.caplets/config.json`.
+- 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.
@@ -118,6 +119,26 @@ 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"]
+          }
+        }
+      }
+    }
   }
 }
 ```
@@ -138,8 +159,10 @@ caplets config paths
 caplets config paths --json
 ```
 
-Caplets validates this file at startup. Config changes take effect after restarting the
-Caplets MCP server.
+Caplets validates this file at startup and hot reloads config changes while `caplets serve`
+is running. Invalid edits are ignored until fixed, so the MCP server keeps serving the last
+known-good config instead of dropping every tool because of a transient JSON or validation
+error.
 
 The optional `$schema` field points editors at the generated JSON Schema in
 [`schemas/caplets-config.schema.json`](schemas/caplets-config.schema.json). CI verifies that
@@ -148,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:
@@ -206,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`.
@@ -253,8 +302,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
 {
@@ -270,7 +319,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
 
@@ -389,6 +438,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:
@@ -399,7 +499,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>
@@ -458,6 +558,12 @@ Configure your MCP client to run Caplets as a stdio server:
 If your client starts the configured command directly, `caplets` without arguments also
 starts the MCP server. `serve` is explicit and recommended for clarity.
 
+`caplets serve` watches the effective user config, project config, user Caplet files, and
+trusted project Caplet files. Adding, editing, disabling, or removing a Caplet updates the
+top-level MCP tool list without restarting Caplets. When an MCP-backed Caplet changes or is
+removed, Caplets closes only that affected downstream connection; unrelated Caplets and
+their downstream connections keep running.
+
 ## How Agents Use It
 
 Caplets initially exposes one MCP tool per enabled Caplet. If the config has `filesystem`,
@@ -536,9 +642,10 @@ pnpm schema:check
 pnpm verify
 ```
 
-`pnpm dev` rebuilds on source changes and restarts the local stdio MCP server from
+`pnpm dev` rebuilds Caplets source changes and restarts the local stdio MCP server from
 `dist/index.js`. Use it for local development, not as the command configured in an MCP
-client, because build logs are written to stdout.
+client, because build logs are written to stdout. Runtime config hot reload is built into
+normal `caplets serve` and does not require `pnpm dev`.
 
 ## Product Notes