caplets 0.17.7 → 0.17.9

package/README.md

@@ -4,8 +4,8 @@
   <h1>Caplets</h1>
 
   <p>
-    <strong>Capability cards for coding agents.</strong><br />
-    Wrap sprawling tool stacks behind focused, progressive-disclosure interfaces.
+    <strong>Give your agent capabilities, not tools.</strong><br />
+    Turn MCP servers, APIs, and commands into focused agent capabilities.
   </p>
 
   <p>
@@ -15,6 +15,10 @@
     <img alt="Node 22+" src="https://img.shields.io/badge/node-%3E%3D22-F6E8C8?style=flat-square&labelColor=1F2018" />
   </p>
 
+  <p>
+    <a href="https://caplets.dev"><strong>caplets.dev</strong></a>
+  </p>
+
   <p>
     <code>MCP</code> · <code>OpenAPI</code> · <code>GraphQL</code> · <code>HTTP</code> · <code>CLI</code>
   </p>
@@ -22,38 +26,33 @@
 
 ---
 
-Caplets turns sprawling tool setups into focused capability cards for coding agents.
-Connect MCP servers, OpenAPI specs, GraphQL endpoints, HTTP actions, and curated CLI
-commands without flooding the model with every downstream operation up front.
+Caplets turns MCP servers, APIs, and commands into focused agent capabilities: one card first, searchable tools next, inspectable schemas before calls, and preserved results after.
 
-Instead of exposing a flat wall of tools, Caplets shows one top-level tool per capability.
-The agent chooses a domain first, then uses scoped operations like `search_tools`,
-`get_tool`, and `call_tool` only when it needs more detail.
+Stop dumping every operation into context up front. Caplets wraps each tool source as a capability an agent can discover, inspect, call, and recover from one step at a time. Instead of exposing a giant flat wall of operations, Caplets shows a compact capability card with source, status, and next actions. 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.
+For MCP-backed Caplets, the scoped operation set also includes resource discovery and reading, prompt listing and rendering, resource-template discovery, and completion for prompt or template arguments. Non-MCP backends expose focused tool and action operations.
 
-## Quick Start
+## Try the aha moment
 
-Caplets requires Node.js 22 or newer.
+Install Caplets, add Context7, and watch your agent see one capability before it searches downstream tools.
 
 ```sh
-pnpm add -g caplets
+npm install -g caplets
 caplets init
+caplets add mcp context7 --command npx --arg -y --arg @upstash/context7-mcp
+caplets serve
 ```
 
-Add a capability from an existing system:
+In the deterministic benchmark, 106 flat tools became 3 top-level capabilities with an 87.9% smaller initial payload. Your agent starts with `context7`, then drills in through `inspect`, `search_tools`, `get_tool`, and `call_tool` only when needed.
 
-```sh
-# Wrap an MCP server
-caplets add mcp docs --command npx --arg -y --arg @upstash/context7-mcp
+## Quick Start
 
-# Convert useful repository commands into curated tools
-caplets add cli repo-tools --repo . --include git,gh,package
+Caplets requires Node.js 22 or newer.
 
-# Install ready-made Caplets from a repository
-caplets install spiritledsoftware/caplets github linear context7
+```sh
+npm install -g caplets
+caplets init
+caplets serve
 ```
 
 Connect Caplets to any MCP client:
@@ -69,13 +68,25 @@ Connect Caplets to any MCP client:
 }
 ```
 
-Ask your agent to use Caplets. It will see a compact capability list first, then inspect
-only the backend it needs.
+Ask your agent to use Caplets. It will see a compact capability list first, then inspect only the backend it needs.
 
-You can also invoke configured Caplets directly from the CLI for agent-friendly scripts and smoke tests:
+Add capabilities from existing systems when you are ready to give agents a focused tool surface:
 
 ```sh
-caplets get-caplet context7
+# Wrap an MCP server
+caplets add mcp docs --command npx --arg -y --arg @upstash/context7-mcp
+
+# Convert useful repository commands into curated tools
+caplets add cli repo-tools --repo . --include git,gh,package
+
+# Install ready-made Caplets from a repository
+caplets install spiritledsoftware/caplets github linear context7
+```
+
+Configured Caplets can be invoked directly from the CLI for agent-friendly scripts and smoke tests:
+
+```sh
+caplets inspect context7
 caplets list-tools context7
 caplets get-tool context7 resolve-library-id
 caplets call-tool context7 resolve-library-id --args '{"libraryName":"react"}'
@@ -244,12 +255,16 @@ version, and customize them with the project.
 
 ## Why It Matters
 
-Large MCP setups can make agents harder to steer. If every downstream server exposes
-every tool up front, the model starts with a noisy flat list, duplicate tool names, and
-a larger context surface before it knows which capability matters.
+Flat tool lists make agents guess before they understand. If every downstream server exposes every operation up front, the model starts with a noisy list, duplicate tool names, and a larger context surface before it knows which capability matters.
 
-Caplets turns that flat tool wall into progressive disclosure: one capability card first,
-then scoped discovery only after the agent chooses the relevant domain.
+Caplets turns that flat wall into a staged path:
+
+1. **Choose** a capability, such as `GitHub`.
+2. **Inspect** matching operations with `search_tools` or `list_tools`.
+3. **Resolve** the exact schema with `get_tool`.
+4. **Invoke** with `call_tool` while preserving downstream content, structured data, and error state.
+
+A backend enters agent context as a focused card with source, status, and next actions, not a wall of operations.
 
 ## Benchmark
 
@@ -290,18 +305,30 @@ CAPLETS_BENCH_LIVE=1 pnpm benchmark:live:opencode -- --model openai/gpt-5.5-fast
 
 ## Design Model
 
-Caplets combines two ideas that work well separately but leave a gap together: agent
-skills and MCP servers.
+Caplets combines two ideas that work well separately but leave a gap together: agent skills and MCP servers.
+
+Agent skills are great at progressive disclosure. They show an agent a compact capability card first, then let it read deeper instructions only when that skill is relevant. MCP servers are great at live tool execution, but most clients expose their tools as one flat list up front. That means a powerful MCP setup can flood the agent with every tool from every server before it knows which capability area matters.
 
-Agent skills are great at progressive disclosure. They show an agent a compact capability
-card first, then let it read deeper instructions only when that skill is relevant. MCP
-servers are great at live tool execution, but most clients expose their tools as one flat
-list up front. That means a powerful MCP setup can flood the agent with every tool from
-every server before it knows which capability area matters.
+Caplets borrows the skill-shaped discovery model and applies it to MCP, OpenAPI, GraphQL, HTTP, and CLI backends. Each backend becomes a skill-like capability card first; its actual operations stay hidden until the agent chooses that capability and asks to search, list, inspect, or call them.
 
-Caplets borrows the skill-shaped discovery model and applies it to MCP. Each downstream
-server becomes a skill-like capability card first; its actual MCP tools stay hidden until
-the agent chooses that server and asks to search, list, inspect, or call them.
+A capability is safe for agents when it reveals itself in stages:
+
+- **Discoverable as one capability:** source, status, auth posture, and next actions are visible before any downstream tool list enters context.
+- **Inspectable before invocation:** agents search inside the selected capability, then inspect exact tool schemas before any call is made.
+- **Lossless after the call:** Caplets preserves structured content, resource links, images, and downstream error state instead of flattening results away.
+
+## Trust Before Invocation
+
+Caplets keeps trust mechanics visible before an agent calls a backend.
+
+| Mechanic | Example                            | Why it matters                                                                  |
+| -------- | ---------------------------------- | ------------------------------------------------------------------------------- |
+| Source   | `.caplets/config.json`             | Users can see where the capability came from before trusting it.                |
+| Auth     | `GITHUB_TOKEN: redacted`           | Secrets stay hidden while auth state remains inspectable.                       |
+| Timeout  | `30s boundary`                     | Slow or stuck backends fail visibly instead of disappearing into agent context. |
+| Error    | `safe message + raw detail scoped` | Recovery information stays useful without leaking sensitive configuration.      |
+
+If a backend fails, Caplets keeps the error scoped to the capability, preserves useful recovery detail, and redacts sensitive configuration before it reaches the agent.
 
 ## Capabilities
 
@@ -464,8 +491,11 @@ tags:
   - code
   - review
 mcpServer:
-  command: npx
-  args: ["-y", "github-mcp-server"]
+  transport: http
+  url: https://api.githubcopilot.com/mcp
+  auth:
+    type: bearer
+    token: $env:GH_TOKEN
 ---
 
 # GitHub
@@ -559,7 +589,7 @@ normal Markdown links from `CAPLET.md`.
 
 This repository includes polished working examples under [`caplets/`](caplets/):
 
-- `github`: GitHub's official MCP server container, using `GITHUB_PERSONAL_ACCESS_TOKEN`.
+- `github`: GitHub's hosted MCP endpoint, using `GH_TOKEN`.
 - `linear`: Linear's hosted OAuth MCP endpoint.
 - `context7`: Context7 documentation lookup through `@upstash/context7-mcp`.
 - `repo-cli`: Read-oriented repository CLI workflows through `git` and package scripts.
@@ -857,7 +887,7 @@ an existing destination file.
 ### Caplet Sets
 
 Use `capletSets` to expose another Caplets collection as nested Caplets. Each child Caplet appears
-as one downstream tool and supports the full Caplets operation set: `get_caplet`, `check_backend`,
+as one downstream tool and supports the full Caplets operation set: `inspect`, `check_backend`,
 `list_tools`, `search_tools`, `get_tool`, and `call_tool`.
 
 ```json
@@ -997,6 +1027,34 @@ top-level MCP tool list without restarting Caplets. When an MCP-backed Caplet ch
 removed, Caplets closes only that affected downstream connection; unrelated Caplets and
 their downstream connections keep running.
 
+## Quick Integration Setup
+
+Use `caplets setup` to install or configure an agent integration:
+
+```bash
+caplets setup codex
+caplets setup claude-code
+caplets setup opencode
+caplets setup pi
+caplets setup mcp-client --output ./caplets.mcp.json
+```
+
+Preview the actions before changing anything:
+
+```bash
+caplets setup codex --dry-run
+```
+
+For native integrations that should connect to a remote Caplets HTTP service:
+
+```bash
+caplets setup opencode --remote --server-url https://caplets.example.com/caplets
+```
+
+`caplets setup` runs the supported agent installer commands or writes the explicit config
+path you pass with `--output`. It does not store secrets, edit unknown MCP client config
+locations, or start `caplets serve`.
+
 ## Additional Native Integrations
 
 OpenCode and Pi support true native tool registration. Those integrations expose one
@@ -1062,7 +1120,7 @@ Call one exact downstream tool:
 
 Available operations:
 
-- `get_caplet`: return the configured capability card without starting the downstream server.
+- `inspect`: return the configured capability card without starting the downstream server.
 - `check_backend`: verify the selected backend, whether MCP, OpenAPI, GraphQL, HTTP, CLI, or nested Caplets.
 - `list_tools`: return compact downstream tool metadata.
 - `search_tools`: search downstream tool names and descriptions within this Caplet.
@@ -1072,7 +1130,7 @@ 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
+Discovery operations (`inspect`, `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