diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 90f792b2b7..976997747b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -96,6 +96,12 @@ "source": "./plugins/book-distill", "category": "knowledge", "tags": ["book", "distill", "pdf", "epub", "skill", "knowledge", "reference", "documentation"] + }, + { + "name": "context7", + "source": "./plugins/context7", + "category": "utilities", + "tags": ["context7", "documentation", "library-docs", "api-reference", "tooling", "skill"] } ] } diff --git a/.lycheeignore b/.lycheeignore new file mode 100644 index 0000000000..9687c821c8 --- /dev/null +++ b/.lycheeignore @@ -0,0 +1,7 @@ +# Lychee link-check exclusions. One regex per line (matches anywhere in URL). + +# Vendored upstream baselines (plugins/*/skills/*/vendor/) are byte-exact +# snapshots kept solely for drift diffing. Their relative links may point at +# upstream sibling files that are deliberately not vendored — do not check +# links that resolve into a vendor directory. +/plugins/[^/]+/skills/[^/]+/vendor/ diff --git a/README.md b/README.md index 5a3f3d593d..1ed4eca930 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ Browse and manage with `/plugin`. To refresh after updates: `/plugin marketplace | [`mcp-tool-audit`](plugins/mcp-tool-audit) | Skill | Audits MCP server tool definitions against MCP-spec and Anthropic tool-design criteria, returning a per-tool PASS/WARN/FAIL scorecard. Language-agnostic (Python, TypeScript, .NET). | | [`prototype`](plugins/prototype) | Skills | Builds throwaway code to answer a design question before committing to architecture. Ships two skills: `/prototype:logic` (an interactive terminal app over a portable state model) and `/prototype:ui` (radically different visual variants on one route). | | [`book-distill`](plugins/book-distill) | Skill | Distills a technical book (PDF or EPUB) into concept-organized, author-attributed skill reference files through a structured multi-session read-write pipeline, updating the target skill's routing table. | +| [`context7`](plugins/context7) | Skill | Looks up current library documentation, API references, and code examples via Context7 — a two-step resolve-then-query workflow over the `ctx7` CLI or the consumer's Context7 MCP server, plus an upstream drift-check `update` action. | Install one: `/plugin install @melodic-software`. diff --git a/plugins/context7/.claude-plugin/plugin.json b/plugins/context7/.claude-plugin/plugin.json new file mode 100644 index 0000000000..ca524d09c1 --- /dev/null +++ b/plugins/context7/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", + "name": "context7", + "version": "0.1.0", + "description": "Looks up current library documentation, API references, and code examples via Context7 (ctx7 CLI or the Context7 MCP server), with a two-step resolve-then-query workflow and an upstream drift-check action.", + "author": { + "name": "Melodic Software", + "email": "info@melodicsoftware.com" + }, + "license": "MIT", + "keywords": ["context7", "documentation", "library-docs", "api-reference", "tooling"] +} diff --git a/plugins/context7/README.md b/plugins/context7/README.md new file mode 100644 index 0000000000..5840f381b9 --- /dev/null +++ b/plugins/context7/README.md @@ -0,0 +1,70 @@ +# context7 + +A Claude Code plugin for looking up **current library documentation, API +references, and code examples** via [Context7](https://context7.com) — so +answers about libraries, frameworks, SDKs, and cloud services come from live +docs instead of stale training data. + +Invoke it with `/context7:context7` (or let Claude invoke it automatically when +a question names a library): + +```text +/context7:context7 react "useEffect cleanup" +/context7:context7 configure +/context7:context7 update +``` + +## What it does + +- **`lookup `** (default) — the two-step Context7 workflow: + resolve the library name to a `/org/project` ID, then query its docs. Works + through the `ctx7` CLI, or through the Context7 MCP server when the consuming + project has one configured (same backend, ~1.8× more content per call). +- **`configure`** — CLI install, `CONTEXT7_API_KEY` auth, and the Windows Git + Bash `MSYS_NO_PATHCONV=1` gotcha. +- **`update`** — checks the installed `ctx7` CLI against the latest npm release + (`--fix` upgrades it) and diffs Upstash's upstream reference skills against + the plugin's bundled `vendor/` baselines, reporting anything new for manual + review. It never auto-rewrites the skill. + +## Requirements + +- **`ctx7` CLI** (`npm install -g ctx7@latest`) for the CLI path — or a + Context7 MCP server configured in the consuming project for the MCP path. + Either alone is enough; the skill picks whichever is available. +- **`CONTEXT7_API_KEY`** (optional) — anonymous usage works at low rates; an + API key raises limits. Set it as an environment variable; never commit it. + +## Install + +```shell +/plugin marketplace add melodic-software/claude-code-plugins +/plugin install context7@melodic-software +``` + +## Configuration + +This plugin has no `userConfig` and ships **no MCP server** — it never opens a +network surface by itself beyond the lookups you ask for. Two optional +consumer-side settings: + +- `CONTEXT7_API_KEY` environment variable — higher rate limits for both CLI + and MCP paths. +- A `context7` entry in your own MCP configuration if you want the MCP path — + the skill documents the exact snippet and degrades cleanly to the CLI when + it is absent. + +## Data egress note + +Lookup queries (your library question text) are sent to the Context7 backend +(`context7.com` / `mcp.context7.com`). Don't put secrets in queries. The +`ctx7` CLI also sends anonymous usage telemetry by default — set +`CTX7_TELEMETRY_DISABLED=1` to opt out. The `update` action additionally +fetches two public files from `raw.githubusercontent.com` (Upstash's +reference skills) and reads the npm registry for the latest `ctx7` version — +read-only, nothing uploaded. + +## License + +MIT (SPDX-License-Identifier: MIT). See the LICENSE file at the root of the +melodic-software/claude-code-plugins repository. diff --git a/plugins/context7/skills/context7/SKILL.md b/plugins/context7/skills/context7/SKILL.md new file mode 100644 index 0000000000..20cc94ab58 --- /dev/null +++ b/plugins/context7/skills/context7/SKILL.md @@ -0,0 +1,101 @@ +--- +name: context7 +description: "Look up current library documentation, API references, and code examples via Context7 (ctx7 CLI or the Context7 MCP server — same backend) whenever a question names a library, framework, SDK, CLI tool, or cloud service, including API syntax, configuration, setup, and version-migration questions. Actions: lookup (default) | configure (CLI/MCP setup, auth, Windows gotchas) | update (CLI upgrade + upstream drift check)." +argument-hint: "[lookup | configure | update] (default: lookup — e.g., /context7:context7 react \"useEffect cleanup\")" +user-invocable: true +disable-model-invocation: false +allowed-tools: + - "Bash(ctx7 --version*)" +metadata: + upstream-version: upstash/context7@master + synced: 2026-05-22 +--- + +## Pre-computed context + +Installed CLI version: !`ctx7 --version 2>/dev/null || echo "not installed (run: npm install -g ctx7@latest)"` + +MCP availability: check your own tool list — if `mcp__context7__resolve-library-id` / `mcp__context7__query-docs` are present, the MCP path is configured. + +## Purpose + +A primary source of up-to-date library documentation. Two equivalent interfaces: CLI (`ctx7`) via npm, and the Context7 HTTP MCP server (`mcp__context7__*`) when the consuming project has it configured. Both read the same backend. Pick by workflow (see [When to use CLI vs MCP](#when-to-use-cli-vs-mcp)). + +**Philosophy**: training data is stale by the time you use it. Library APIs, framework defaults, best practices change. Before claiming how a library works, verify against Context7 — even for libraries you "know." + +## Actions + +| Action | When | Loads | +|---|---|---| +| `lookup ` (default) | User asks about a library | [context/lookup.md](context/lookup.md) | +| `update` | Drift check + CLI upgrade + upstream skill changes | [context/update.md](context/update.md) | +| `configure` | First-time setup, auth, env vars, Windows gotchas | [context/cli.md](context/cli.md) | + +If the argument is bare (no action keyword), treat as `lookup`. + +## Lookup (happy path) + +Two-step: resolve library name → fetch docs with resolved ID. + +```bash +# Step 1: name → Context7 library ID +ctx7 library "" "" +# Step 2: ID → docs (Windows Git Bash: prefix with MSYS_NO_PATHCONV=1 — see context/cli.md) +MSYS_NO_PATHCONV=1 ctx7 docs "" "" +``` + +Equivalent via MCP when the consuming project has the Context7 MCP server configured (no Windows gotcha, cleaner output, returns ~1.5-2× more content): + +```text +mcp__context7__resolve-library-id(libraryName: "...", query: "...") +mcp__context7__query-docs(libraryId: "/org/project", query: "...") +``` + +You MUST call `library` / `resolve-library-id` first to get a valid ID, UNLESS the user provides one in `/org/project` format. One concept per query — when a question spans several independent topics, run a separate lookup per topic. Do not run more than 3 lookup commands per topic — if you cannot find what you need, fall back to training knowledge and tell the user Context7 didn't cover it. + +**Do not include sensitive information** (API keys, passwords, credentials) in queries — sent to the Context7 backend. + +Details: query-writing, result selection, version-specific IDs, common mistakes → [context/lookup.md](context/lookup.md) + +## When to use CLI vs MCP + +Both read the same backend — results equivalent in substance. Pick by workflow. + +| Use the CLI (`ctx7`) when | Use the MCP (`mcp__context7__*`) when | +|---|---| +| Piping into `grep`, `jq`, `head`, a file | Conversational lookup where the model picks the tool naturally | +| Dumping large docs to disk (`> docs.md`) instead of context | Default docs depth matters (MCP returns ~1.8× more content per call) | +| Scripting, loops, Bash one-liners | Clean markdown output (no ANSI codes) | +| No MCP server configured, or `mcp.context7.com` blocked | Zero Windows Git Bash ceremony (no `MSYS_NO_PATHCONV=1`) | +| Structured extraction (`--json`) | Auto-discoverable from the model's tool list | + +More: [context/cli.md](context/cli.md), [context/mcp.md](context/mcp.md) + +## Update + +Two upstream dependencies can drift: the `ctx7` npm package, and Upstash's reference skill content. Aggregate-level stale-tracking via `metadata.upstream-version` + `metadata.synced` in the frontmatter above; the verbatim upstream baselines under `vendor/` refresh together. + +When CLI or upstream skill content drifts: + +```bash +bash "${CLAUDE_PLUGIN_ROOT}/skills/context7/scripts/update.sh" # check only +bash "${CLAUDE_PLUGIN_ROOT}/skills/context7/scripts/update.sh" --fix # apply CLI upgrade +``` + +Script (a) reports installed vs latest `ctx7` version, (b) fetches latest upstream `find-docs/SKILL.md` and `context7-cli/SKILL.md` from `upstash/context7`, (c) diffs against the `vendor/` baselines, (d) if different, reports NEW upstream guidance for manual integration into this skill. The script does NOT auto-overwrite this `SKILL.md` — customizations (Windows gotcha, CLI-vs-MCP guidance, action dispatch) must be preserved. + +Full protocol (merge strategy, what to preserve, maintainer-only baseline refresh) → [context/update.md](context/update.md) + +## What this skill does NOT do + +- **Does not replace multi-source research** — use your research workflow for architecture decisions or anything needing cross-referenced sources. This skill is library-doc retrieval only +- **Does not refactor code** — retrieves docs. User's question shapes what comes back +- **Does not cache content locally** — docs fetched fresh each call. `vendor/` baseline is verbatim upstream for skill-content drift detection only, not doc retrieval (do NOT read `vendor/` for normal lookup invocations; only when running the `update` action) +- **Does not auto-overwrite on update** — `update` is advisory. User approves any merge before changes land + +## Gotchas + +- **Windows Git Bash**: `ctx7 docs /org/project "..."` gets path-mangled to `C:/Program Files/Git/org/project`. Always prefix with `MSYS_NO_PATHCONV=1`. `ctx7 library` is unaffected. Full detail: [context/cli.md](context/cli.md) +- **Prefer the `CONTEXT7_API_KEY` env var over `ctx7 login`**: `ctx7 login` triggers browser OAuth and writes a token to `~/.ctx7/` — the env var is simpler and portable across machines. See [context/cli.md](context/cli.md) +- **No content tuning**: CLI has no `--tokens` / `--limit` flag. Default depth is server-controlled. For more content per call, prefer MCP (returns ~1.8× more by default) +- **Don't run `ctx7 skills install` into `.claude/skills/`**: this plugin owns the Context7 lookup surface. Installing Upstash's `find-docs` skill alongside creates a parallel surface that fragments lookups and drifts independently diff --git a/plugins/context7/skills/context7/context/cli.md b/plugins/context7/skills/context7/context/cli.md new file mode 100644 index 0000000000..edd80a712a --- /dev/null +++ b/plugins/context7/skills/context7/context/cli.md @@ -0,0 +1,135 @@ +# CLI reference (`ctx7`) + +Install, configure, command reference, flags, env vars, and Windows-specific gotchas. + +## Install + +```bash +npm install -g ctx7@latest +ctx7 --version # 0.3.13 or later +``` + +Fallback (no global install): `npx ctx7@latest ` — slower per-invocation, no PATH ceremony. + +## Authentication + +CLI works anonymously for low-rate usage. For higher limits, set the `CONTEXT7_API_KEY` env var: + +```bash +export CONTEXT7_API_KEY="" +``` + +Set it wherever your project manages local environment variables (shell profile, a gitignored local settings file, or your secret manager) — never commit the key. + +**Prefer the env var over `ctx7 login`** — `login` triggers browser OAuth and writes a token to `~/.ctx7/`. The env-var approach is simpler, cross-machine-portable, and doesn't pollute the user profile. If `login` was run anyway, it's harmless but redundant — delete `~/.ctx7/` to revert. + +## Commands + +| Command | Purpose | +|---|---| +| `ctx7 library ` | Resolve library name → Context7 library ID | +| `ctx7 docs ` | Fetch documentation for a resolved library | +| `ctx7 setup [flags]` | Configure Context7 for an IDE (this plugin does NOT use it — see below) | +| `ctx7 login` / `logout` / `whoami` | OAuth flow (this plugin does NOT use it — env var is enough) | +| `ctx7 skills install [skill]` | Install skills from a GitHub repo (this plugin does NOT use it — see below) | +| `ctx7 skills search ` | Search the Context7 skills registry | +| `ctx7 skills suggest` | Auto-suggest skills based on project dependencies | +| `ctx7 skills info ` | Show skills available in a repository | +| `ctx7 skills generate` | Interactive AI skill generator (Pro feature, requires login) | +| `ctx7 skills list` | List installed skills in the current directory | +| `ctx7 skills remove ` | Uninstall a skill | + +Short aliases: `ctx7 skills` ↔ `ctx7 skill`, `install` ↔ `i`, `list` ↔ `ls`, `search` ↔ `s`, `generate` ↔ `gen/g`. + +## Flags + +### Global + +| Flag | Default | Purpose | +|---|---|---| +| `--base-url ` | `https://context7.com/api` | Point at a custom Context7 backend | +| `-V, --version` | | Print version | +| `-h, --help` | | Help for the current command | + +### Per-command (`library`, `docs`) + +| Flag | Purpose | +|---|---| +| `--json` | Structured JSON output (vs. formatted text). Useful for scripts / `jq` extraction | + +**No `--tokens`, `--limit`, `--format`, or `-v/--verbose` flag exists.** Default content depth is server-controlled. For more content per call, prefer MCP (`mcp__context7__query-docs`) — returns ~1.8× more content by default. + +### Setup / install flags (why this plugin doesn't use them) + +`ctx7 setup --claude --project --cli` and `ctx7 skills install /upstash/context7 find-docs --claude --yes` both install Upstash's skills into `.claude/skills/`. **This plugin does not use these** because: + +1. They create a parallel `find-docs/` skill that fragments the lookup surface — this plugin owns the lookup workflow +2. `ctx7 skills install` re-fetched overwrites local customizations with zero warning — it would destroy the Windows gotcha notes, CLI-vs-MCP guidance, and action dispatch +3. This plugin's `update` action ([update.md](update.md)) fetches upstream skill content for diffing, but integrates changes manually — a human reviews the merge + +## Environment variables + +| Variable | Purpose | +|---|---| +| `CONTEXT7_API_KEY` | Higher rate limits + priority. Required for `ctx7 skills generate` | +| `CTX7_TELEMETRY_DISABLED` | Set to `1` to disable the CLI's anonymous usage telemetry | + +The CLI sends anonymous usage telemetry **by default** (see the Telemetry section of Context7's CLI docs at context7.com/docs/clients/cli). In privacy-sensitive environments, disable it per invocation (`CTX7_TELEMETRY_DISABLED=1 ctx7 docs ...`) or permanently by exporting the variable in your shell profile. + +## Windows Git Bash gotcha (REQUIRED for `docs`) + +On Windows with Git Bash / MSYS2, any CLI argument starting with `/` is rewritten to a Windows path. When you run: + +```bash +ctx7 docs /facebook/react "useEffect cleanup" +``` + +Git Bash converts `/facebook/react` → `C:/Program Files/Git/facebook/react` before the CLI sees it. The CLI correctly rejects the malformed ID: + +```text +✖ Invalid library ID: "C:/Program Files/Git/facebook/react" +``` + +**Always prefix `ctx7 docs` calls with `MSYS_NO_PATHCONV=1`:** + +```bash +MSYS_NO_PATHCONV=1 ctx7 docs /facebook/react "useEffect cleanup" +``` + +- Prefix disables MSYS path conversion for that one invocation +- No-op on macOS/Linux — safe to always include +- Double-slash workaround (`//facebook/react`) does **not** work — ctx7 rejects it as malformed +- `ctx7 library` is unaffected (its first argument doesn't start with `/`) + +This is a Git Bash quirk, not a `ctx7` bug. Any CLI taking `/org/project`-style IDs hits the same thing on Windows. + +## Composability (CLI's main advantage over MCP) + +Output goes to stdout in formatted text (with ANSI color codes) or JSON with `--json`. Common pipe patterns: + +```bash +# Filter docs for a specific keyword +MSYS_NO_PATHCONV=1 ctx7 docs /facebook/react "hooks" | grep -A3 -i useEffect + +# Strip ANSI for clean grep output +MSYS_NO_PATHCONV=1 ctx7 docs /facebook/react "hooks" | sed 's/\x1b\[[0-9;]*m//g' | grep useEffect + +# Dump to disk (keeps context clean) +MSYS_NO_PATHCONV=1 ctx7 docs /vercel/next.js "app router" > /tmp/nextjs-router.md + +# Extract library IDs from a search +ctx7 library react "hooks" --json | jq -r '.[0].id' + +# Top 3 by benchmark score +ctx7 library "Entity Framework Core" "tracking" --json | jq 'sort_by(-.benchmarkScore) | .[0:3] | .[].id' +``` + +## When to prefer the CLI (summary) + +- Pipe into `grep` / `jq` / `head` / a file +- Dump large docs to disk instead of context +- Scripting, loops, Bash one-liners +- No MCP server configured, or restricted networks where `mcp.context7.com` is blocked +- Structured extraction with `--json` + +When not to: conversational lookups where the model picks the tool — MCP is more discoverable and returns more content. See [mcp.md](mcp.md) for that side. diff --git a/plugins/context7/skills/context7/context/lookup.md b/plugins/context7/skills/context7/context/lookup.md new file mode 100644 index 0000000000..c63b3151ea --- /dev/null +++ b/plugins/context7/skills/context7/context/lookup.md @@ -0,0 +1,109 @@ +# Lookup workflow + +Two-step library → docs pattern, query-writing guidance, result selection, common mistakes. + +## Step 1: Resolve a library name to a Context7 library ID + +```bash +# CLI +ctx7 library "" "" + +# MCP +mcp__context7__resolve-library-id(libraryName: "", query: "") +``` + +- Use the **official library name** with proper punctuation — `"Next.js"` not `"nextjs"`, `"Customer.io"` not `"customerio"`, `"Three.js"` not `"threejs"` +- `query` argument is **required** and directly affects result ranking. Distill the user's intent into a focused library/topic query — disambiguates when multiple libraries share a name +- Queries are sent to Context7's backend. Never include secrets (API keys, passwords, credentials), personal data, proprietary code, pasted stack traces, or internal endpoints/identifiers — send distilled library/topic terms only + +## Result fields + +Each result includes: + +- **Library ID** — Context7-compatible identifier (format: `/org/project`) +- **Title** — library or package name +- **Description** — short summary +- **Code Snippets** — number of available code examples (higher = better coverage) +- **Source Reputation** — `High` / `Medium` / `Low` / `Unknown` (prefer High/Medium) +- **Benchmark Score** — quality indicator, 100 is max (higher is better) +- **Versions** — list of versions if indexed. Use a version-specific ID when the user specifies a version + +## Selection process + +1. Analyze the query to understand what library the user wants +2. Rank candidates by: + - Name similarity to query (exact matches prioritized) + - Description relevance + - Code snippet count (coverage) + - Source reputation (prefer High or Medium) + - Benchmark score (higher is better) +3. If multiple good matches exist, acknowledge this but proceed with the most relevant one +4. If no good matches exist, state this clearly and suggest a refined query +5. For ambiguous cases, ask the user before guessing + +## Step 2: Query documentation + +```bash +# CLI (Windows Git Bash requires MSYS_NO_PATHCONV=1 — see cli.md) +MSYS_NO_PATHCONV=1 ctx7 docs "" "" + +# MCP +mcp__context7__query-docs(libraryId: "/org/project", query: "") +``` + +### Version-specific IDs + +If the user mentions a specific version, use the version-specific ID: + +```bash +# Latest indexed +MSYS_NO_PATHCONV=1 ctx7 docs /vercel/next.js "app router middleware" + +# Version-specific (version format comes from the library result's Versions field) +MSYS_NO_PATHCONV=1 ctx7 docs /vercel/next.js/v14.3.0 "app router middleware" +``` + +## Writing good queries + +Query quality directly affects results. Be specific and include relevant details. + +| Quality | Example | +|---|---| +| Good | `"How to set up authentication with JWT in Express.js"` | +| Good | `"React useEffect cleanup function with async operations"` | +| Good | `"EF Core DbContext change tracking with QueryTrackingBehavior"` | +| Bad | `"auth"` | +| Bad | `"hooks"` | +| Bad | `"tracking"` | + +Distill the user's question into a focused query: keep the details that describe the library problem, drop everything else. When the question includes a pasted stack trace, code snippet, or internal endpoint/identifier, extract only the library and topic terms — never forward the raw content (e.g. a `NullReferenceException` trace from change-tracking code becomes `"EF Core DbContext change tracking null reference"`). Vague one-word queries return generic results. + +Keep each query to a **single concept**. When a prompt asks about several independent topics, split them and run a separate `docs` / `query-docs` lookup per topic — a combined query dilutes ranking and returns shallow results for every topic. Combine concepts in one query only when the question is about how they interact (e.g. `"Next.js middleware with NextAuth session validation"`). + +## Output content types + +Output contains two kinds of snippets: + +- **Code snippets** — titled, with language-tagged code blocks. Primary value +- **Info snippets** — prose explanations with breadcrumb context. Secondary value + +MCP returns ~1.8× more content per call than CLI at default settings. If a CLI response feels thin, re-run via MCP or re-issue with a more targeted query. + +## Quota / rate limit handling + +If a command fails with `"Monthly quota reached"` or `"quota exceeded"`: + +1. Inform the user their Context7 quota is exhausted +2. Confirm `CONTEXT7_API_KEY` is set in the environment (higher limits come with an API key — see [cli.md](cli.md)) +3. If they cannot or choose not to authenticate further, answer from training knowledge and **clearly note it may be outdated** + +Do not silently fall back to training data. Always tell the user why Context7 was unavailable. + +## Common mistakes + +- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react` +- Always run `library` / `resolve-library-id` first — `ctx7 docs react "hooks"` fails without a valid ID +- Use descriptive queries, not single words +- Do not include secrets, personal data, proprietary code, stack traces, or internal identifiers in queries — send distilled library/topic terms only +- Do not combine independent topics into one query — one concept per lookup +- Do not run more than **3 lookup commands per topic**. If you cannot find what you need in 3 attempts, fall back and tell the user diff --git a/plugins/context7/skills/context7/context/mcp.md b/plugins/context7/skills/context7/context/mcp.md new file mode 100644 index 0000000000..f1fdbf0b2b --- /dev/null +++ b/plugins/context7/skills/context7/context/mcp.md @@ -0,0 +1,76 @@ +# MCP reference (`mcp__context7__*`) + +Context7 HTTP MCP server — reads the same backend as the `ctx7` CLI. This plugin does NOT ship or auto-start an MCP server; the consuming project opts in by declaring it in its own MCP configuration. + +## Configuration (consumer-side, optional) + +Add to the consuming project's `.mcp.json` (or user-scope MCP config) — server entries live under the top-level `mcpServers` key. Anonymous (low-rate) usage needs no headers: + +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +With an API key (higher limits), add the `CONTEXT7_API_KEY` request header (the header name Context7's server expects) — but note Claude Code **fails to parse the config** when a referenced env var is unset with no default, so only use this form once `CONTEXT7_API_KEY` is actually set in your environment: + +```json +{ + "mcpServers": { + "context7": { + "type": "http", + "url": "https://mcp.context7.com/mcp", + "headers": { "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}" } + } + } +} +``` + +`CONTEXT7_API_KEY` is the same env var the CLI reads (see [cli.md](cli.md)). MCP sends it as a request header; CLI reads it from the environment. Both equivalent from a quota/auth perspective. Without the MCP server configured, every lookup in this skill works through the CLI path. + +## Tools exposed + +| Tool | Purpose | CLI equivalent | +|---|---|---| +| `mcp__context7__resolve-library-id` | Resolve library name → `/org/project` ID | `ctx7 library ` | +| `mcp__context7__query-docs` | Fetch docs for a resolved ID | `MSYS_NO_PATHCONV=1 ctx7 docs ` | + +Both tools require a `query` argument for result ranking. Same input shape as CLI, same backend, same output substance — different transport. + +## Why prefer MCP over CLI for most lookups + +Empirical observation (2026-04, React + EF Core test queries): + +| Dimension | Result | +|---|---| +| Default content per `query-docs` call | ~1.8× more than `ctx7 docs` at default settings | +| Output format | Clean markdown (no ANSI codes to strip) | +| Windows ceremony | None (no `MSYS_NO_PATHCONV=1` prefix) | +| Auto-discovery by the model | Tool appears in the tool list — model picks it naturally | +| Latency | ~2.1s (same as CLI — both network-bound) | + +**Default route for conversational library lookups is MCP** when it is configured. CLI's advantages kick in when you want composability (pipe to grep, dump to disk, script), not when you just want the answer. + +## When the MCP is unavailable + +- Not configured in the consuming project (this plugin doesn't ship it) +- Network restrictions (corporate proxies, some cloud sessions) +- `mcp.context7.com` blocked by local firewall +- Connection failed at session start (check `claude mcp list`) + +Fall back to CLI in those cases — same backend, different transport path. If both are blocked, check `CONTEXT7_API_KEY`, or fall back to other documentation sources and tell the user Context7 was unavailable. + +## Serialization and performance + +Observed behavior (not a documented guarantee): back-to-back `resolve-library-id` + `query-docs` calls complete serially (~2s each, ~4s for the pair) — no parallelism benefit. + +Irrelevant in practice — you always need the `library` result before the `docs` call — so serial is correct. + +## Do not re-configure via `ctx7 setup --mcp` + +`ctx7 setup --mcp` rewrites MCP configuration files and can modify the consuming project's `.mcp.json`. **Do not run it from this skill.** The consumer's MCP configuration is theirs to curate; if Upstash changes their recommended MCP URL or headers in a future release, the `update` action ([update.md](update.md)) surfaces that so the consumer can port the change deliberately. diff --git a/plugins/context7/skills/context7/context/update.md b/plugins/context7/skills/context7/context/update.md new file mode 100644 index 0000000000..9b517e4976 --- /dev/null +++ b/plugins/context7/skills/context7/context/update.md @@ -0,0 +1,71 @@ +# Update / drift protocol + +This skill has two upstream dependencies that can drift: + +1. The **`ctx7` npm package** (`npm view ctx7 version`) +2. **Upstash's reference skill content** (`https://raw.githubusercontent.com/upstash/context7/refs/heads/master/skills/find-docs/SKILL.md` and `.../skills/context7-cli/SKILL.md`) + +Neither is consumed verbatim — this plugin OWNS its skill surface. Upstream is advisory: watch for changes, evaluate, port anything worth keeping. No `find-docs/` skill installed alongside; no autogenerated files. + +## The update action + +```bash +# Report drift (no changes made) +bash "${CLAUDE_PLUGIN_ROOT}/skills/context7/scripts/update.sh" + +# Apply CLI upgrade; still advisory on skill content +bash "${CLAUDE_PLUGIN_ROOT}/skills/context7/scripts/update.sh" --fix +``` + +The script does four things: + +1. **CLI version check** — compares `ctx7 --version` (installed) with `npm view ctx7 version` (latest). With `--fix`, runs `npm install -g ctx7@latest` +2. **Upstream skill fetch** — pulls `find-docs/SKILL.md` and `context7-cli/SKILL.md` from `upstash/context7` master +3. **Baseline diff** — compares current upstream against the plugin's `vendor/find-docs/SKILL.md` (and `vendor/cli/SKILL.md`). Shows the diff as "what Upstash changed since the last review" +4. **Manual-integration prompt** — if diff is non-empty, prints the new upstream guidance for review and the files that might need touching + +**The script does NOT auto-write changes into `SKILL.md` or context files.** Upstash's content is stylistically different (YAML folded descriptions, different frontmatter, etc.) and would clobber this plugin's additions (Windows gotcha, action dispatch, CLI-vs-MCP comparison). The human in the loop decides what to port. + +## Roles: consumer vs plugin maintainer + +- **Consumers** run the default report mode (drift visibility) and `--fix` (CLI upgrade). Skill-content drift findings are input for an upstream issue or PR against the plugin's marketplace repository — not something to patch in the installed copy, which is an ephemeral cache overwritten on plugin update. +- **Plugin maintainers** port upstream changes in a working clone of the marketplace repository (using the `--plugin-dir` local development loop), then refresh the baseline there: + +```bash +bash "${CLAUDE_PLUGIN_ROOT}/skills/context7/scripts/update.sh" --refresh-baseline +``` + +This overwrites `vendor/find-docs/SKILL.md` (and `vendor/cli/SKILL.md`) with current upstream and stamps `synced:` in the skill frontmatter. It writes next to the script itself, so run it only in a working clone — never in the installed plugin cache. + +## What to preserve when integrating upstream changes + +When porting upstream additions, **keep** this plugin's customizations: + +| Customization | Where it lives | Why | +|---|---|---| +| Frontmatter shape | `SKILL.md` | Plugin conventions (`user-invocable`, `argument-hint`, `disable-model-invocation`, `metadata`) | +| `MSYS_NO_PATHCONV=1` gotcha | `SKILL.md`, `context/cli.md` | Empirically verified; Upstash doesn't document | +| CLI-vs-MCP comparison table | `SKILL.md`, `context/mcp.md` | Empirical findings | +| Action dispatch (`lookup`/`update`/`configure`) | `SKILL.md` | The `update` action has no upstream equivalent | +| Progressive-disclosure structure | `context/*.md` | Upstash ships single-file skills | +| "Do not run `ctx7 setup` / `skills install`" guidance | Multiple | This plugin owns the skill layer; Upstash expects their install flow | + +What to **adopt** from upstream (when present): + +- New commands or flags in examples (`ctx7` gains a new subcommand) +- New error handling / quota messages +- New env vars or config paths +- Changes to the library/docs API contract (new fields, ranking changes) +- New IDE-specific tips that apply to Claude Code + +## Escalation + +If the drift check surfaces a substantive behavioral change — new CLI subcommand, new auth model, new MCP transport, breaking change in the library/docs API — research primary sources (GitHub PRs, Upstash blog, release notes) before porting. Upstash's SKILL.md is not a changelog; it reflects the current state only. + +## What this action does NOT do + +- **Does not `ctx7 skills install`** — that overwrites the owned skill surface +- **Does not `ctx7 setup --mcp`** — that modifies the consumer's MCP configuration +- **Does not auto-merge upstream content** — the user approves every port +- **Does not refresh the baseline automatically** — only on `--refresh-baseline` after manual integration, so the baseline stays honest about "what was last reviewed" +- **Does not upgrade the CLI without `--fix`** — default is report-only diff --git a/plugins/context7/skills/context7/scripts/update.sh b/plugins/context7/skills/context7/scripts/update.sh new file mode 100755 index 0000000000..46c249c42b --- /dev/null +++ b/plugins/context7/skills/context7/scripts/update.sh @@ -0,0 +1,231 @@ +#!/usr/bin/env bash +# context7 update — drift check for ctx7 CLI version and upstream skill content. +# +# Modes: +# (default) report only — CLI version drift + upstream skill diff +# --fix install/upgrade CLI to latest; still advisory on skill content +# --refresh-baseline overwrite upstream snapshot with current upstream +# (maintainer-only: run in a working clone, never the installed cache) +# +# Exit codes: +# 0 — verified: no drift detected (or drift reported in report mode) +# 1 — prerequisites missing (npm, curl, diff not on PATH) +# 2 — state unverifiable OR requested fix/refresh failed +# (npm registry unreachable, upstream fetch failed, post-install PATH issue, +# baseline write failure; missing baseline in report mode surfaces as drift, exit 0) + +# No -e: check_skill_drift captures non-zero return codes via $? as drift signals, +# not failures. +set -uo pipefail + +MODE="${1:-report}" + +# All paths resolve relative to this script's own location, so the script works +# both in the installed plugin cache and in a working clone of the marketplace repo. +SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +SNAPSHOT_DIR="$SKILL_DIR/vendor" +SKILL_MD="$SKILL_DIR/SKILL.md" +BASELINE_FIND_DOCS="$SNAPSHOT_DIR/find-docs/SKILL.md" +BASELINE_CLI_SKILL="$SNAPSHOT_DIR/cli/SKILL.md" + +UPSTREAM_FIND_DOCS="https://raw.githubusercontent.com/upstash/context7/refs/heads/master/skills/find-docs/SKILL.md" +UPSTREAM_CLI_SKILL="https://raw.githubusercontent.com/upstash/context7/refs/heads/master/skills/context7-cli/SKILL.md" + +# --- prerequisite checks --- +for cmd in npm curl diff; do + if ! command -v "$cmd" >/dev/null 2>&1; then + echo "✖ Required command not found: $cmd" >&2 + exit 1 + fi +done + +mkdir -p "$SNAPSHOT_DIR/find-docs" "$SNAPSHOT_DIR/cli" + +# Verifies ctx7 is resolvable on PATH and prints a non-empty version. +# On success: prints version to stdout, returns 0. +# On failure: prints nothing to stdout, returns non-zero. +verify_ctx7_callable() { + local version + if ! command -v ctx7 >/dev/null 2>&1; then + return 1 + fi + version=$(ctx7 --version 2>/dev/null | tr -d '\r') + if [[ -z "$version" ]]; then + return 2 + fi + printf '%s\n' "$version" + return 0 +} + +install_and_verify() { + echo " ↳ Applying: npm install -g ctx7@latest" + if ! npm install -g ctx7@latest; then + echo " ✖ npm install failed" >&2 + return 2 + fi + local new_version + if ! new_version=$(verify_ctx7_callable); then + echo " ✖ npm install reported success but ctx7 is not callable on PATH" >&2 + echo " ↳ Check npm global bin: $(npm config get prefix 2>/dev/null)" >&2 + return 2 + fi + echo " ✓ CLI installed and verified: $new_version" + return 0 +} + +# --- CLI version check --- +echo "=== Context7 CLI version ===" +INSTALLED=$(verify_ctx7_callable) || INSTALLED="not-installed" +LATEST=$(npm view ctx7 version 2>/dev/null | tr -d '\r' || echo "") +echo " installed: $INSTALLED" +echo " latest: ${LATEST:-unknown}" + +if [[ "$INSTALLED" == "not-installed" ]]; then + if [[ "$MODE" == "--fix" ]]; then + install_and_verify || exit 2 + else + echo " ↳ ctx7 is not installed. Run with --fix, or manually: npm install -g ctx7@latest" + CLI_DRIFT=1 + fi +elif [[ -z "$LATEST" ]]; then + echo " ✖ Cannot verify latest version (npm view ctx7 failed)" >&2 + echo " ↳ CLI state is unverifiable until npm registry is reachable" >&2 + CLI_DRIFT=2 +elif [[ "$INSTALLED" != "$LATEST" ]]; then + echo " ↳ CLI is behind latest." + if [[ "$MODE" == "--fix" ]]; then + install_and_verify || exit 2 + else + echo " ↳ Run with --fix to upgrade, or manually: npm install -g ctx7@latest" + CLI_DRIFT=1 + fi +else + echo " ✓ CLI is current" +fi + +echo "" + +# --- upstream skill content check --- +# Return codes: +# 0 — upstream unchanged (or baseline seeded/refreshed successfully in --refresh-baseline mode) +# 1 — fetch failed or baseline write failed; state unverifiable +# 2 — drift detected (content differs, OR baseline missing in non-refresh mode) +check_skill_drift() { + local name="$1" + local url="$2" + local baseline="$3" + local tmpfile baseline_lf tmpfile_lf + tmpfile=$(mktemp) + baseline_lf=$(mktemp) + tmpfile_lf=$(mktemp) + # RETURN trap removes every temp file on all exit paths. + trap 'rm -f "$tmpfile" "$baseline_lf" "$tmpfile_lf"' RETURN + + if ! curl -fsSL "$url" -o "$tmpfile" 2>/dev/null; then + echo " ✖ Failed to fetch $url" >&2 + return 1 + fi + + echo "=== Upstream skill: $name ===" + if [[ ! -f "$baseline" ]]; then + echo " ↳ No baseline at $baseline" + if [[ "$MODE" == "--refresh-baseline" ]]; then + if ! cp "$tmpfile" "$baseline"; then + echo " ✖ Failed to seed baseline (check permissions/disk)" >&2 + return 1 + fi + echo " ✓ Baseline seeded ($(wc -c <"$baseline") bytes)" + return 0 + fi + echo " ↳ Run with --refresh-baseline to seed (until seeded, state is unverified)" + return 2 + fi + + # Normalize line endings before comparing — baseline may be CRLF on Windows + # checkouts, upstream is always LF. Without this, every Windows run reports + # false-positive drift. + tr -d '\r' <"$baseline" >"$baseline_lf" + tr -d '\r' <"$tmpfile" >"$tmpfile_lf" + + if diff -q "$baseline_lf" "$tmpfile_lf" >/dev/null 2>&1; then + echo " ✓ Upstream unchanged since last baseline" + return 0 + fi + + local diff_output diff_lines + diff_output=$(diff -u "$baseline_lf" "$tmpfile_lf") + diff_lines=$(printf '%s\n' "$diff_output" | wc -l | tr -d ' ') + echo " ↳ Drift detected ($diff_lines diff lines)" + echo "" + echo " --- new upstream content (for manual review) ---" + printf '%s\n' "$diff_output" | head -60 + if ((diff_lines > 60)); then + echo " ↳ (diff truncated to 60 of $diff_lines lines — run diff manually for full output)" + fi + echo "" + + if [[ "$MODE" == "--refresh-baseline" ]]; then + if ! cp "$tmpfile" "$baseline"; then + echo " ✖ Failed to refresh baseline (check permissions/disk)" >&2 + return 1 + fi + echo " ✓ Baseline refreshed to match current upstream" + return 0 + fi + + echo " ↳ To integrate (plugin maintainers, in a working clone):" + echo " 1. Review the diff above and decide what to port into:" + echo " $SKILL_DIR/SKILL.md" + echo " $SKILL_DIR/context/{cli,mcp,lookup,update}.md" + echo " 2. Preserve the plugin's customizations (see context/update.md)" + echo " 3. After integration, re-run this script with --refresh-baseline" + return 2 +} + +check_skill_drift "find-docs" "$UPSTREAM_FIND_DOCS" "$BASELINE_FIND_DOCS" +FIND_DOCS_RC=$? + +echo "" +check_skill_drift "context7-cli" "$UPSTREAM_CLI_SKILL" "$BASELINE_CLI_SKILL" +CLI_SKILL_RC=$? + +if [[ "$MODE" == "--refresh-baseline" ]] && [[ $FIND_DOCS_RC == 0 ]] && [[ $CLI_SKILL_RC == 0 ]]; then + TODAY=$(date -u +%Y-%m-%d) + sed -i.bak -E "s/^( *synced: ).*/\1$TODAY/" "$SKILL_MD" && rm -f "$SKILL_MD.bak" + echo " ✓ Stamped synced: $TODAY in SKILL.md frontmatter" +fi + +echo "" +echo "=== Summary ===" +EXIT_CODE=0 +if [[ "${CLI_DRIFT:-0}" == "0" ]] && [[ $FIND_DOCS_RC == 0 ]] && [[ $CLI_SKILL_RC == 0 ]]; then + echo "✓ No drift detected. Context7 is in sync with upstream." +else + echo "↳ Drift or unverifiable state present. See sections above." + case "${CLI_DRIFT:-0}" in + 1) echo " - CLI version behind" ;; + 2) + echo " - CLI state unverifiable (npm registry unreachable)" + EXIT_CODE=2 + ;; + *) ;; # 0 = no CLI drift; non-CLI drift handled below + esac + if [[ $FIND_DOCS_RC == 1 ]]; then + echo " - find-docs upstream fetch/write failed (state unverifiable)" + EXIT_CODE=2 + elif [[ $FIND_DOCS_RC == 2 ]]; then + echo " - find-docs SKILL.md changed upstream (or baseline missing)" + fi + if [[ $CLI_SKILL_RC == 1 ]]; then + echo " - context7-cli upstream fetch/write failed (state unverifiable)" + EXIT_CODE=2 + elif [[ $CLI_SKILL_RC == 2 ]]; then + echo " - context7-cli SKILL.md changed upstream (or baseline missing)" + fi + if [[ "$MODE" == "report" ]]; then + echo "" + echo "Next: review diffs, port relevant changes, then --refresh-baseline." + fi +fi + +exit $EXIT_CODE diff --git a/plugins/context7/skills/context7/vendor/.markdownlint-cli2.jsonc b/plugins/context7/skills/context7/vendor/.markdownlint-cli2.jsonc new file mode 100644 index 0000000000..3dd9cc5326 --- /dev/null +++ b/plugins/context7/skills/context7/vendor/.markdownlint-cli2.jsonc @@ -0,0 +1,5 @@ +{ + "config": { + "default": false + } +} diff --git a/plugins/context7/skills/context7/vendor/cli/SKILL.md b/plugins/context7/skills/context7/vendor/cli/SKILL.md new file mode 100644 index 0000000000..531aa8af9a --- /dev/null +++ b/plugins/context7/skills/context7/vendor/cli/SKILL.md @@ -0,0 +1,72 @@ +--- +name: context7-cli +description: Use the ctx7 CLI to fetch library documentation, manage AI coding skills, and configure Context7 MCP. Activate when the user mentions "ctx7" or "context7", needs current docs for any library, wants to install/search/generate skills, or needs to set up Context7 for their AI coding agent. +--- + +# ctx7 CLI + +The Context7 CLI does three things: fetches up-to-date library documentation, manages AI coding skills, and sets up Context7 MCP for your editor. + +Make sure the CLI is up to date before running commands: + +```bash +npm install -g ctx7@latest +``` + +Or run directly without installing: + +```bash +npx ctx7@latest +``` + +## What this skill covers + +- **[Documentation](references/docs.md)** — Fetch current docs for any library. Use when writing code, verifying API signatures, or when training data may be outdated. +- **[Skills management](references/skills.md)** — Install, search, suggest, list, remove, and generate AI coding skills. +- **[Setup](references/setup.md)** — Configure Context7 MCP for Claude Code / Cursor / OpenCode. + +## Quick Reference + +```bash +# Documentation +ctx7 library # Step 1: resolve library ID +ctx7 docs # Step 2: fetch docs + +# Skills +ctx7 skills install /owner/repo # Install from a repo (interactive) +ctx7 skills install /owner/repo name # Install a specific skill +ctx7 skills search # Search the registry +ctx7 skills suggest # Auto-suggest based on project deps +ctx7 skills list # List installed skills +ctx7 skills remove # Uninstall a skill +ctx7 skills generate # Generate a custom skill with AI (requires login) + +# Setup +ctx7 setup # Configure Context7 MCP (interactive) +ctx7 login # Log in for higher rate limits + skill generation +ctx7 whoami # Check current login status +``` + +## Authentication + +```bash +ctx7 login # Opens browser for OAuth +ctx7 login --no-browser # Prints URL instead of opening browser +ctx7 logout # Clear stored tokens +ctx7 whoami # Show current login status (name + email) +``` + +Most commands work without login. Exceptions: `skills generate` always requires it; `ctx7 setup` requires it unless `--api-key` or `--oauth` is passed. Login also unlocks higher rate limits on docs commands. + +Set an API key via environment variable to skip interactive login entirely: + +```bash +export CONTEXT7_API_KEY=your_key +``` + +## Common Mistakes + +- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react` +- Always run `ctx7 library` first — `ctx7 docs react "hooks"` will fail without a valid ID +- Repository format for skills is `/owner/repo` — e.g., `ctx7 skills install /anthropics/skills` +- `skills generate` requires login — run `ctx7 login` first diff --git a/plugins/context7/skills/context7/vendor/find-docs/SKILL.md b/plugins/context7/skills/context7/vendor/find-docs/SKILL.md new file mode 100644 index 0000000000..99e5c6e143 --- /dev/null +++ b/plugins/context7/skills/context7/vendor/find-docs/SKILL.md @@ -0,0 +1,154 @@ +--- +name: find-docs +description: >- + Retrieves up-to-date documentation, API references, and code examples for any + developer technology. Use this skill whenever the user asks about a specific + library, framework, SDK, CLI tool, or cloud service -- even for well-known ones + like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. Your + training data may not reflect recent API changes or version updates. + + Always use for: API syntax questions, configuration options, version migration + issues, "how do I" questions mentioning a library name, debugging that involves + library-specific behavior, setup instructions, and CLI tool usage. + + Use even when you think you know the answer -- do not rely on training data + for API details, signatures, or configuration options as they are frequently + outdated. Always verify against current docs. Prefer this over web search for + library documentation and API details. +--- + +# Documentation Lookup + +Retrieve current documentation and code examples for any library using the Context7 CLI. + +Make sure the CLI is up to date before running commands: + +```bash +npm install -g ctx7@latest +``` + +Or run directly without installing: + +```bash +npx ctx7@latest +``` + +## Workflow + +Two-step process: resolve the library name to an ID, then query docs with that ID. + +```bash +# Step 1: Resolve library ID +ctx7 library + +# Step 2: Query documentation +ctx7 docs +``` + +You MUST call `ctx7 library` first to obtain a valid library ID UNLESS the user explicitly provides a library ID in the format `/org/project` or `/org/project/version`. + +IMPORTANT: Do not run these commands more than 3 times per question. If you cannot find what you need after 3 attempts, use the best result you have. + +## Step 1: Resolve a Library + +Resolves a package/product name to a Context7-compatible library ID and returns matching libraries. + +```bash +ctx7 library react "How to clean up useEffect with async operations" +ctx7 library nextjs "How to set up app router with middleware" +ctx7 library prisma "How to define one-to-many relations with cascade delete" +``` + +Always pass a `query` argument — it is required and directly affects result ranking. Use the user's intent to form the query, which helps disambiguate when multiple libraries share a similar name. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query. + +### Result fields + +Each result includes: + +- **Library ID** — Context7-compatible identifier (format: `/org/project`) +- **Name** — Library or package name +- **Description** — Short summary +- **Code Snippets** — Number of available code examples +- **Source Reputation** — Authority indicator (High, Medium, Low, or Unknown) +- **Benchmark Score** — Quality indicator (100 is the highest score) +- **Versions** — List of versions if available. Use one of those versions if the user provides a version in their query. The format is `/org/project/version`. + +### Selection process + +1. Analyze the query to understand what library/package the user is looking for +2. Select the most relevant match based on: + - Name similarity to the query (exact matches prioritized) + - Description relevance to the query's intent + - Documentation coverage (prioritize libraries with higher Code Snippet counts) + - Source reputation (consider libraries with High or Medium reputation more authoritative) + - Benchmark score (higher is better, 100 is the maximum) +3. If multiple good matches exist, acknowledge this but proceed with the most relevant one +4. If no good matches exist, clearly state this and suggest query refinements +5. For ambiguous queries, request clarification before proceeding with a best-guess match + +### Version-specific IDs + +If the user mentions a specific version, use a version-specific library ID: + +```bash +# General (latest indexed) +ctx7 docs /vercel/next.js "How to set up app router" + +# Version-specific +ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router" +``` + +The available versions are listed in the `ctx7 library` output. Use the closest match to what the user specified. + +## Step 2: Query Documentation + +Retrieves up-to-date documentation and code examples for the resolved library. + +```bash +ctx7 docs /facebook/react "How to clean up useEffect with async operations" +ctx7 docs /vercel/next.js "How to add authentication middleware to app router" +ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete" +``` + +### Writing good queries + +The query directly affects the quality of results. Be specific and include relevant details. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query. + +| Quality | Example | +|---------|---------| +| Good | `"How to set up authentication with JWT in Express.js"` | +| Good | `"React useEffect cleanup function with async operations"` | +| Bad | `"auth"` | +| Bad | `"hooks"` | + +Use the user's full question as the query when possible, vague one-word queries return generic results. + +The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context). + +## Authentication + +Works without authentication. For higher rate limits: + +```bash +# Option A: environment variable +export CONTEXT7_API_KEY=your_key + +# Option B: OAuth login +ctx7 login +``` + +## Error Handling + +If a command fails with a quota error ("Monthly quota reached" or "quota exceeded"): +1. Inform the user their Context7 quota is exhausted +2. Suggest they authenticate for higher limits: `ctx7 login` +3. If they cannot or choose not to authenticate, answer from training knowledge and clearly note it may be outdated + +Do not silently fall back to training data — always tell the user why Context7 was not used. + +## Common Mistakes + +- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react` +- Always run `ctx7 library` first — `ctx7 docs react "hooks"` will fail without a valid ID +- Use descriptive queries, not single words — `"React useEffect cleanup function"` not `"hooks"` +- Do not include sensitive information (API keys, passwords, credentials) in queries