skills/.wiki/concepts/context7-setup.md

title, type, updated

title	type	updated
context7 setup: CLI-first (migrated from official plugin)	concept	2026-08-13

context7 setup: CLI-first (migrated from official plugin)

2026-04-28 (plugin era) → 2026-08-12 (CLI migration, setup-context7 v2.0.0).

Current state (canonical, since 2026-08-12)

Single source = the ctx7 CLI (npm), agent-neutral — any harness (pi / claude / hermes / codex) runs it in bash. No MCP registration, no plugin.

• CLI: ctx7 v0.5.8 installed globally (npm i -g ctx7).
• API key: ~/.config/projects-secrets/ctx7.env → CONTEXT7_API_KEY=<key> (our secrets convention, cf. interns.env / auth.toml).
• Works anonymously for basic queries; the key raises rate limits but does not change output.
• Legacy removed: plugin context7@claude-plugins-official uninstalled (installed_plugins + cache + pluginUsage), manual mcpServers.context7 entries cleaned from ~/.claude.json / ~/.claude/settings.json (top-level + project-scoped). Backups: ~/.claude.json.bak-<ts>, ~/.claude/settings.json.bak-<ts>.

Procedure: setup-context7 skill (skills/setup-context7/SKILL.md) — key discovery (search ctx7.env → env var → settings.json → .claude.json, reuse, never invent), confirmation gates before any mutation, smoke via ctx7 library (functional; works anonymously). Usage policy: using-context7 skill — ctx7 library <name> → ctx7 docs <libraryId> "<question>". Git Bash gotcha: library IDs start with / and path-convert — use //owner/repo double-slash.

Verification gotcha (commit 79baad1): ctx7 whoami answers "Not logged in" even with an env key — it's OAuth identity (ctx7 login), not a key check. The functional smoke is ctx7 library, not whoami.

History: plugin era (2026-04-28 → 2026-08-12, rollback reference only)

Before the CLI migration, context7 ran through the official MCP plugin context7@claude-plugins-official. The plugin's .mcp.json (after install): ~/.claude/plugins/cache/claude-plugins-official/context7/<version>/.mcp.json (version slug unknown).

The key was injected as a CLI flag into args: ["-y", "@upstash/context7-mcp", "--api-key", "ctx7sk-..."] (Upstash-recommended form for stdio; header / env block forms also supported). Three manual MCP registrations were deleted at the time (settings.json top-level, .claude.json top-level, and a project-scoped one in projects["…/snolla-admin-ui"].mcpServers.context7).

Plugin-update gotcha (moot since uninstall, keep for rollback): /plugin update / re-install overwrote the plugin's .mcp.json from the marketplace cache, dropping the --api-key flag — needed re-application after every update.

Rollback to the plugin path (if ever needed): restore the .bak-* files, reinstall the plugin (/plugin install context7@claude-plugins-official), re-inject the key, restart Claude Code. Full procedure is in the setup-context7 skill's Rollback section.

Why CLI-first

Context7 ships as both an HTTP MCP server and an npm CLI. The MCP path 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).

Why two skills

• using-context7 (policy, every-time): when to call, how to phrase queries, budget.
• setup-context7 (one-time, mutates user config): install, key reuse, legacy cleanup.

Mixing them would dilute the policy skill's description (worse triggering) and pull setup procedure into every library question. Template for future "X CLI + how-to-use-X" pairs.