https://github.com/spiritledsoftware/caplets
Give your agent capabilities, not tools
https://github.com/spiritledsoftware/caplets
agents ai mcp openapi skills
Last synced: 13 days ago
JSON representation
Give your agent capabilities, not tools
- Host: GitHub
- URL: https://github.com/spiritledsoftware/caplets
- Owner: spiritledsoftware
- License: mit
- Created: 2026-05-12T00:12:42.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-12T12:27:41.000Z (19 days ago)
- Last Synced: 2026-06-12T14:18:58.365Z (19 days ago)
- Topics: agents, ai, mcp, openapi, skills
- Language: TypeScript
- Homepage: https://caplets.dev
- Size: 3.03 MB
- Stars: 7
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
Caplets
Give your agent capabilities, not giant tool walls.
Caplets wraps MCP servers, APIs, and commands behind focused capability cards.
caplets.dev
·
docs.caplets.dev
---
Caplets gives coding agents a Code Mode surface for MCP servers, APIs, and commands. Instead
of exposing every downstream operation as a giant tool list, each backend becomes a typed
`caplets.` handle the agent can inspect, search, call, filter, join, and summarize inside
one compact workflow.
Progressive discovery is still available when you want visible wrapper tools, but Code Mode is
the default exposure for configured backends.
Caplets can wrap:
- MCP servers
- OpenAPI, GraphQL, and simple HTTP APIs
- Curated repository CLI commands
- Shared Caplet files from this repo's `caplets/` catalog
## Quick Start
Full setup and configuration docs are available at [docs.caplets.dev](https://docs.caplets.dev/).
Install the CLI and wire it into your agent:
```sh
npm install -g caplets
caplets setup
```
Install a no-auth example Caplet and try it from your agent:
```sh
caplets install spiritledsoftware/caplets osv
```
Or add Caplets manually to any MCP client:
```json
{
"mcpServers": {
"caplets": {
"command": "caplets",
"args": ["serve"]
}
}
}
```
## Use Caplets
Add your own capability sources:
```sh
caplets add mcp docs --command npx --arg -y --arg @upstash/context7-mcp
caplets add openapi users --spec ./openapi.json --base-url https://api.example.com
caplets add graphql catalog --endpoint-url https://api.example.com/graphql --schema ./schema.graphql
caplets add http status-api --base-url https://api.example.com --action get_status:GET:/status/{service}
caplets add cli repo-tools --repo . --include git,gh,package
```
Inspect and call them from the CLI:
```sh
caplets list
caplets inspect osv
caplets search-tools osv vulnerability
caplets get-tool osv query_package_version
caplets call-tool osv query_package_version --args '{"name":"react","ecosystem":"npm","version":"18.2.0"}'
```
MCP-backed Caplets also support resources, resource templates, prompts, and argument
completion. Direct CLI commands print Markdown by default; pass `--format json` for
machine-readable output. In agent sessions, Code Mode keeps the same operations behind typed
handles so discovery, execution, filtering, and synthesis can happen in one call.
## Agent Surfaces
Caplets works as a regular MCP server through `caplets serve`. By default, that server exposes
Code Mode for the configured backends. Caplets also has native integrations for agents that can
load packages directly:
| Agent | Setup |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Codex, Claude Code, and other MCP clients | `caplets setup` or `caplets serve` |
| OpenCode | [`@caplets/opencode`](https://github.com/spiritledsoftware/caplets/tree/main/packages/opencode) |
| Pi | [`@caplets/pi`](https://github.com/spiritledsoftware/caplets/tree/main/packages/pi) |
`caplets setup` uses each harness's MCP configuration command:
```sh
codex mcp add caplets -- caplets serve
claude mcp add --transport stdio --scope user caplets -- caplets serve
```
Equivalent local Codex config:
```toml
[mcp_servers.caplets]
command = "caplets"
args = ["serve"]
```
For a remote or Cloud-backed MCP server, point the client at `caplets attach` instead:
```toml
[mcp_servers.caplets]
command = "caplets"
args = ["attach"]
```
```json
{
"mcpServers": {
"caplets": {
"command": "caplets",
"args": ["attach"]
}
}
}
```
Native integrations expose `caplets__code_mode` for multi-step TypeScript workflows over
generated `caplets.` handles. Progressive exposure adds `caplets__` tools; direct
exposure adds operation-level tools such as `caplets____`.
Remote mode is available with `caplets attach`, self-hosted HTTP service settings, or
Caplets Cloud auth:
```sh
export CAPLETS_MODE=remote
export CAPLETS_REMOTE_URL=https://caplets.example.com/caplets
export CAPLETS_REMOTE_TOKEN=...
caplets cloud auth login
CAPLETS_MODE=cloud CAPLETS_REMOTE_URL=https://cloud.caplets.dev opencode
```
## Benchmark
The deterministic benchmark compares flat MCP exposure with Caplets over the same mock
servers:
| Initial surface | Direct MCP | Caplets | Reduction |
| ----------------------- | ------------: | -----------: | ------------: |
| Visible tools | 215 | 7 | 96.7% fewer |
| Serialized payload | 63,250 bytes | 12,720 bytes | 79.9% smaller |
| Approx. context surface | 15,813 tokens | 3,180 tokens | 12,633 fewer |
The landing-page live Pi eval reports Caplets Code Mode passing the same 10/10 real-world
large MCP tasks as direct MCP and Executor.sh while using 72.0% fewer request + output
tokens than direct vanilla MCP. Live runs are model- and environment-dependent; the
deterministic benchmark is the reproducible claim.
See [docs/benchmarks/coding-agent.md](https://github.com/spiritledsoftware/caplets/blob/main/docs/benchmarks/coding-agent.md) for methodology and reproduction commands.
See [docs.caplets.dev/changelog](https://docs.caplets.dev/changelog/) for public release notes.
## Repository
This monorepo uses pnpm. Published packages support Node.js `>=22`; repo verification uses
the root toolchain, which requires Node.js `>=24`.
```sh
pnpm install --frozen-lockfile
pnpm verify
```
Useful focused checks:
```sh
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm benchmark:check
pnpm build
```
Package map:
- `packages/core` - runtime, config, Code Mode, backends, MCP server, remote attach
- `packages/cli` - published `caplets` binary
- `packages/opencode` - native OpenCode plugin
- `packages/pi` - native Pi extension
- `packages/benchmarks` - deterministic and opt-in live benchmarks
- `apps/landing` - public site at `caplets.dev`
- `apps/docs` - public docs site at `docs.caplets.dev`
Long-lived docs:
- [Code Mode PRD](https://github.com/spiritledsoftware/caplets/blob/main/docs/product/caplets-code-mode-prd.md)
- [Architecture](https://github.com/spiritledsoftware/caplets/blob/main/docs/architecture.md)
- [ADR 0001: Code Mode default exposure](https://github.com/spiritledsoftware/caplets/blob/main/docs/adr/0001-code-mode-default-exposure.md)
- [Benchmark methodology](https://github.com/spiritledsoftware/caplets/blob/main/docs/benchmarks/coding-agent.md)
- [Native integrations](https://github.com/spiritledsoftware/caplets/blob/main/docs/native-integrations.md)
- [Project Binding](https://github.com/spiritledsoftware/caplets/blob/main/docs/project-binding.md)
## License
MIT