caplets 0.15.0 → 0.17.0

package/README.md

@@ -30,6 +30,10 @@ Instead of exposing a flat wall of tools, Caplets shows one top-level tool per c
 The agent chooses a domain first, then uses scoped operations like `search_tools`,
 `get_tool`, and `call_tool` only when it needs more detail.
 
+For MCP-backed Caplets, the scoped operation set also includes resource discovery/reading,
+prompt listing/rendering, resource-template discovery, and completion for prompt or template
+arguments. Non-MCP backends continue to expose only tool/action operations.
+
 ## Quick Start
 
 Caplets requires Node.js 22 or newer.
@@ -76,10 +80,47 @@ caplets list-tools context7
 caplets get-tool context7.resolve-library-id
 caplets call-tool context7.resolve-library-id --args '{"libraryName":"react"}'
 caplets call-tool context7.resolve-library-id --args '{"libraryName":"react"}' --field result.id --format json
+caplets list-resources docs
+caplets read-resource docs file:///repo/README.md
+caplets list-prompts linear
+caplets get-prompt linear.review_issue --args '{"issueId":"CAP-123"}'
+caplets complete docs --resource-template 'file:///repo/{path}' --argument path --value src/
 ```
 
 Direct CLI operation commands print Markdown summaries by default. Add `--format plain` for plain text or `--format json` for machine-readable JSON (`md` is accepted as an alias for `markdown`). If a downstream tool returns `isError: true`, Caplets still exits with status code 1.
 
+### Shell completions
+
+The npm package ships shell completion generators for Bash, Zsh, Fish, PowerShell, and cmd. Installation is explicit: `npm install -g caplets` does not modify shell startup files or system completion directories.
+
+```sh
+# Bash
+mkdir -p ~/.local/share/bash-completion/completions
+caplets completion bash > ~/.local/share/bash-completion/completions/caplets
+
+# Zsh
+mkdir -p ~/.zsh/completions
+caplets completion zsh > ~/.zsh/completions/_caplets
+# Ensure ~/.zsh/completions is on fpath before compinit, then reload your shell:
+# echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
+# echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
+
+# Fish
+mkdir -p ~/.config/fish/completions
+caplets completion fish > ~/.config/fish/completions/caplets.fish
+
+# PowerShell
+caplets completion powershell | Out-String | Invoke-Expression
+
+# cmd.exe
+caplets completion cmd > %USERPROFILE%\caplets-completion.cmd
+%USERPROFILE%\caplets-completion.cmd
+```
+
+Completions include command names, options, common enum values, configured Caplet IDs, and cache-backed downstream names for qualified targets such as `caplets call-tool repo.<TAB>`. Downstream discovery is bounded by the `completion` config timeouts and a platform-native cache directory. Generated shell scripts suppress completion stderr; run the underlying CLI command directly when debugging completion behavior.
+
+Backends that require OAuth or token auth may need `caplets auth login <server>` before live downstream completions can return richer results. Completion never starts interactive login flows.
+
 ## Agent Plugins
 
 Use Caplets as a normal MCP server everywhere, or install a native agent integration when
@@ -107,28 +148,74 @@ configs run `caplets serve` directly, so install the Caplets CLI globally first.
 
 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:
+Start a local HTTP service. `--path` is the service base path; Caplets mounts MCP,
+control, and health endpoints underneath it:
+
+```sh
+CAPLETS_SERVER_URL=http://127.0.0.1:5387/caplets \
+CAPLETS_SERVER_PASSWORD=... \
+caplets serve --transport http
+```
+
+With `CAPLETS_SERVER_URL=http://127.0.0.1:5387/caplets`, the derived endpoints are:
+
+- MCP: `http://127.0.0.1:5387/caplets/mcp`
+- Control: `http://127.0.0.1:5387/caplets/control`
+- Health: `http://127.0.0.1:5387/caplets/healthz`
+
+`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.
+
+#### Docker Compose self-hosting
+
+This repository includes a source-build Docker image and Compose service for running the HTTP service from the checked-out source tree:
 
 ```sh
-caplets serve --transport http --host 127.0.0.1 --port 5387 --path /mcp
+CAPLETS_SERVER_PASSWORD=change-me docker compose up --build
+```
+
+By default, Compose publishes the service on loopback only:
+
+- Base URL: `http://127.0.0.1:5387`
+- MCP endpoint: `http://127.0.0.1:5387/mcp`
+- Control endpoint: `http://127.0.0.1:5387/control`
+- Health endpoint: `http://127.0.0.1:5387/healthz`
+
+The service stores Caplets config and auth state in a Docker named volume mounted at `/data`. To use a host-visible bind mount instead, replace this Compose volume entry:
+
+```yaml
+volumes:
+  - caplets-data:/data
 ```
 
-`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:
+with:
+
+```yaml
+volumes:
+  - ./data:/data
+```
+
+To expose the service to a LAN interface or reverse proxy, set an explicit bind address and public base URL:
 
 ```sh
-CAPLETS_SERVER_PASSWORD=... caplets serve --transport http --host 127.0.0.1 --port 5387 --path /mcp
+CAPLETS_BIND_ADDRESS=0.0.0.0 \
+CAPLETS_SERVER_URL=https://caplets.example.com \
+CAPLETS_SERVER_PASSWORD=change-me \
+docker compose up --build
 ```
 
-Native integrations read remote client settings from environment variables:
+Only expose Caplets beyond loopback through HTTPS/TLS and Basic Auth. `CAPLETS_SERVER_PASSWORD` protects both the MCP and control endpoints; downstream provider tokens and auth files remain server-owned inside the mounted `/data` location.
+
+Native integrations and remote-capable CLI commands read remote client settings from environment variables:
 
 ```sh
-CAPLETS_REMOTE_URL=https://caplets.example.com/mcp \
-CAPLETS_REMOTE_USER=caplets \
-CAPLETS_REMOTE_PASSWORD=... \
+CAPLETS_MODE=remote \
+CAPLETS_SERVER_URL=https://caplets.example.com/caplets \
+CAPLETS_SERVER_USER=caplets \
+CAPLETS_SERVER_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.
+For MCP-backed Codex or Claude Code configs, point the agent's MCP server entry at the derived `/mcp` 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
 
@@ -242,6 +329,12 @@ you want Caplets to expose:
   "version": 1,
   "defaultSearchLimit": 20,
   "maxSearchLimit": 50,
+  "completion": {
+    "discoveryTimeoutMs": 750,
+    "overallTimeoutMs": 1500,
+    "cacheTtlMs": 300000,
+    "negativeCacheTtlMs": 30000
+  },
   "mcpServers": {
     "filesystem": {
       "name": "Project Files",
@@ -805,11 +898,14 @@ For headless terminals:
 caplets auth login <server> --no-open
 ```
 
-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.
+In local mode, 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. In `CAPLETS_MODE=remote`, `caplets auth list`,
+`caplets auth login <server>`, and `caplets auth logout <server>` operate on the configured Caplets
+server instead. Downstream OAuth/OIDC credentials are stored server-side and are not returned to the
+local client. 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: