caplets 0.12.1 → 0.12.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +96 -38
  2. package/dist/index.js +5 -2
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,26 +1,99 @@
1
1
  # Caplets
2
2
 
3
- Caplets is a progressive-disclosure gateway for Model Context Protocol (MCP) servers,
4
- native OpenAPI endpoints, native GraphQL endpoints, and explicitly configured HTTP APIs.
3
+ Caplets turns sprawling tool setups into focused capability cards for coding agents.
4
+ Connect MCP servers, OpenAPI specs, GraphQL endpoints, HTTP actions, and curated CLI
5
+ commands without flooding the model with every downstream operation up front.
5
6
 
6
- Instead of connecting an MCP client to many downstream servers or HTTP APIs and exposing
7
- every operation up front, Caplets exposes one top-level tool per configured capability.
8
- An agent first chooses a capability domain, then asks Caplets to list, search, inspect,
9
- or call that backend's underlying tools or operations.
7
+ Instead of exposing a flat wall of tools, Caplets shows one top-level tool per capability.
8
+ The agent chooses a domain first, then uses scoped operations like `search_tools`,
9
+ `get_tool`, and `call_tool` only when it needs more detail.
10
10
 
11
- This keeps the initial MCP tool list small, makes tool selection easier, and avoids
12
- flattened tool-name collisions across servers.
11
+ ## Quick Start
12
+
13
+ Caplets requires Node.js 22 or newer.
14
+
15
+ ```sh
16
+ pnpm add -g caplets
17
+ caplets init
18
+ ```
19
+
20
+ Add a capability from an existing system:
21
+
22
+ ```sh
23
+ # Wrap an MCP server
24
+ caplets add mcp docs --command npx --arg -y --arg @upstash/context7-mcp
25
+
26
+ # Convert useful repository commands into curated tools
27
+ caplets add cli repo-tools --repo . --include git,gh,package
28
+
29
+ # Install ready-made Caplets from a repository
30
+ caplets install spiritledsoftware/caplets github linear context7
31
+ ```
32
+
33
+ Connect Caplets to any MCP client:
34
+
35
+ ```json
36
+ {
37
+ "mcpServers": {
38
+ "caplets": {
39
+ "command": "caplets",
40
+ "args": ["serve"]
41
+ }
42
+ }
43
+ }
44
+ ```
45
+
46
+ Ask your agent to use Caplets. It will see a compact capability list first, then inspect
47
+ only the backend it needs.
48
+
49
+ ## Agent Plugins
50
+
51
+ Use Caplets as a normal MCP server everywhere, or install a native agent integration when
52
+ your coding agent supports one.
53
+
54
+ | Agent | Install | What It Provides |
55
+ | -------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
56
+ | Any MCP client | Add `caplets serve` as a stdio MCP server | Universal progressive-disclosure gateway |
57
+ | Claude Code | `claude plugin marketplace add spiritledsoftware/caplets && claude plugin install caplets@caplets` | Claude Code plugin metadata, MCP config, and shared skill guidance |
58
+ | Codex | `codex plugin marketplace add spiritledsoftware/caplets`, then install `caplets` from Codex plugins | Codex plugin metadata, MCP config, and shared skill guidance |
59
+ | OpenCode | Install [`@caplets/opencode`](packages/opencode/README.md) | Native `caplets_<id>` tools and prompt guidance hooks |
60
+ | Pi | Install [`@caplets/pi`](packages/pi/README.md) | Native `caplets_<id>` tools with Pi prompt snippets/guidelines |
61
+
62
+ Codex and Claude Code plugins are plugin-native but MCP-backed. Their manifests live in
63
+ `.codex-plugin/` and `.claude-plugin/`; component files live at the plugin root so
64
+ marketplace installs can copy and resolve them correctly.
65
+
66
+ The Claude Code and Codex commands install from this GitHub repository through each agent's
67
+ plugin marketplace flow; users do not need to clone the repository manually. Plugin MCP
68
+ configs run `caplets serve` directly, so install the Caplets CLI globally first.
69
+
70
+ ## Convert Existing Tooling
71
+
72
+ Caplets is designed to convert what you already use into agent-friendly capability domains.
73
+
74
+ | Existing source | Command |
75
+ | ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
76
+ | Local MCP server | `caplets add mcp local-tools --command node --arg ./server.mjs` |
77
+ | Remote MCP server | `caplets add mcp remote-tools --url https://mcp.example.com/mcp --transport http --token-env MCP_TOKEN` |
78
+ | OpenAPI service | `caplets add openapi users --spec ./openapi.json --base-url https://api.example.com --token-env USERS_API_TOKEN` |
79
+ | GraphQL endpoint | `caplets add graphql catalog --endpoint-url https://api.example.com/graphql --schema ./schema.graphql` |
80
+ | Simple HTTP API | `caplets add http status-api --base-url https://api.example.com --action get_status:GET:/status/{service}` |
81
+ | Repository CLI workflows | `caplets add cli repo-tools --repo . --include git,gh,package` |
82
+ | Shared Caplet catalog | `caplets install spiritledsoftware/caplets github linear context7` |
83
+
84
+ Generated Caplet files are written to `./.caplets` by default so teams can review,
85
+ version, and customize them with the project.
13
86
 
14
87
  ## Why It Matters
15
88
 
16
- Large MCP setups make agents worse before they make them better. If every downstream
17
- server exposes every tool up front, the model starts with a noisy flat list, duplicate
18
- tool names, and a bigger context surface before it knows which capability matters.
89
+ Large MCP setups can make agents harder to steer. If every downstream server exposes
90
+ every tool up front, the model starts with a noisy flat list, duplicate tool names, and
91
+ a larger context surface before it knows which capability matters.
19
92
 
20
93
  Caplets turns that flat tool wall into progressive disclosure: one capability card first,
21
94
  then scoped discovery only after the agent chooses the relevant domain.
22
95
 
23
- ## Benchmark Results
96
+ ## Benchmark
24
97
 
25
98
  In Caplets' reproducible coding-agent benchmark, the same three mock MCP servers are
26
99
  exposed two ways: direct flat MCP aggregation versus Caplets progressive disclosure.
@@ -32,9 +105,9 @@ exposed two ways: direct flat MCP aggregation versus Caplets progressive disclos
32
105
  | Approx. context surface | 8,023 tokens | 2,100 tokens | 5,923 fewer |
33
106
  | Top-level name collisions | 3 duplicate names | 0 | eliminated |
34
107
 
35
- The important part: Caplets does not remove access to the downstream tools. It hides
36
- them behind scoped discovery operations like `search_tools`, `get_tool`, and `call_tool`,
37
- so the agent sees less up front while still being able to reach the same capabilities.
108
+ Caplets does not remove access to downstream tools. It places them behind scoped
109
+ discovery operations, so the agent sees less up front while retaining access to the same
110
+ capabilities when needed.
38
111
 
39
112
  A local OpenCode live benchmark also completed the full benchmark matrix successfully:
40
113
 
@@ -57,10 +130,10 @@ pnpm build
57
130
  CAPLETS_BENCH_LIVE=1 pnpm benchmark:live:opencode -- --model openai/gpt-5.5-fast
58
131
  ```
59
132
 
60
- ## Inspiration
133
+ ## Design Model
61
134
 
62
- Caplets is a mashup of two ideas that work well separately but leave a gap together:
63
- agent skills and MCP servers.
135
+ Caplets combines two ideas that work well separately but leave a gap together: agent
136
+ skills and MCP servers.
64
137
 
65
138
  Agent skills are great at progressive disclosure. They show an agent a compact capability
66
139
  card first, then let it read deeper instructions only when that skill is relevant. MCP
@@ -72,7 +145,7 @@ Caplets borrows the skill-shaped discovery model and applies it to MCP. Each dow
72
145
  server becomes a skill-like capability card first; its actual MCP tools stay hidden until
73
146
  the agent chooses that server and asks to search, list, inspect, or call them.
74
147
 
75
- ## What It Does
148
+ ## Capabilities
76
149
 
77
150
  - Reads downstream MCP server definitions, native OpenAPI endpoint definitions, native GraphQL endpoint definitions, explicit HTTP API action definitions, and curated CLI tool definitions from the user config file.
78
151
  - Registers one generated MCP tool for each enabled MCP server, OpenAPI endpoint, GraphQL endpoint, HTTP API, or CLI tools backend.
@@ -89,21 +162,6 @@ the agent chooses that server and asks to search, list, inspect, or call them.
89
162
  - Redacts secrets from structured errors.
90
163
  - Supports static remote auth and OAuth token storage for remote servers.
91
164
 
92
- ## Install
93
-
94
- Caplets requires Node.js 22 or newer.
95
-
96
- ```sh
97
- pnpm add -g caplets
98
- ```
99
-
100
- For local development from this repository:
101
-
102
- ```sh
103
- pnpm install
104
- pnpm build
105
- ```
106
-
107
165
  ## Configure
108
166
 
109
167
  Create a starter user config at `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms or `%APPDATA%\caplets\config.json` on Windows:
@@ -706,11 +764,11 @@ top-level MCP tool list without restarting Caplets. When an MCP-backed Caplet ch
706
764
  removed, Caplets closes only that affected downstream connection; unrelated Caplets and
707
765
  their downstream connections keep running.
708
766
 
709
- ## Native Agent Integrations
767
+ ## Additional Native Integrations
710
768
 
711
- Caplets can also run as native agent extensions when the host supports native tools. Native
712
- integrations expose one prefixed tool per configured Caplet, such as `caplets_github`, while
713
- reusing the same Caplets config and backend runtime.
769
+ OpenCode and Pi support true native tool registration. Those integrations expose one
770
+ prefixed tool per configured Caplet, such as `caplets_github`, while reusing the same
771
+ Caplets config and backend runtime.
714
772
 
715
773
  - [`@caplets/opencode`](packages/opencode/README.md): OpenCode plugin that injects prompt guidance through plugin hooks instead of editing `opencode.json`.
716
774
  - [`@caplets/pi`](packages/pi/README.md): Pi extension installable with `pi install npm:@caplets/pi`, with guidance provided through Pi tool prompt snippets and guidelines.
package/dist/index.js CHANGED
@@ -1,10 +1,13 @@
1
1
  #!/usr/bin/env node
2
- import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
2
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3
3
  import { CapletsRuntime, runCli } from "@caplets/core";
4
+ //#region package.json
5
+ var version = "0.12.3";
6
+ //#endregion
4
7
  //#region src/index.ts
5
8
  async function main() {
6
9
  if (process.argv[2] && process.argv[2] !== "serve") {
7
- await runCli(process.argv.slice(2));
10
+ await runCli(process.argv.slice(2), { version });
8
11
  return;
9
12
  }
10
13
  const runtime = process.env.CAPLETS_CONFIG ? new CapletsRuntime({ configPath: process.env.CAPLETS_CONFIG }) : new CapletsRuntime();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "caplets",
3
- "version": "0.12.1",
3
+ "version": "0.12.3",
4
4
  "description": "Progressive disclosure gateway CLI for MCP servers and native Caplets adapters.",
5
5
  "keywords": [
6
6
  "caplets",
@@ -34,7 +34,7 @@
34
34
  },
35
35
  "dependencies": {
36
36
  "@modelcontextprotocol/sdk": "^1.29.0",
37
- "@caplets/core": "0.12.1"
37
+ "@caplets/core": "0.12.2"
38
38
  },
39
39
  "devDependencies": {
40
40
  "@types/node": "^25.7.0",