Skip to content

carapace-sh/carapace-bin / skills/carapace

carapace

Verified

Use when working with carapace shell completion — integrating into CLIs, writing YAML specs, creating custom actions, building completion-aware lexers for DSLs, looking up macros, setting up shell completion, configuring choices/bridges, using the MCP server, or adding man page documentation.

FileKindSize
SKILL.mdskill md4.0 KB
references/action.mdmarkdown20.8 KB
references/choice.mdmarkdown9.0 KB
references/convert.mdmarkdown10.5 KB
references/env.mdmarkdown7.8 KB
references/integrate.mdmarkdown29.1 KB
references/lexer.mdmarkdown24.3 KB
references/macro.mdmarkdown19.4 KB
references/man.mdmarkdown13.5 KB
references/mcp.mdmarkdown14.0 KB
references/scrape.mdmarkdown6.3 KB
references/setup.mdmarkdown6.8 KB
references/spec.mdmarkdown8.0 KB
references/update.mdmarkdown11.2 KB

references/mcp.md

View on GitHub
# Carapace MCP Server Guide

The carapace MCP server exposes shell completion capabilities to AI assistants and other MCP clients via the [Model Context Protocol](https://modelcontextprotocol.io/).

## Starting the Server

The MCP server runs over stdio (JSON-RPC 2.0) and is started with:

```bash
carapace --mcp
```

The server reads JSON-RPC requests from stdin and writes responses to stdout. It supports both single requests and batch requests (JSON arrays). Notifications (requests without an `id`) are silently skipped.

## Client Configuration

### Crush

Add to `crush.json`:

```json
{
  "mcp": {
    "carapace": {
      "type": "stdio",
      "command": "carapace",
      "args": ["--mcp"]
    }
  }
}
```

### Other MCP Clients

Any MCP client that supports stdio transport can connect. The server name is `carapace` and it reports protocol version `2024-11-05`.

## Protocol

The server implements JSON-RPC 2.0 with these methods:

| Method | Description |
|--------|-------------|
| `initialize` | Returns server info and capabilities |
| `tools/list` | Returns the tool definitions (three tools; `complete_macro` is currently disabled) |
| `tools/call` | Executes a tool by name |

Capabilities: `{tools: {}}` — only tools are supported (no resources, no prompts).

## Tools

### `complete_command` — Shell Command Completion

Returns context‑aware, dynamic completions for shell commands.

**Input Schema:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `args` | `string[]` | Yes | Command line arguments to complete |
| `executable` | `string` | No | Path to the executable providing the completion (requires `bridge`). Differs from `args[0]` (command name) — the bridge action uses this as the actual binary to invoke. |
| `bridge` | `string` | No | Bridge providing the completion (e.g. `carapace-bin`, `cobra`, `zsh`, `fish`, `bash`, `argcomplete`, `click`) |

**How it works:**

The first element in `args` is the command name (not a flag). The remaining elements are the arguments to complete, including the partial word being completed. The command name is `args[0]` — it selects which completer to invoke. It is **not** stripped: the full `args` array (including `args[0]`) is passed through to the completer, so the CLI equivalent is `carapace <args[0]> export <args[0]> <args[1]> ...`. See the worked examples and CLI equivalents table below.

The behavior depends on which optional parameters are provided:

| `executable` | `bridge` | Behavior | Confirmation |
|-------------|----------|----------|--------------|
| not set | not set | Default completion using the running carapace binary (`os.Executable()`) | Not required |
| not set | set | Explicit bridge using `carapace <command>/<bridge> export <args...>` | Not required |
| set | set | Custom executable with specified bridge | Required |

**Mode details:**

1. **Default** (no `executable`, no `bridge`): Invokes `carapace <command> export <args...>` using the running carapace binary itself (`os.Executable()`), not a PATH lookup. This is the standard completion flow.

2. **Bridge only** (no `executable`, `bridge` set): Uses the explicit bridge variant. Invokes `carapace <command>/<bridge> export <args...>`. For example, with `bridge: "zsh"`, it completes `tail` using zsh's completion system. The `carapace-bin/<bridge>` syntax is also supported to use an explicit bridge within carapace-bin (e.g. `bridge: "carapace-bin/cobra"`).

3. **Executable + bridge** (`executable` and `bridge` both set): Uses the given executable for completion. **This requires user confirmation** since it executes an arbitrary binary. The `executable` is the actual binary to invoke (may differ from `args[0]` which is the command name).
   - For `carapace-bin` bridge: Invokes `<executable> <command> export <args...>` directly (default choice).
   - For `carapace-bin/<bridge>`: Invokes `<executable> <command>/<bridge> export <args...>` (explicit bridge with custom executable).
   - For other bridges (cobra, argcomplete, carapace, click, etc.): Invokes the bridge action directly with the `executable` as the target. The bridge action knows how to invoke the executable (e.g., cobra bridge calls `<executable> __complete <args...>`, carapace bridge calls `<executable> _carapace export <args...>`, argcomplete sets env vars and calls `<executable>`).

**Constraints:**

- `args` must contain at least 2 elements (command + argument to complete)
- Command must not start with `-` (flags are not completer names)
- Arguments must not contain NUL bytes (`\0`)
- `bridge` is required when `executable` is set

**Response:** For carapace-bin invocations (default, bridge, and `carapace-bin` executable modes): plain text with the completion output (one candidate per line). For executable mode with a non-`carapace-bin` bridge: JSON-marshalled invoked action. On error, the response has `isError: true` with the error message as text.

**Examples:**

```json
// Complete git branches after "git checkout " (default mode)
{"args": ["git", "checkout", ""]}

// Complete docker subcommands (default mode)
{"args": ["docker", ""]}

// Complete tail using zsh bridge (bridge mode)
{"args": ["tail", ""], "bridge": "zsh"}

// Complete git using cobra bridge (bridge mode)
{"args": ["git", ""], "bridge": "cobra"}

// Complete using a custom carapace-bin executable (executable mode - needs confirmation)
{"args": ["git", "checkout", ""], "executable": "/path/to/carapace", "bridge": "carapace-bin"}

// Complete using a custom executable with cobra bridge (executable mode - needs confirmation)
{"args": ["myapp", ""], "executable": "/path/to/myapp", "bridge": "cobra"}

// Complete using a custom carapace-bin executable with explicit bridge variant
{"args": ["git", ""], "executable": "/path/to/carapace", "bridge": "carapace-bin/cobra"}
```

**CLI equivalents:**

The command name (`args[0]`) appears **twice** in the CLI form: once as `<cmd>` to select the completer, and again as the first element of `<args...>` since the args array is passed verbatim. For example, `{"args": ["git", "checkout", ""]}` maps to `carapace git export git checkout ""`.

| Mode | MCP input | CLI equivalent |
|------|-----------|----------------|
| Default | `{"args": ["git", "checkout", ""]}` | `carapace git export git checkout ""` |
| Bridge only | `{"args": ["tail", ""], "bridge": "zsh"}` | `carapace tail/zsh export tail ""` |
| Executable + carapace-bin | `{"args": ["git", ""], "executable": "/p/carapace", "bridge": "carapace-bin"}` | `/p/carapace git export git ""` |
| Executable + carapace-bin/bridge | `{"args": ["git", ""], "executable": "/p/carapace", "bridge": "carapace-bin/cobra"}` | `/p/carapace git/cobra export git ""` |
| Executable + other bridge | `{"args": ["myapp", ""], "executable": "/p/myapp", "bridge": "cobra"}` | cobra bridge calls `/p/myapp __complete myapp ""` directly |

### `complete_macro` — Macro Completion (currently disabled)

> **This tool is currently disabled** and not returned by `tools/list` ("TODO: re-enable complete_macro once macro invocation is properly implemented"). The schema below documents the intended interface for when it returns. To test a macro from the CLI instead, use `carapace --macro <name> <TAB>`.

Returns context‑aware, dynamic completions for a carapace macro.

**Input Schema:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `macro` | `string` | Yes | Macro name (e.g. `tools.git.Refs`) |
| `args` | `string[]` | Yes | Arguments to complete |
| `executable` | `string` | No | Path to the carapace executable providing the macro |

**How it works:**

1. **Default** (no `executable`): Invokes the current carapace binary with `_carapace macro <macro> <args...>`.

2. **Custom executable** (`executable` set): Resolves the executable path and invokes it with the same arguments. **This requires user confirmation** since it executes an arbitrary binary.

**Constraints:**

- `macro` is required
- `args` is required
- Arguments must not contain NUL bytes (`\0`)

**Response:** Plain text containing the completion output (JSON with `values` array). On error, the response has `isError: true` with the error message as text.

**Examples:**

```json
// Complete git refs (default mode)
{"macro": "tools.git.Refs", "args": [""]}

// Complete git refs with opts (default mode)
{"macro": "tools.git.Refs", "args": ["{localbranches: true, remotebranches: true, tags: true}", ""]}

// Complete using a custom carapace executable (needs confirmation)
{"macro": "tools.git.Refs", "args": [""], "executable": "/path/to/carapace"}
```

**CLI equivalent:** `carapace _carapace macro <macro> <args...>`

### `list_macros` — Available Macros

Lists all available carapace macros with their names, signatures, descriptions, versions, and Go source references.

**Input Schema:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `executable` | `string` | No | Path to the carapace executable providing the macros |

**How it works:**

1. **Default** (no `executable`): Iterates the built-in `actions.Macros` map and returns each macro's name (prefixed with `carapace.`), signature, description, and Go source reference.

2. **Custom executable** (`executable` set): Resolves the executable path and invokes it with `_carapace macro` to retrieve the macro list. **This requires user confirmation** since it executes an arbitrary binary.

**Response:** JSON object with a `version` field (the main module version) and a `macros` array:

```json
{
  "version": "1.2.0",
  "macros": [
    {
      "name": "carapace.tools.git.Refs",
      "signature": "{localbranches: false, remotebranches: false, tags: false}",
      "description": "complete refs",
      "version": "1.2.0",
      "reference": "github.com/carapace-sh/carapace-bin/pkg/actions/tools/git#ActionRefs"
    },
    {
      "name": "carapace.tools.git.Tags",
      "signature": "—",
      "description": "complete tags",
      "version": "1.2.0",
      "reference": "github.com/carapace-sh/carapace-bin/pkg/actions/tools/git#ActionTags"
    }
  ]
}
```

The `version` field on each macro indicates the version of the module providing that action — for in-project packages this is the main module version, for external dependencies it is the dependency version.

When using a custom executable, the `name` field is prefixed with the executable name (e.g. `myexe.tools.git.Refs`), and the `function` field replaces `reference`:

```json
{
  "version": "unknown",
  "macros": [
    {
      "name": "myexe.files",
      "signature": "[\"\"]",
      "description": "",
      "version": "",
      "function": ""
    }
  ]
}
```

**Fields:**

| Field | Description |
|-------|-------------|
| `name` | Fully qualified macro name prefixed with the executable name (e.g. `carapace.tools.git.Refs` in default mode, `myexe.tools.git.Refs` with custom executable) |
| `signature` | Argument signature — see carapace-macro skill for format details. `—` (em dash) means no arguments (MacroN) |
| `description` | Short description of what the macro completes |
| `version` | Version of the module providing the action (main module version for in-project packages, dependency version for external packages) |
| `reference` | Go import path with `#FunctionName` for looking up source code (only in default mode) |
| `function` | Function reference (only when using a custom executable) |

**Use cases:**

- Discover which macros exist before using them in YAML specs or Go code
- Look up argument signatures to format macro calls correctly
- Find the Go source reference to understand parameters in detail
- List macros from a custom carapace-spec binary

**CLI equivalent:** `carapace --macro` (default) or `<executable> _carapace macro` (custom executable)

### `codegen` — Generate Go Code from YAML Spec

Generates Go completer source code from a carapace YAML spec file. This is useful for converting a user spec into a native Go completer that can be built into carapace-bin.

**Input Schema:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | `string` | Yes | Path to the YAML spec file (relative or absolute) |

**How it works:**

1. Resolves `path` to an absolute path (relative paths are resolved from the server's working directory)
2. Invokes `carapace --codegen <path>` internally
3. Scans the output for `.go` filenames that were generated
4. Returns a sorted JSON array of generated file paths

**Response:** JSON array of generated `.go` file paths as text:

```json
["cmd/root.go", "cmd/cache.go"]
```

On error (missing path, invalid spec, codegen failure), the response has `isError: true` with the error message as text.

**CLI equivalent:** `carapace --codegen <path>`

## MCP Tool to CLI Flag Mapping

| MCP Tool | CLI Command | Notes |
|----------|-------------|-------|
| `complete_command` | `carapace <cmd> export <args...>` | Default mode; bridge/executable modes use different invocations |
| `list_macros` | `carapace --macro` | Default mode; custom executable mode uses `<executable> _carapace macro` |
| `complete_macro` | `carapace _carapace macro <macro> <args...>` | Currently disabled in `tools/list` |
| `codegen` | `carapace --codegen <path>` | Shells out to the same executable |

## Relationship to Other Skills

| Skill | When to use instead of this skill |
|-------|----------------------------------|
| `carapace-macro` | Formatting macro arguments in specs/YAML, understanding MacroN/MacroI/MacroV types |
| `carapace-spec` | Writing YAML spec files (input for codegen) |
| `carapace-action` | Creating/modifying shared Go actions that become macros |
| `carapace-scrape` | Generating specs from CLI source code |
| `carapace-integrate` | Integrating carapace library into cobra-based CLIs |

## Error Handling

The MCP server returns errors in two ways:

1. **JSON-RPC errors** — For protocol-level failures (unknown method, invalid tool call parameters). Uses standard JSON-RPC error codes:
   - `-32601` — Method not found
   - `-32602` — Invalid params

2. **Tool errors** — For tool execution failures (command not found, invalid arguments, codegen failures). Returned as `isError: true` with the error message in the text content.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall