203 lines
10 KiB
Markdown
203 lines
10 KiB
Markdown
---
|
||
name: setup-context7
|
||
author: ours
|
||
version: 2.0.0
|
||
description: "Installs and configures the agent-neutral `ctx7` CLI (npm) for Context7 docs — CLI-first, no MCP registration. Reuses an existing Context7 API key or offers the OAuth flow, and migrates off the legacy context7 MCP plugin (`context7@claude-plugins-official`): uninstalls the plugin, cleans `mcpServers.context7` entries from `~/.claude.json` / `~/.claude/settings.json`. Use when the user says «настрой context7», «установи context7», «context7 не работает», \"set up context7\", \"install context7\", \"context7 isn't working\", or when a session needs library docs and the `ctx7` CLI is missing. Cross-platform — Windows / Linux / macOS. Mutates user-level config; pauses for confirmation before writing."
|
||
---
|
||
|
||
# setup-context7
|
||
|
||
> One-time skill that gets the **`ctx7` CLI** running with the user's existing Context7 key, and migrates off the legacy MCP plugin. Agent-neutral: any harness (pi / claude / hermes / codex) calls `ctx7` in bash — no MCP registration, no harness-specific tools. 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 the `ctx7` CLI isn't on PATH.
|
||
- Migrating an existing plugin/MCP-based context7 install to the CLI (legacy cleanup).
|
||
|
||
## Out of scope
|
||
|
||
- Creating a *new* API key. This skill *reuses* a key the user already has or offers the OAuth flow (`ctx7 login`); if the user has no key and no account, offer OAuth and stop.
|
||
- Rolling back from CLI to the plugin (not supported — CLI is the canonical path, idea 16 `claude-to-agents`).
|
||
- Any non-context7 MCP server.
|
||
|
||
## Hard rule: don't auto-mutate config
|
||
|
||
The procedure modifies `~/.claude.json`, `~/.claude/settings.json` and the plugin install state. **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.
|
||
|
||
## Prerequisites
|
||
|
||
- Node.js / npm on PATH (the CLI is an npm package). Check with `node -v`; if missing, install Node first.
|
||
- Git Bash gotcha (Windows): library IDs start with `/` and Git Bash path-converts them — `using-context7` documents the `//owner/repo` double-slash workaround.
|
||
|
||
## Procedure
|
||
|
||
### Phase 0 — Environment sanity
|
||
|
||
- Check whether `ctx7` is already installed: `ctx7 --version`. Installed → skip Phase 4 (install), proceed to Phase 5 (auth) / cleanup as needed.
|
||
- Pick paths: `~/.claude/` and `~/.config/projects-secrets/` work 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. `~/.config/projects-secrets/ctx7.env` → `CONTEXT7_API_KEY=` (our secrets convention, cf. `interns.env` / `auth.toml`)
|
||
2. Env var `CONTEXT7_API_KEY`
|
||
3. `~/.claude/settings.json` → `mcpServers.context7.headers.CONTEXT7_API_KEY`
|
||
4. `~/.claude.json` → top-level `mcpServers.context7.headers.CONTEXT7_API_KEY`
|
||
5. `~/.claude/settings.local.json` if present
|
||
|
||
The first hit wins. Capture the key value internally for Phase 5; **never echo it in chat**.
|
||
|
||
**Legacy MCP/plugin state** (migration targets — report locations, don't touch yet):
|
||
|
||
- Manual `mcpServers.context7` blocks in `~/.claude.json` and `~/.claude/settings.json` (top-level and project-scoped).
|
||
- Plugin installed: `~/.claude/plugins/installed_plugins.json` contains `context7@claude-plugins-official`?
|
||
- Plugin cache/data dirs: `~/.claude/plugins/cache/claude-plugins-official/context7/`, `~/.claude/plugins/data/context7*`.
|
||
|
||
### Phase 2 — Plan + confirm
|
||
|
||
Present a single-block plan to the user:
|
||
|
||
```
|
||
ctx7 CLI: <installed vX.Y.Z | will npm i -g ctx7>
|
||
API key: <found-at | NOT FOUND — will ask / offer OAuth>
|
||
Legacy to clean:
|
||
plugin: <installed | not installed>
|
||
manual MCP: <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 `ctx7 login` (OAuth, interactive)?" 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
|
||
cp ~/.config/projects-secrets/ctx7.env ~/.config/projects-secrets/ctx7.env.bak-$TS 2>/dev/null || true
|
||
```
|
||
|
||
Confirm backups exist before any further edit.
|
||
|
||
### Phase 4 — Install the CLI
|
||
|
||
```bash
|
||
npm install -g ctx7
|
||
ctx7 --version # verify
|
||
```
|
||
|
||
If the user prefers no global install: `npx -y ctx7 ...` works per-call (no install) — but for a standing setup, the global install is one-time and cheaper per call.
|
||
|
||
### Phase 5 — Auth (key or OAuth)
|
||
|
||
- **Key found** (Phase 1): write `~/.config/projects-secrets/ctx7.env`:
|
||
|
||
```
|
||
CONTEXT7_API_KEY=<KEY>
|
||
```
|
||
|
||
(if the file exists, merge the key in; never clobber sibling entries).
|
||
|
||
- **No key**: run `ctx7 login` (interactive OAuth, one-time, human runs it) or ask the user to paste a key.
|
||
|
||
Verify: `ctx7 library Nuxt "config"` должен вернуть ID библиотеки — это функциональный smoke (работает анонимно; env-ключ даёт повышенные лимиты, но не меняет вывод). Примечание: `ctx7 whoami` отвечает "Not logged in" даже с env-ключом — это OAuth-идентичность (`ctx7 login`), не проверка ключа; не считать ошибкой setup.
|
||
|
||
### Phase 6 — Clean legacy MCP/plugin (migration)
|
||
|
||
For each legacy item found in Phase 1:
|
||
|
||
- **Plugin** installed → uninstall via CLI:
|
||
|
||
```bash
|
||
claude plugin uninstall context7@claude-plugins-official
|
||
```
|
||
|
||
Then remove leftover cache/data dirs if any remain:
|
||
`~/.claude/plugins/cache/claude-plugins-official/context7/`, `~/.claude/plugins/data/context7*`.
|
||
|
||
- **Manual `mcpServers.context7`** in `settings.json` / `.claude.json` (top-level) → 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
|
||
|
||
Call the CLI with a benign query:
|
||
|
||
```bash
|
||
ctx7 library Nuxt "Nuxt 4 config and route rules"
|
||
```
|
||
|
||
If it returns library IDs / snippets — context7 works via CLI in *any* harness. (`ctx7 whoami` — OAuth-идентичность, отвечает "Not logged in" при env-ключе; не смоук-критерий.)
|
||
|
||
### Phase 8 — Restart guidance + final report
|
||
|
||
Tell the user:
|
||
|
||
```
|
||
✅ Setup complete. ctx7 CLI is agent-neutral — no MCP registration, no restart needed for other agents.
|
||
|
||
• Usage: ctx7 library <name> / ctx7 docs <libraryId> "<question>" (see using-context7)
|
||
• Key: ~/.config/projects-secrets/ctx7.env (CONTEXT7_API_KEY)
|
||
• Legacy: context7 plugin + mcpServers.context7 entries removed (single source = CLI)
|
||
• Backups saved at ~/.claude.json.bak-<ts> and ~/.claude/settings.json.bak-<ts>.
|
||
|
||
If something breaks after cleanup:
|
||
• Restore from .bak-* files and tell me — we'll roll back together.
|
||
```
|
||
|
||
## Rollback procedure
|
||
|
||
If a problem surfaces (now or later):
|
||
|
||
1. Stop. Don't try to fix forward.
|
||
2. Find the most recent `.bak-YYYYMMDD-HHMMSS` next to the modified files.
|
||
3. `cp <file>.bak-<ts> <file>` for each.
|
||
4. Optional: reinstall the plugin via `/plugin install context7@claude-plugins-official` if the user wants the MCP path back.
|
||
5. Restart Claude Code.
|
||
6. Confirm `mcp__context7__*` is back via the legacy path.
|
||
7. Report what went wrong so we can fix the procedure.
|
||
|
||
## 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/...`, `~/.config/projects-secrets/...`) 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.
|
||
- **Leaving the legacy plugin installed.** The point of the CLI migration is one agent-neutral path; a stale plugin means two sources of truth. Clean it in Phase 6.
|
||
- **Auto-running on every "use context7".** This skill is intrusive. Trigger only when explicitly invoked or when the CLI is missing and the user is blocked.
|
||
|
||
## Why CLI-first (design note)
|
||
|
||
Context7 is an HTTP MCP server + npm CLI. The MCP path (`context7@claude-plugins-official`) is harness-specific glue (claude-plugins-official); pi doesn't see it (the claude-mcp-bridge only reads `~/.claude.json`, and even then it's fragile). Per the sovereign-catalog principle *"что можно сделать CLI — делаем CLI и оборачиваем в скил; MCP только там, где нужен структурированный/интерактивный протокол"* — the CLI is the canonical path (idea 16, `claude-to-agents` running record).
|