caplets 0.13.0 → 0.15.0

package/README.md

@@ -103,6 +103,33 @@ The Claude Code and Codex commands install from this GitHub repository through e
 plugin marketplace flow; users do not need to clone the repository manually. Plugin MCP
 configs run `caplets serve` directly, so install the Caplets CLI globally first.
 
+### Remote Caplets service
+
+OpenCode and Pi can use native `caplets_<id>` tools backed by a remote Caplets HTTP service. Codex, Claude Code, and any MCP client can connect to the same remote MCP endpoint directly.
+
+Start a local HTTP service:
+
+```sh
+caplets serve --transport http --host 127.0.0.1 --port 5387 --path /mcp
+```
+
+`caplets serve --transport http` serves plain HTTP. For non-loopback or network access, expose it only through HTTPS/TLS (for example, a reverse proxy or secure tunnel) and enable Basic Auth; Basic Auth over plain HTTP exposes credentials. Keep credentials out of plugin manifests:
+
+```sh
+CAPLETS_SERVER_PASSWORD=... caplets serve --transport http --host 127.0.0.1 --port 5387 --path /mcp
+```
+
+Native integrations read remote client settings from environment variables:
+
+```sh
+CAPLETS_REMOTE_URL=https://caplets.example.com/mcp \
+CAPLETS_REMOTE_USER=caplets \
+CAPLETS_REMOTE_PASSWORD=... \
+opencode
+```
+
+For MCP-backed Codex or Claude Code configs, point the agent's MCP server entry at the remote URL using that agent's supported HTTP MCP configuration. If Basic Auth is needed, use the agent's secure secret or environment interpolation mechanism rather than hardcoding credentials.
+
 ## Convert Existing Tooling
 
 Caplets is designed to convert what you already use into agent-friendly capability domains.
@@ -914,6 +941,26 @@ Available operations:
 Requests are strict: operation-specific extra fields are rejected, and `call_tool` requires
 `arguments` to be a JSON object.
 
+Discovery operations (`get_caplet`, `check_backend`, `list_tools`, `search_tools`, and
+`get_tool`) return wrapper-generated results whose `structuredContent.caplets` field
+identifies the Caplet with `id`, plus backend, operation, status, and elapsed time when
+available. Discovery result objects and compact tool entries also use `id` for the
+configured Caplet identity. Compact `list_tools` and `search_tools` entries may include
+input/output schema hashes; treat those
+hashes as reuse hints for a schema you have already inspected, not as a replacement for
+`get_tool` when arguments, output, or semantics are unclear.
+
+Direct `call_tool` preserves the downstream tool result shape instead of wrapping it in
+`structuredContent.result`. When the result can carry MCP metadata, Caplets adds
+`_meta.caplets` with the same call context and status. It may also include artifact metadata
+for paths mentioned by downstream content, such as screenshots, snapshots, logs, downloads,
+or other saved files. Artifact `displayPath` values are either absolute local paths or
+relative to the downstream MCP server process, not necessarily relative to the current
+project or Caplets process.
+
+For first use, the explicit progressive-discovery path is still safest: choose a Caplet,
+`search_tools` or `list_tools`, inspect uncertain tools with `get_tool`, then `call_tool`.
+
 ## Development
 
 ```sh