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

name, description

name

description

setup-context7

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 ".

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:

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:

{
  "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:

# 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.