caplets 0.5.2 → 0.7.0

package/README.md

@@ -129,8 +129,19 @@ CAPLETS_CONFIG=/path/to/config.json caplets init
 CAPLETS_CONFIG=/path/to/config.json caplets serve
 ```
 
-Caplets validates this file at startup. Config changes take effect after restarting the
-Caplets MCP server.
+Inspect the installed CLI version and resolved config locations:
+
+```sh
+caplets --version
+caplets config path
+caplets config paths
+caplets config paths --json
+```
+
+Caplets validates this file at startup and hot reloads config changes while `caplets serve`
+is running. Invalid edits are ignored until fixed, so the MCP server keeps serving the last
+known-good config instead of dropping every tool because of a transient JSON or validation
+error.
 
 The optional `$schema` field points editors at the generated JSON Schema in
 [`schemas/caplets-config.schema.json`](schemas/caplets-config.schema.json). CI verifies that
@@ -201,6 +212,30 @@ Top-level files derive their Caplet ID from the filename. Directory-style Caplet
 `linear/CAPLET.md`, which is exposed as `linear`; sibling files can be referenced with
 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`.
+- `linear`: Linear's hosted OAuth MCP endpoint.
+- `context7`: Context7 documentation lookup through `@upstash/context7-mcp`.
+
+Install every example from a repo's `caplets/` directory:
+
+```sh
+caplets install spiritledsoftware/caplets
+```
+
+Install one or more individual Caplets by ID:
+
+```sh
+caplets install spiritledsoftware/caplets github
+caplets install spiritledsoftware/caplets github linear
+```
+
+`caplets install` accepts a GitHub `owner/repo` shorthand, a Git URL, or a local repository path.
+It installs into your user Caplets root, which is `~/.caplets` by default or the parent directory
+of `CAPLETS_CONFIG` when that environment variable is set. Existing Caplets are not overwritten
+unless `--force` is passed.
+
 Caplets always loads user Caplet files from `~/.caplets`. Project `./.caplets/config.json`
 is still loaded as project config, but project Markdown Caplet files are executable
 configuration and are ignored unless explicitly trusted:
@@ -390,6 +425,14 @@ caplets auth list
 caplets auth logout <server>
 ```
 
+To list configured Caplets without starting downstream backends:
+
+```sh
+caplets list
+caplets list --all
+caplets list --json
+```
+
 ### Optional Server Settings
 
 Every server can set:
@@ -417,6 +460,12 @@ Configure your MCP client to run Caplets as a stdio server:
 If your client starts the configured command directly, `caplets` without arguments also
 starts the MCP server. `serve` is explicit and recommended for clarity.
 
+`caplets serve` watches the effective user config, project config, user Caplet files, and
+trusted project Caplet files. Adding, editing, disabling, or removing a Caplet updates the
+top-level MCP tool list without restarting Caplets. When an MCP-backed Caplet changes or is
+removed, Caplets closes only that affected downstream connection; unrelated Caplets and
+their downstream connections keep running.
+
 ## How Agents Use It
 
 Caplets initially exposes one MCP tool per enabled Caplet. If the config has `filesystem`,
@@ -495,9 +544,10 @@ pnpm schema:check
 pnpm verify
 ```
 
-`pnpm dev` rebuilds on source changes and restarts the local stdio MCP server from
+`pnpm dev` rebuilds Caplets source changes and restarts the local stdio MCP server from
 `dist/index.js`. Use it for local development, not as the command configured in an MCP
-client, because build logs are written to stdout.
+client, because build logs are written to stdout. Runtime config hot reload is built into
+normal `caplets serve` and does not require `pnpm dev`.
 
 ## Product Notes
 

package/caplets/context7.md

@@ -0,0 +1,33 @@
+---
+$schema: https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
+name: Context7 Documentation
+description: Fetch current library and framework documentation through Context7 before using version-sensitive APIs.
+tags:
+  - docs
+  - libraries
+  - frameworks
+  - api-reference
+mcpServer:
+  command: npx
+  args:
+    - -y
+    - "@upstash/context7-mcp"
+---
+
+# Context7 Documentation
+
+Use this Caplet when the agent needs up-to-date library, SDK, framework, CLI, or cloud-service
+documentation before writing code or giving technical instructions.
+
+## Good Fits
+
+- Check current API signatures for fast-moving JavaScript, TypeScript, Python, or cloud libraries.
+- Look up migration notes before changing framework configuration.
+- Retrieve official examples for a specific package version.
+- Resolve uncertainty about CLI flags, config files, or SDK initialization.
+
+## Use Carefully
+
+- Prefer primary documentation over snippets when implementation risk is high.
+- Record the library or package name clearly before searching.
+- Do not use this as a substitute for project-local types and tests.

package/caplets/github/CAPLET.md

@@ -0,0 +1,54 @@
+---
+$schema: https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
+name: GitHub
+description: Inspect and manage GitHub repositories, issues, pull requests, branches, commits, and code review workflows.
+tags:
+  - code
+  - github
+  - pull-requests
+  - issues
+  - reviews
+mcpServer:
+  command: docker
+  args:
+    - run
+    - -i
+    - --rm
+    - -e
+    - GITHUB_PERSONAL_ACCESS_TOKEN
+    - ghcr.io/github/github-mcp-server
+  env:
+    GITHUB_PERSONAL_ACCESS_TOKEN: $env:GITHUB_PERSONAL_ACCESS_TOKEN
+---
+
+# GitHub
+
+Use this Caplet when the agent needs live GitHub repository context or needs to act on
+issues, pull requests, branches, commits, or review feedback.
+
+## Good Fits
+
+- Summarize recent pull request activity before a code review.
+- Inspect open issues and identify implementation work.
+- Create or update issues from an implementation plan.
+- Compare branches, inspect commits, or review pull request files.
+- Leave review comments after the agent has inspected the relevant diff.
+
+## Use Carefully
+
+- Mutating operations can affect real repositories. Prefer read operations first.
+- Use a least-privilege `GITHUB_PERSONAL_ACCESS_TOKEN`.
+- Do not ask the agent to expose token values, repository secrets, or private issue contents outside
+  the intended conversation.
+
+## Setup
+
+Create a GitHub personal access token with the minimum repository scopes needed for your workflow,
+then export it before starting Caplets:
+
+```sh
+export GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_...
+caplets serve
+```
+
+This Caplet uses GitHub's official MCP server container, so Docker must be available on the host.

package/caplets/github/README.md

@@ -0,0 +1,13 @@
+# GitHub Caplet
+
+This Caplet wraps GitHub's official MCP server container:
+
+```sh
+docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
+```
+
+Install it from this repo:
+
+```sh
+caplets install spiritledsoftware/caplets github
+```

package/caplets/linear/CAPLET.md

@@ -0,0 +1,50 @@
+---
+$schema: https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
+name: Linear
+description: Plan and track product work in Linear by reading teams, projects, cycles, issues, comments, and workflow state.
+tags:
+  - planning
+  - linear
+  - issues
+  - projects
+  - triage
+mcpServer:
+  transport: http
+  url: https://mcp.linear.app/mcp
+  auth:
+    type: oauth2
+---
+
+# Linear
+
+Use this Caplet when the agent needs live product planning context from Linear or needs to keep
+implementation work synchronized with issues, projects, and team workflows.
+
+## Good Fits
+
+- Find the current issue or project that matches a requested feature.
+- Summarize open work by team, project, cycle, label, or assignee.
+- Draft issue breakdowns from a technical plan.
+- Add implementation notes or status comments after code changes.
+- Check whether a bug or feature already has active work before creating a new issue.
+
+## Reference Files
+
+- [Workflows](./workflows.md): recommended lookup, planning, status update, and triage flows.
+
+## Use Carefully
+
+- Linear issue updates are visible to teammates. Read first, then write deliberately.
+- Keep issue titles and comments concise; use links to detailed implementation artifacts when useful.
+- Avoid broad, noisy searches when a team key, issue ID, project, or label is available.
+
+## Setup
+
+Authenticate once through Caplets:
+
+```sh
+caplets auth login linear
+```
+
+The Linear MCP endpoint supports OAuth. Caplets stores the resulting token bundle in your local
+Caplets auth store.

package/caplets/linear/workflows.md

@@ -0,0 +1,9 @@
+# Linear Workflows
+
+Useful agent flows:
+
+- **Issue lookup**: search by issue key first, then by title or project if no key is provided.
+- **Planning**: read project context, summarize constraints, then create child issues only when the
+  requested breakdown is clear.
+- **Status updates**: comment with what changed, verification run, and remaining risk.
+- **Triage**: group candidate issues by urgency, owner, and whether they are blocked.