docs(wiki): context7-setup concept → CLI-first canonical
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).
This commit is contained in:
@@ -1,90 +1,68 @@
|
||||
---
|
||||
title: "context7 setup: official plugin + API key"
|
||||
title: "context7 setup: CLI-first (migrated from official plugin)"
|
||||
type: concept
|
||||
updated: 2026-04-28
|
||||
updated: 2026-08-13
|
||||
---
|
||||
|
||||
# context7 setup: official plugin + API key
|
||||
# context7 setup: CLI-first (migrated from official plugin)
|
||||
|
||||
_2026-04-28._
|
||||
_2026-04-28 (plugin era) → 2026-08-12 (CLI migration, setup-context7 v2.0.0)._
|
||||
|
||||
## Where the MCP server is now registered
|
||||
## Current state (canonical, since 2026-08-12)
|
||||
|
||||
Single source: the official plugin **`context7@claude-plugins-official`**.
|
||||
Single source = the **`ctx7` CLI** (npm), agent-neutral — any harness (pi / claude / hermes / codex)
|
||||
runs it in bash. **No MCP registration, no plugin.**
|
||||
|
||||
The plugin's `.mcp.json` (after install) lives at:
|
||||
```
|
||||
~/.claude/plugins/cache/claude-plugins-official/context7/<version>/.mcp.json
|
||||
```
|
||||
- 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>`.
|
||||
|
||||
For this user the version slug is `unknown` (marketplace plugin without a tagged release).
|
||||
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.
|
||||
|
||||
## API-key injection
|
||||
**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`.
|
||||
|
||||
The `@upstash/context7-mcp` npm package, run via stdio, accepts the key as a CLI flag (per Upstash docs at <https://context7.com/docs/resources/all-clients>):
|
||||
## History: plugin era (2026-04-28 → 2026-08-12, rollback reference only)
|
||||
|
||||
```json
|
||||
{
|
||||
"context7": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@upstash/context7-mcp", "--api-key", "ctx7sk-..."]
|
||||
}
|
||||
}
|
||||
```
|
||||
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`).
|
||||
|
||||
We injected the user's existing key (previously in HTTP-header form) into this `args` array. Header / `env` block forms are also supported, but the CLI flag is what Upstash recommends for stdio.
|
||||
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`).
|
||||
|
||||
## What was removed
|
||||
**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.
|
||||
|
||||
Three manual MCP registrations were deleted:
|
||||
**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.
|
||||
|
||||
| File | Where | Had API key? |
|
||||
|---|---|---|
|
||||
| `~/.claude/settings.json` | top-level `mcpServers.context7` | yes (header) |
|
||||
| `~/.claude.json` | top-level `mcpServers.context7` | yes (header) |
|
||||
| `~/.claude.json` | `projects["…/snolla-admin-ui"].mcpServers.context7` | no (legacy) |
|
||||
## Why CLI-first
|
||||
|
||||
Backups saved with suffix `.bak-YYYYMMDD-HHMMSS` next to each file.
|
||||
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`).
|
||||
|
||||
## ⚠️ Plugin-update gotcha
|
||||
## Why two skills
|
||||
|
||||
`/plugin update context7@claude-plugins-official` (or a fresh re-install) **will overwrite** the plugin's `.mcp.json` from the marketplace cache, dropping the `--api-key` flag. After any plugin update, re-apply the edit:
|
||||
- **`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.
|
||||
|
||||
```bash
|
||||
# inspect
|
||||
cat ~/.claude/plugins/cache/claude-plugins-official/context7/<version>/.mcp.json
|
||||
|
||||
# if --api-key is missing, re-inject
|
||||
```
|
||||
|
||||
The marketplace upstream of the plugin lives at `anthropics/claude-plugins-official/external_plugins/context7/.mcp.json` and is two lines — unlikely to change often, but we should expect to re-apply the flag after updates.
|
||||
|
||||
## Restart required to take effect
|
||||
|
||||
Claude Code reads MCP server configs at session start. The session in which this change was made keeps its old (HTTP-transport) connection until a restart. After restart, the plugin's stdio invocation takes over.
|
||||
|
||||
## Why this matters
|
||||
|
||||
Manual MCP entries in `~/.claude.json` / `settings.json` are easy to:
|
||||
- duplicate accidentally (we had three for one server)
|
||||
- forget about when sharing config
|
||||
- drift from the canonical version
|
||||
|
||||
The plugin centralizes the registration and gets versioned through the marketplace. The price is a single edit-after-update for the API key.
|
||||
|
||||
## Now captured as a skill
|
||||
|
||||
The procedure above is now formalized as the **`setup-context7`** skill ([`skills/setup-context7/SKILL.md`](../../skills/setup-context7/SKILL.md)). It runs the same algorithm with confirmation gates and key-discovery logic (search `settings.json` → `.claude.json` → env, reuse what's there, never invent). `using-context7` got a small **Prerequisites** section pointing at it.
|
||||
|
||||
### Why split into two skills
|
||||
|
||||
Two distinct concerns:
|
||||
|
||||
- **Policy** (every-time, short-running): when to call resolve-library-id, query budget, how to phrase queries — this lives in `using-context7`.
|
||||
- **Setup** (one-time, mutates user config): install plugin, inject key, clean manual entries — this lives in `setup-context7`.
|
||||
|
||||
Mixing them would make the policy skill ~2× larger, dilute its description (worse triggering), and make every library question pull setup procedure into context. The split is also a template for future "X plugin + how-to-use-X" skill pairs.
|
||||
|
||||
### Cross-platform
|
||||
|
||||
The setup skill is platform-agnostic. Only the JSON validator differs (PowerShell on Windows, `jq` / Python on Linux/macOS). Paths (`~/.claude/...`) are identical.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user