vitya
9d7d25223c
Split context7 concerns into two skills: - using-context7 (policy, every-time): when to call, how to query well - setup-context7 (infrastructure, one-time): install plugin, inject API key, clean manual MCP entries, with confirmation gates setup-context7 reuses an existing CONTEXT7_API_KEY by searching, in order: ~/.claude/settings.json → ~/.claude.json (top-level + project-scoped) → ~/.claude/settings.local.json → env. Asks the user only if nothing found. Cross-platform (paths identical on Win/Linux/macOS; only JSON validator differs). Phase-2 confirmation gate before any write; per-edit JSON validation; rollback procedure documented. using-context7 gets a small Prerequisites section pointing at setup-context7 when MCP tools are missing. Bonus fix: scripts/build.sh PS multi-arg bug. Comma-joined -Names didn't split into [string[]] when build.ps1 was invoked via -File. Now the bash side loops one PS invocation per skill. Wiki: extended .wiki/concepts/context7-setup.md with the design rationale (why split policy from setup) — template for future "X plugin + how to use X" pairs. index.md and log.md updated. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
91 lines
3.7 KiB
Markdown
91 lines
3.7 KiB
Markdown
---
|
||
title: "context7 setup: official plugin + API key"
|
||
type: concept
|
||
updated: 2026-04-28
|
||
---
|
||
|
||
# context7 setup: official plugin + API key
|
||
|
||
_2026-04-28._
|
||
|
||
## Where the MCP server is now registered
|
||
|
||
Single source: the official plugin **`context7@claude-plugins-official`**.
|
||
|
||
The plugin's `.mcp.json` (after install) lives at:
|
||
```
|
||
~/.claude/plugins/cache/claude-plugins-official/context7/<version>/.mcp.json
|
||
```
|
||
|
||
For this user the version slug is `unknown` (marketplace plugin without a tagged release).
|
||
|
||
## API-key injection
|
||
|
||
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>):
|
||
|
||
```json
|
||
{
|
||
"context7": {
|
||
"command": "npx",
|
||
"args": ["-y", "@upstash/context7-mcp", "--api-key", "ctx7sk-..."]
|
||
}
|
||
}
|
||
```
|
||
|
||
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.
|
||
|
||
## What was removed
|
||
|
||
Three manual MCP registrations were deleted:
|
||
|
||
| 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) |
|
||
|
||
Backups saved with suffix `.bak-YYYYMMDD-HHMMSS` next to each file.
|
||
|
||
## ⚠️ Plugin-update gotcha
|
||
|
||
`/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:
|
||
|
||
```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.
|