claude-skills/skills/setup-context7/SKILL.md

---
name: setup-context7
version: 1.0.0
description: Installs and configures the official context7 MCP plugin (`context7@claude-plugins-official`), reuses the user's existing Context7 API key, and cleans out any manual `mcpServers.context7` entries from `~/.claude.json` and `~/.claude/settings.json`. Use this skill when the user says "install context7", "set up context7", "configure context7", "настрой context7", "установи context7", "context7 не работает", "context7 isn't working", or whenever the `mcp__context7__resolve-library-id` / `mcp__context7__query-docs` tools are missing in a session that needs library docs. Cross-platform — Windows / Linux / macOS. Mutates user-level config; pauses for confirmation before writing.
---

# setup-context7

> One-time skill that gets the official context7 plugin running with the user's existing API key, with manual MCP entries cleaned up. Stops at confirmation gates because the procedure modifies user-level config files.

## When to use

- User explicitly asks: install / set up / configure context7.
- A `using-context7`-driven task fails because `mcp__context7__*` tools aren't available.
- Migrating an existing manually-configured context7 to the official plugin.

## Out of scope

- Creating a *new* API key. This skill *reuses* a key the user already has; if there's no key, offer the OAuth flow (`npx ctx7 setup`) and stop.
- Rolling back from the official plugin to manual config.
- Any non-context7 MCP server.

## Hard rule: don't auto-mutate config

The procedure modifies `~/.claude.json` and `~/.claude/settings.json`. **Always pause for explicit confirmation between Phase 1 (discovery, read-only) and Phase 2 (plan), and again before Phase 3 (backup + writes).** A trigger phrase is permission to run discovery, not permission to overwrite config.

## Procedure

### Phase 0 — Environment sanity

- Confirm Claude Code is the current harness (need `/plugin install` capability).
- Confirm `npx` is on `PATH` (the plugin spawns `npx -y @upstash/context7-mcp`). If missing, install Node.js first.
- Pick paths: `~/.claude/` works on all three OSes. In git-bash on Windows, `~` resolves correctly.

### Phase 1 — Discovery (read-only)

Search, in order. Stop reporting verbatim values for keys; report only "found at <path>".

**Existing API key.** Look in priority order:

1. `~/.claude/settings.json` → `mcpServers.context7.headers.CONTEXT7_API_KEY`
2. `~/.claude.json` → top-level `mcpServers.context7.headers.CONTEXT7_API_KEY`
3. `~/.claude.json` → `projects.<any>.mcpServers.context7.headers.CONTEXT7_API_KEY`
4. `~/.claude/settings.local.json` if present
5. Env var `CONTEXT7_API_KEY`

The first hit wins. Capture the key value internally for Phase 5; **never echo it in chat**.

**Manual context7 MCP entries.** Find every `mcpServers.context7` block in `~/.claude.json` and `~/.claude/settings.json` (top-level and project-scoped). Note all locations.

**Plugin install state.** Read `~/.claude/plugins/installed_plugins.json` and check for `context7@claude-plugins-official`.

**Plugin's `.mcp.json` state** (only if plugin is installed). Path:
```
~/.claude/plugins/cache/claude-plugins-official/context7/<version>/.mcp.json
```
`<version>` is often `unknown` for un-tagged marketplace plugins. List the cache dir to find it. Check whether `--api-key` is already in `args`.

### Phase 2 — Plan + confirm

Present a single-block plan to the user:

```
API key:        <found-at | NOT FOUND — will ask>
Plugin:         <installed | will ask user to /plugin install>
Manual entries: <list of paths to remove>
Backups:        ~/.claude.json.bak-<ts>, ~/.claude/settings.json.bak-<ts>
```

Wait for explicit confirmation ("ok", "go", "поехали"). Anything else → stop.

If no API key was found in Phase 1 — first ask: "Paste a Context7 API key, or run `npx ctx7 setup` to get one (OAuth)?" Don't proceed past Phase 2 without a key.

### Phase 3 — Backup

Copy each file we will modify to `<file>.bak-YYYYMMDD-HHMMSS`:
```bash
TS=$(date +%Y%m%d-%H%M%S)
cp ~/.claude.json ~/.claude.json.bak-$TS
cp ~/.claude/settings.json ~/.claude/settings.json.bak-$TS
```
Confirm both backups exist before any further edit.

### Phase 4 — Plugin install (if needed)

If the plugin is **not** in `installed_plugins.json`:
1. Ask the user to run `/plugin install context7@claude-plugins-official` in Claude Code (we can't run interactive slash commands).
2. Wait for "поставил" / "installed".
3. Verify by re-reading `installed_plugins.json`.

If the plugin **is** already installed: skip this phase.

### Phase 5 — Inject `--api-key`

Find the live plugin file:
```
~/.claude/plugins/cache/claude-plugins-official/context7/<version>/.mcp.json
```

If the file's `args` already contains `--api-key`, skip. Otherwise edit `args` to append `"--api-key", "<KEY>"`. Final shape:

```json
{
  "context7": {
    "command": "npx",
    "args": ["-y", "@upstash/context7-mcp", "--api-key", "<KEY>"]
  }
}
```

Per Upstash's client-config docs (<https://context7.com/docs/resources/all-clients>), `--api-key` is the recommended form for stdio transport. Header form is for HTTP transport (which the plugin doesn't use).

### Phase 6 — Clean manual entries

For each manual entry found in Phase 1:

- **Top-level `mcpServers.context7`** in `settings.json` or `.claude.json` → remove the `context7` key. Preserve sibling MCP servers and JSON validity (watch for trailing commas).
- **Project-scoped `projects.<path>.mcpServers.context7`** in `.claude.json` → remove. If the parent `mcpServers` becomes empty, leave it as `{}` (don't delete the key — Claude Code may rely on its presence).

After each edit, validate JSON. On any platform:
```bash
# Windows (PowerShell)
powershell.exe -NoProfile -c "Get-Content '<file>' -Raw | ConvertFrom-Json | Out-Null"
# Linux / macOS (jq) — install via brew/apt if missing
jq empty <file>
# fallback: python (always available)
python -c "import json,sys; json.load(open('<file>'))"
```

If validation fails → restore the just-edited file from its `.bak-*` and abort with a clear report. Do not continue editing.

### Phase 7 — Smoke test (best-effort)

Call `mcp__context7__resolve-library-id` with a benign query (e.g. `libraryName: "Nuxt"`, `query: "smoke test"`). If it returns library IDs — context7 is reachable in *this* session.

**Important caveat to relay to the user:** in the *same* session that just ran setup, the MCP server is still the legacy connection bound at session start. So a passing smoke test only proves "context7 still works" — not "the plugin is what's serving it". The real test is after Claude Code restart.

### Phase 8 — Restart guidance + final report

Tell the user:

```
✅ Setup complete. Restart Claude Code to pick up the plugin's stdio transport.

After restart:
  • mcp__context7__* tools will be served by `npx @upstash/context7-mcp --api-key …`
  • Manual entries are gone — single source of truth is the plugin's .mcp.json.
  • Backups saved at ~/.claude.json.bak-<ts> and ~/.claude/settings.json.bak-<ts>.

If something breaks after restart:
  • Restore from .bak-* files and tell me — we'll roll back together.
```

## Rollback procedure

If a problem surfaces (now or after restart):

1. Stop. Don't try to fix forward.
2. Find the most recent `.bak-YYYYMMDD-HHMMSS` next to `~/.claude.json` and `~/.claude/settings.json`.
3. `cp <file>.bak-<ts> <file>` for both.
4. Optional: `/plugin uninstall context7@claude-plugins-official`.
5. Restart Claude Code.
6. Confirm `mcp__context7__*` is back via the legacy HTTP path.
7. Report what went wrong so we can fix the procedure.

## Plugin-update gotcha

`/plugin update context7@claude-plugins-official` (or any reinstall) re-fetches the plugin's `.mcp.json` from the marketplace cache. That file is upstream-canonical and **does not** contain `--api-key` — the marketplace doesn't ship secrets. After any plugin update:

- Run this skill again. Phase 1 will detect the missing flag, Phase 5 will re-inject. Phases 4 and 6 are no-ops.
- Or manually re-add `--api-key` to `args` in the live `.mcp.json`.

The marketplace upstream is at `anthropics/claude-plugins-official/external_plugins/context7/.mcp.json`. It's two lines and rarely changes — the `--api-key` re-injection is the only ongoing maintenance cost.

## Cross-platform notes

The procedure is platform-agnostic. Only auxiliary tooling differs:

| | JSON validate | Backup |
|---|---|---|
| Windows (git-bash) | `powershell.exe -NoProfile -c "Get-Content '<f>' -Raw \| ConvertFrom-Json \| Out-Null"` | `cp` |
| Linux | `jq empty <f>` (or `python -c "import json; json.load(open('<f>'))"`) | `cp` |
| macOS | same as Linux | `cp` |

Path forms (`~/.claude/...`) are identical on all three.

## Common mistakes

- **Skipping Phase 1.** "User just said 'install context7' — let's go." No — find the existing key first; making the user paste a key when they already have one is rude.
- **Echoing the key.** It's a secret. The Edit / Write tool calls inevitably contain it (that's how it gets into the file), but no chat output should.
- **Mutating `.claude.json` without backup.** That file holds *all* of the user's per-project Claude Code state. Losing it is bad.
- **Treating in-session smoke test as proof.** It isn't — the active MCP connection is bound at session start.
- **Auto-running on every "use context7".** This skill is intrusive. Trigger only when explicitly invoked or when MCP tools are missing and the user is blocked.