Setup

---
description: "Verify or configure Context7 for this plugin's lookups. Check the ctx7 CLI, CONTEXT7_API_KEY auth, and the Context7 MCP server, then install/upgrade the CLI on request. Use when the user wants Context7 set up, verified, or repaired on this machine, covering CLI installation, API-key auth, and MCP server wiring: 'set up context7', 'is context7 working', 'install ctx7'. Actions: check (read-only verification, default) | apply (resolve what check found) | apply install-cli (also install/upgrade the ctx7 CLI)."
argument-hint: "[check|apply] [install-cli]"
user-invocable: true
disable-model-invocation: true
allowed-tools:
  - "Bash(ctx7 --version*)"
  - "Bash(npm view ctx7 version*)"
shell: bash
---

## Pre-computed context

Installed CLI version: !`ctx7 --version 2>/dev/null || echo "not installed"`

Latest published CLI version: !`npm view ctx7 version 2>/dev/null || echo "unknown (npm registry unreachable)"`

MCP availability: check your own tool list. If `mcp__context7__resolve-library-id` / `mcp__context7__query-docs` are present, the Context7 MCP server is already configured.

## Purpose

Bring the local environment to a working state for `/context7:lookup`. Two independent paths,
either alone sufficient: the **CLI** (`ctx7` via npm) and the **Context7 MCP server** (configured
by the consuming project). An optional `CONTEXT7_API_KEY` raises rate limits for both.

Check-centric per the uniform setup contract (`docs/plugin-philosophy.md`
"Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports,
`apply` resolves what `check` found, and the CLI install is a distinct opt-in subaction.
Idempotent and transparent: safe to rerun.

Action routing: no argument or `check` runs the check; `apply` runs the check first, then the
guidance-only remediations (auth, MCP routing); `apply install-cli` additionally authorizes the
global `ctx7` install/upgrade below. All actions are non-interactive when the action is given.
Never prompt.

## `check` (read-only)

Work top-down from the pre-computed context and report a PASS/FAIL/INFO table with one
remediation line per FAIL. Do not install, edit config, or write anything.

1. **CLI path**. From the pre-computed block: is `ctx7` installed, and does it match the latest
   published version? A working, current CLI is PASS. Installed-but-behind is INFO with
   remediation `apply install-cli`. Absent is INFO only when the MCP path is live (below);
   otherwise it is a FAIL of the "at least one path works" requirement.
2. **MCP path**. Is the Context7 MCP server present in your tool list? Present is PASS; absent is
   INFO. The MCP interface is optional; the CLI alone is sufficient.
3. **At least one path**. FAIL only when neither the CLI nor the MCP server resolves; every
   lookup would then be blocked. Remediation: `apply install-cli`, or add the MCP server (routed
   in `apply`).
4. **Auth**. INFO: report whether `CONTEXT7_API_KEY` is present in the environment
   (`[ -n "$CONTEXT7_API_KEY" ]`). Report presence only. Never print or echo the value.
   Anonymous usage works at low rates, so absence is never a FAIL.
5. **Windows Git Bash**. INFO: CLI `ctx7 docs /org/project "..."` calls must be prefixed with
   `MSYS_NO_PATHCONV=1` (a no-op on macOS/Linux, so it is safe to always include), or the `/org/project`
   ID gets path-mangled. Full explanation:
   `${CLAUDE_PLUGIN_ROOT}/skills/lookup/context/cli.md`.

## `apply` (idempotent)

Run `check`, then resolve each finding. Re-running after both paths are working changes nothing
and reports "already configured". State each change before making it, and re-detect before
claiming it.

1. **`apply install-cli` installs or upgrades the CLI.** Only with this subaction, and only when
   `check` found `ctx7` missing or behind latest:

   ```bash
   npm install -g ctx7@latest
   ```

   No global install available? `npx ctx7@latest <command>` works per-invocation. Version floor,
   npx trade-offs, and the full command/flag reference:
   `${CLAUDE_PLUGIN_ROOT}/skills/lookup/context/cli.md`. After installing, re-read the CLI version
   and report the observed result. Never claim upgraded on the install command's exit code alone.

2. **Auth (optional, both paths). Guidance only.** For higher limits, direct the user to set
   `CONTEXT7_API_KEY` in their own shell profile / secret store:

   ```bash
   export CONTEXT7_API_KEY="<your-key>"
   ```

   Prefer this over `ctx7 login`. Never write the key into the repository, Claude Code settings,
   or an MCP config file, and never print its value. An environment-variable change takes effect
   in a fresh session; report its presence only and defer verification to that fresh session.
   Rationale and the `ctx7 login` caveat: `${CLAUDE_PLUGIN_ROOT}/skills/lookup/context/cli.md`.

3. **MCP path (optional). Guidance only.** If the user wants the MCP interface (cleaner output,
   more content per call with the measured ratio in
   `${CLAUDE_PLUGIN_ROOT}/skills/lookup/context/mcp.md`, no Windows ceremony), route them to add a `context7` server entry
   to *their own* MCP configuration. The exact JSON, covering anonymous and API-key forms plus the
   "unset env var breaks config parsing" caveat, lives in
   `${CLAUDE_PLUGIN_ROOT}/skills/lookup/context/mcp.md`. Do not edit their `.mcp.json` for them.

4. **Verify.** Re-read the CLI version and your tool list. Confirm at least one path (CLI or MCP)
   is live before declaring setup complete.

## Output

Report what was already in place, what changed, what was skipped, and which lookup path(s) are now
available (CLI, MCP, or both).

## Boundaries

- Do not run `ctx7 setup` or `ctx7 skills install`. This plugin owns the lookup surface; those
  install a parallel skill that fragments and clobbers it (detail in the CLI and update references).
- Do not run `ctx7 setup --mcp` or edit the consumer's `.mcp.json` without consent. Their MCP
  configuration is theirs to curate.
- Do not write `CONTEXT7_API_KEY` into the repository, Claude Code settings, or any config file, and
  never print its value; the key belongs in the environment or a secret store.
- Do not write the plugin cache, Claude Code user settings, or `pluginConfigs`. This skill brings the
  local environment to a working state for lookups; machine-wide Claude Code state belongs to the user
  and the harness, and the installed plugin cache is overwritten on the next plugin update.
- Do not perform library lookups. That is `/context7:lookup`.