vitya
d15fc3f9ef
Concept page (2026-04-28) still documented the plugin context7@claude-plugins-official as single source — stale vs setup-context7 v2.0.0 CLI-first migration (2026-08-12). Rewrote: CLI + key in ~/.config/projects-secrets/ctx7.env as canonical, plugin era demoted to rollback-only, whoami!=key-check gotcha recorded. Index entry + log updated. Surface: review finding on session-ritual-context7-pins-review (already closed VERDICT PASS).
69 lines
3.9 KiB
Markdown
69 lines
3.9 KiB
Markdown
---
|
|
title: "context7 setup: CLI-first (migrated from official plugin)"
|
|
type: concept
|
|
updated: 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`](../../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.
|