Doramagic Project Pack · Human Manual
context7
MCP server for Context7
Context7 Platform Overview and Architecture
Related topics: MCP Server and Core Documentation Tools, ctx7 CLI, Agent Setup, and Skills System
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: MCP Server and Core Documentation Tools, ctx7 CLI, Agent Setup, and Skills System
Context7 Platform Overview and Architecture
1. Purpose and Scope
Context7 is an open-source platform developed by Upstash that delivers up-to-date, version-specific documentation and code examples to AI coding agents and LLM-powered applications. The project addresses a well-known failure mode of LLM-based coding assistants: training data becomes stale, APIs evolve, and assistants hallucinate interfaces that no longer exist.
"Context7 provides up-to-date documentation and code examples for libraries and frameworks." — packages/mcp/src/index.ts
The repository is a pnpm monorepo that ships Context7 in several consumption modes so the same documentation engine can be reached from MCP-aware agents, AI SDK workflows, terminal sessions, vendor-specific coding assistants, and the pi coding agent.
1.1 The Problem Context7 Solves
| Problem | How Context7 Responds |
|---|---|
| Year-old training data in LLMs | Fresh, source-driven docs fetched at request time |
| Hallucinated APIs | Snippets keyed to a real libraryId (e.g. /vercel/next.js) |
| Generic answers for old versions | Versioned library IDs and slash-command hints (e.g. use library /vercel/next.js/v14.2.0) |
| Repetitive boilerplate explanations | Pre-aggregated, topic-ranked documentation snippets |
Source: README.md, packages/sdk/README.md
1.2 High-Level Capabilities
Context7 exposes two primary tool surfaces across all integration paths:
resolve-library-id— maps a free-form library name to a Context7-compatible ID.query-docs— fetches ranked documentation for a resolved ID.
Source: README.md, plugins/claude/context7/README.md
Source: https://github.com/upstash/context7 / Human Manual
MCP Server and Core Documentation Tools
Related topics: Context7 Platform Overview and Architecture, SDKs, Extensions, and Plugin Ecosystem
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Context7 Platform Overview and Architecture, SDKs, Extensions, and Plugin Ecosystem
MCP Server and Core Documentation Tools
Overview
Context7's MCP (Model Context Protocol) Server is the central client-facing component of the platform. It exposes two LLM-callable tools — resolve-library-id and query-docs — that allow AI coding assistants to look up up-to-date documentation for any library, framework, SDK, or CLI tool. The same tool surface is also delivered through companion packages: a Vercel AI SDK adapter (@upstash/context7-tools-ai-sdk), a CLI (ctx7), a pi coding-agent extension (@upstash/context7-pi), and a Cursor plugin.
The MCP server itself is intentionally thin. It does not crawl, parse, or store documentation in this repository. The supporting components — the API backend, the parsing engine, and the crawling engine — are private and not part of this open-source repository. Source: README.md
"This repository hosts the MCP server's source code. The supporting components — API backend, parsing engine, and crawling engine — are private and not part of this repository." — README.md
This separation is important context for several of the most-upvoted community issues: requests for self-hosting the documentation backend (#59), offline / air-gapped operation (#320), and private document indexes (#34) all intersect with the boundary between the open MCP server and the private backend.
High-Level Architecture
graph TD
A[AI Coding Agent<br/>Cursor, Claude Code, Codex, etc.] -->|MCP protocol| B[Context7 MCP Server<br/>@upstash/context7-mcp]
A -.->|slash command| C[ctx7 CLI]
A -.->|AI SDK tool calls| D[tools-ai-sdk]
A -.->|pi extension| E[context7-pi]
B -->|HTTPS / API key| F[(Context7 API<br/>context7.com/api)]
C -->|HTTPS / API key| F
D -->|HTTPS / API key| F
E -->|HTTPS / API key| F
F --> G[(Private: Crawler)]
F --> H[(Private: Parser)]
F --> I[(Private: Indexed Docs)]
B -.stdio or http transport.-> A
C -.reads/writes MCP config.-> J[Agent config files<br/>~/.claude, .cursor, etc.]
D -.uses CONTEXT7_API_KEY.-> AThe MCP server is the canonical implementation; the CLI, AI SDK tools, and pi extension are delivery mechanisms that ultimately call the same private API. Source: packages/mcp/package.json
The Two Core Tools
The MCP server exposes two tools, both of which are mirrored in the AI SDK, CLI, and pi extension packages. Their descriptions are intentionally kept identical so that the LLM receives the same instructions regardless of the client. Source: packages/pi/lib/prompts.ts
"Tool titles, descriptions, and parameter descriptions are copied verbatim from @upstash/context7-mcp (packages/mcp/src/index.ts) so pi and MCP clients give the LLM identical instructions. Update both together when tweaking guidance." — packages/pi/lib/prompts.ts
`resolve-library-id`
Resolves a human-friendly package or product name into a Context7-compatible library ID. It must be called before query-docs unless the user already supplied a library ID in /org/project (or /org/project/version) form.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | yes | The user's question or task. Used to rank results by relevance. |
libraryName | string | yes | The name of the library to search for. Use the official name with proper punctuation (e.g., "Next.js"). |
The tool returns a list of matching libraries, each annotated with:
- Library ID in
/org/projectform. - Name and Description.
- Code Snippets count — higher is better.
- Source Reputation —
High,Medium,Low, orUnknown. - Benchmark Score — up to 100.
- Versions — if available; use one of these if the user specified a version.
The selection process the LLM is instructed to follow is:
- Analyze the query to understand the library/package the user wants.
- Pick the most relevant match based on name similarity, description relevance, snippet coverage, source reputation, and benchmark score. Source: packages/pi/lib/prompts.ts
`query-docs`
Fetches documentation and code examples for a resolved library ID. Source: packages/tools-ai-sdk/src/tools/query-docs.ts
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId | string | yes | Exact Context7-compatible library ID (e.g., /mongodb/docs, /vercel/next.js). |
query | string | yes | The user's full question — not a single word. |
Internally the AI SDK tool constructs a Context7 client using the supplied apiKey (or the CONTEXT7_API_KEY environment variable if none is given):
export function queryDocs(config: Context7ToolsConfig = {}) {
const { apiKey } = config;
const getClient = () => new Context7({ apiKey });
// ...
}
Source: packages/tools-ai-sdk/src/tools/query-docs.ts
Recommended Two-Step Workflow
The Context7 system prompt defines an explicit four-step workflow for the LLM:
graph TD
S1[Step 1: resolveLibraryId with library name] --> S2[Step 2: Analyze results]
S2 --> S3{Is there a version?}
S3 -- yes --> V[Use /org/project/version]
S3 -- no --> I[Use /org/project]
V --> S4[Step 3: queryDocs]
I --> S4
S4 --> S5[Step 4: Answer with code examples<br/>and cite the library ID]Source: packages/tools-ai-sdk/src/prompts/system.ts
Transport: stdio vs HTTP
The MCP server can be reached over either transport. The transport is selected at setup time by the CLI. Source: packages/cli/src/commands/setup.ts
function resolveTransport(options: SetupOptions): Transport {
return options.stdio ? "stdio" : "http";
}
The default is HTTP, which the Cursor deeplink install also uses. Source: README.md
https://mcp.context7.com/mcp
When the Antigravity agent is targeted, the HTTP transport is configured with an httpUrl key (the Gemini convention) rather than a generic serverUrl:
buildEntry: (auth, transport) =>
transport === "stdio" ? stdioEntry(auth) : withHeaders({ httpUrl: mcpUrl(auth) }, auth),
Source: packages/cli/src/setup/agents.ts
Setup via the `ctx7 setup` Command
ctx7 setup is the recommended one-shot installer. It writes the MCP config, drops a rule file, and installs a skill for the selected agent(s). Source: packages/cli/CHANGELOG.md
Supported Agents and Their Config Layouts
| Agent | MCP config file | Rule file | Skill directory |
|---|---|---|---|
claude | ~/.claude.json / .mcp.json | CLAUDE.md | .claude/skills |
cursor | ~/.cursor/mcp.json / .cursor/mcp.json | Cursor Rules | .cursor/skills |
codex | ~/.codex/config.toml | AGENTS.md | .codex/skills |
opencode | opencode.json | AGENTS.md | .opencode/skill |
gemini | ~/.gemini/settings.json | GEMINI.md | — |
antigravity | ~/.gemini/config/mcp_config.json | ~/.gemini/GEMINI.md / GEMINI.md | .agent/skills |
Source: packages/cli/src/setup/agents.ts
`setup` Command Flags
| Flag | Effect |
|---|---|
--claude | Configure for Claude Code |
--cursor | Configure for Cursor |
--codex | Configure for Codex CLI |
--opencode | Configure for opencode |
--gemini | Configure for Gemini CLI |
--antigravity | Configure for Antigravity 2.0 (added in [email protected]) |
--project | Write config to the project (vs. the user's home directory) |
--stdio | Use stdio transport instead of HTTP |
--mcp | Setup mode: install only the MCP config |
--cli | Setup mode: install only the CLI |
--api-key <k> | Use a specific API key |
--oauth | Authenticate via OAuth |
--yes | Non-interactive: accept all defaults |
Source: packages/cli/src/commands/setup.ts and packages/cli/CHANGELOG.md
The latest release ([email protected]) extends this with first-class Antigravity 2.0 support:
"ctx7 setupnow properly supports--antigravity, installing skills to.agent/skills, aGEMINI.mdrule section (Antigravity reads Gemini-family config), and MCP config to Antigravity 2.0's documented global path~/.gemini/config/mcp_config.json(withhttpUrlfor HTTP, matching the Gemini convention). Antigravity has no documented project-level MCP file." — packages/cli/CHANGELOG.md
The Default Rule Text
When a project has no prior context7 rule, ctx7 setup writes a rule that tells the agent to reach for resolve-library-id → query-docs automatically. The fallback rule looks like this (truncated for length):
Use Context7 MCP to fetch current documentation whenever the user asks about a
library, framework, SDK, API, CLI tool, or cloud service -- even well-known
ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot.
Steps
1. resolve-library-id with the library name and the user's question
2. Pick the best match by exact name, description, snippet count, source
reputation, and benchmark score
3. query-docs with the selected library ID and the user's full question
4. Answer using the fetched docs
Source: packages/cli/src/setup/templates.ts
Authentication
The MCP server and the AI SDK tools both read the CONTEXT7_API_KEY environment variable when no explicit key is provided. Source: packages/tools-ai-sdk/src/tools/query-docs.ts
export CONTEXT7_API_KEY=ctx7sk_...
Without a key, requests are served at IP-based rate limits, which is useful for trying the service out. The pi extension README makes this explicit:
"The extension works without any setup at IP-based rate limits — useful for trying it out. For higher quotas, generate a free key at context7.com/dashboard." — packages/pi/README.md
The CLI additionally supports an OAuth flow that fires automatically when authentication is required (for example, for ctx7 skills generate):
"Auto-login via OAuth when the generate command requires authentication instead of showing an error." — packages/cli/CHANGELOG.md
Versioning
Library versions are part of the library ID format: /org/project for the default version, or /org/project/version to pin a specific release. The resolve-library-id response includes a versions array; the AI is instructed to pick from it when the user mentions a version. Source: packages/pi/lib/prompts.ts
"Versions: List of versions if available. Use one of those versions if the user provides a version in your query. The format of the version is /org/project/version." — packages/pi/lib/prompts.ts
This addresses the long-standing community request in #45 for explicit documentation versioning — though version pinning is supported by the data model, the granularity depends on what the crawler has ingested for a given library.
The Cursor plugin README documents the same pattern:
"To get documentation for a specific version, include the version in the library…" — plugins/cursor/context7/README.md
Research Mode
A "research" mode exposes deep, agent-driven documentation answers. It is reachable through both surfaces:
| Surface | How to invoke research mode |
|---|---|
| MCP tool | Call the researchMode MCP tool |
| CLI | ctx7 docs --research <libraryId> <query> |
Source: packages/cli/CHANGELOG.md
"Expose research mode through the MCPresearchModetool and the CLIdocs --researchflag for deep, agent-driven documentation answers." — packages/cli/CHANGELOG.md
CLI Surface
The ctx7 CLI mirrors the MCP tool surface in a shell-friendly form. Source: README.md
| Command | Description | ||
|---|---|---|---|
ctx7 library <name> <query> | Searches the Context7 index by library name and returns matching libraries with their IDs. | ||
ctx7 docs <libraryId> <query> | Retrieves documentation for a library using a Context7-compatible library ID. | ||
ctx7 docs <libraryId> <query> --research | Use research mode for deeper, agent-driven answers. | ||
| `ctx7 setup [--claude\ | --cursor\ | ...]` | One-shot installer for a coding agent. |
ctx7 remove | Cleanup counterpart to ctx7 setup; preserves non-Context7 MCP entries. | ||
ctx7 upgrade | Check for a newer CLI version with safer guidance across npm/pnpm/bun. | ||
ctx7 skills suggest | Scan package.json, requirements.txt, pyproject.toml and recommend skills. | ||
ctx7 skills install [--all-agents --yes] | Install a skill across all detected agents non-interactively. | ||
ctx7 skills generate | AI-generate a new skill (requires auth, may trigger OAuth). |
Sources: README.md, packages/cli/CHANGELOG.md
AI SDK Adapter (`@upstash/context7-tools-ai-sdk`)
For Vercel AI SDK users, the same two tools are exposed as resolveLibrary and getLibraryDocs, plus a pre-wired Context7Agent that performs the multi-step workflow. Source: packages/tools-ai-sdk/README.md
import { Context7Agent } from "@upstash/context7-tools-ai-sdk";
import { anthropic } from "@ai-sdk/anthropic";
const agent = new Context7Agent({
model: anthropic("claude-sonnet-4-20250514"),
});
const { text } = await agent.generate({
prompt: "How do I set up routing in Next.js?",
});
The package's public surface is the union of tools, the agent, and a re-export of the relevant prompts and SDK types. Source: packages/tools-ai-sdk/src/index.ts
export { Context7Agent, type Context7AgentConfig } from "@agents";
export { resolveLibraryId, queryDocs, type Context7ToolsConfig } from "@tools";
export {
SYSTEM_PROMPT,
AGENT_PROMPT,
RESOLVE_LIBRARY_ID_DESCRIPTION,
QUERY_DOCS_DESCRIPTION,
} from "@prompts";
pi Extension (`@upstash/context7-pi`)
The pi extension mirrors the MCP surface in a form suited to the pi coding agent. It adds:
- The two tools (
resolve-library-id,query-docs). - A
context7-docsskill that triggers them automatically. - A
/c7-docs <library> <question>slash command that runs the resolve + query flow in one shot.
Install:
pi install npm:@upstash/context7-pi
Source: packages/pi/README.md
Cursor Plugin
The Cursor plugin bundles the MCP server, an always-on use-context7 rule, a context7-docs-lookup skill, and a dedicated docs-researcher agent. Source: plugins/cursor/context7/README.md
graph TD
C[Cursor] --> P[context7 plugin]
P --> M[MCP Server]
P --> R[use-context7 rule]
P --> S[context7-docs-lookup skill]
P --> A[docs-researcher agent]
M -->|resolve-library-id| API[Context7 API]
M -->|query-docs| APIConfiguration Reference
| Environment variable | Used by | Purpose |
|---|---|---|
CONTEXT7_API_KEY | MCP server, AI SDK, pi, CLI | Authenticated requests, raises quota above IP-based limits. |
CTX7_TELEMETRY_DISABLED | CLI | Disable fire-and-forget usage events posted to /api/v2/cli/events. |
EDITOR | CLI | Editor opened by the "View skill" action in skills generate. |
Source: packages/cli/CHANGELOG.md, packages/tools-ai-sdk/src/tools/query-docs.ts
Common Failure Modes and Community Notes
Network / API Downtime
Because all client surfaces (MCP server, CLI, AI SDK, pi) ultimately call the hosted Context7 API, the system is sensitive to outages at context7.com. This is the central concern behind issue #59, which requests the ability to self-host the documentation backend. As of the current codebase, the open repository does not include the backend, so self-hosting the documentation service is not possible from this repo alone. Source: README.md
Air-Gapped / Offline Use
Issue #320 asks for offline documentation. The MCP client itself is a thin client and cannot retrieve anything without a reachable API. There is no offline cache in the open repository. Source: README.md
Private Documents
Issue #34 asks for private document indexes tied to user accounts. Authentication via CONTEXT7_API_KEY exists, and the CLI supports OAuth-based login, but private document storage lives in the private backend and is not exposed by the open MCP server. Source: packages/tools-ai-sdk/src/tools/query-docs.ts, packages/cli/CHANGELOG.md
Generic "getting error" Reports
Issue #19 is the most-commented community thread and consists almost entirely of user-submitted error screenshots. The most common remedies, derived from the code rather than the issue thread:
- Re-run
ctx7 setupso the agent's MCP config is regenerated and the rule/skill are installed. - Export
CONTEXT7_API_KEYin the shell that launches the agent. - For Codex in particular, the rule and skill now tell the agent to retry Context7 CLI requests outside the default sandbox after DNS or network failures. Source: packages/cli/CHANGELOG.md
- For Windows users, the
skills installpath validation bug that rejected valid files inside the target directory was fixed in[email protected]. Source: packages/cli/CHANGELOG.md
Version Pinning Caveats
Version IDs in the form /org/project/version are accepted by the API, but only versions that the crawler has ingested will resolve. Users pinning to very old or pre-release tags (the example in #45 was v13.5.11 of vercel/next.js) may receive empty results if those tags have not been indexed. Source: packages/pi/lib/prompts.ts
How the Pieces Fit Together
graph TD
subgraph Open Source
MCP[packages/mcp<br/>@upstash/context7-mcp]
SDK[packages/tools-ai-sdk]
CLI[packages/cli / ctx7]
PI[packages/pi]
CUR[plugins/cursor]
MCP -.shared prompts.-> SDK
MCP -.shared prompts.-> PI
CLI -.configures.-> MCP
CLI -.configures.-> SDK
CLI -.configures.-> PI
CUR -.bundles.-> MCP
end
subgraph Private
API[Context7 API]
CR[Crawler]
PR[Parser]
IDX[Indexed Docs]
end
MCP -->|HTTPS| API
SDK -->|HTTPS| API
CLI -->|HTTPS| API
PI -->|HTTPS| API
API --- CR
API --- PR
API --- IDXSource: README.md, packages/mcp/package.json
See Also
- Context7 Platform README
@upstash/context7-mcppackage configuration- AI SDK tools — queryDocs implementation
- AI SDK system prompts
- AI SDK package entry point
- CLI setup templates (fallback rules)
- CLI agent registry (Claude, Cursor, Codex, Antigravity, …)
ctx7 setupcommand- MCP config writer (TOML / JSON)
- CLI changelog (Antigravity 2.0, research mode, Windows fix)
- pi extension README
- pi extension shared prompts
- Cursor plugin README
Sources: README.md, packages/cli/CHANGELOG.md
ctx7 CLI, Agent Setup, and Skills System
Related topics: Context7 Platform Overview and Architecture, SDKs, Extensions, and Plugin Ecosystem
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Context7 Platform Overview and Architecture, SDKs, Extensions, and Plugin Ecosystem
ctx7 CLI, Agent Setup, and Skills System
The ctx7 CLI is the user-facing entry point for the Context7 documentation service. It bundles three concerns into a single Node.js binary: a client for resolving libraries and fetching their docs, an agent installer that wires Context7 into popular AI coding assistants, and a skills lifecycle manager for installing, searching, and generating reusable agent skills. As of the latest release ([email protected]), the CLI is published as a single ESM binary named ctx7 from the packages/cli workspace Source: [packages/cli/package.json:1-15].
graph TD
A[User Terminal] -->|npx ctx7| B[ctx7 CLI]
B --> C[docs / library commands]
B --> D[setup / remove commands]
B --> E[skills commands]
B --> F[auth commands]
B --> G[upgrade command]
C --> H[Context7 API<br/>context7.com/api]
D --> I[Agent Config Files<br/>.cursor/mcp.json, ~/.claude/...]
E --> J[Local Skills Directory<br/>~/.agents/skills]
F --> K[OAuth + API Key]
H --> L[Upstash / Search Index]High-Level Role in the Repository
The Context7 monorepo contains three primary client surfaces that all delegate to the same hosted API:
| Package | Role | Source |
|---|---|---|
packages/mcp | Model Context Protocol server for editors that speak MCP | packages/mcp/package.json:1-15 |
packages/tools-ai-sdk | Vercel AI SDK tools (resolveLibraryId, queryDocs) and a Context7Agent | packages/tools-ai-sdk/src/index.ts:1-15 |
packages/cli (ctx7) | Human-facing CLI for library lookups, agent setup, and skill management | packages/cli/README.md:1-10 |
The CLI is intentionally the lowest-friction way to onboard: it requires no code changes, no editor plugin installation, and no SDK integration. A single npx ctx7 setup command provisions a working MCP-backed documentation assistant in any supported agent Source: [packages/cli/README.md:7-22].
Command Surface
The CLI exposes several command groups. The following table summarizes each command, its purpose, and the most common invocation form. All descriptions are grounded in either the CLI README or the CHANGELOG.
| Command | Purpose | Key Flags / Notes |
|---|---|---|
ctx7 setup | Configure MCP + rules + skills for one or more AI agents | --cursor, --claude, --opencode, --antigravity, --all-agents, --yes |
ctx7 remove | Undo a setup, removing only Context7-owned artifacts | Prompts only for agents that actually contain Context7 entries |
ctx7 upgrade | Update the CLI binary via the user's package manager (npm/pnpm/bun) | Caches a "newer version available" check; non-blocking notice |
ctx7 docs <libraryId> <query> | Fetch documentation for a specific library | --json, --research (deep agent-driven research) |
ctx7 library <name> | Resolve a human name to a Context7 library ID | --json |
ctx7 skills install | Install one or more skills into detected agent directories | --all-agents, --yes |
ctx7 skills search | Browse the skill hub with install counts and trust scores | Columns: Installs, Trust (0–10) |
ctx7 skills list | List skills already present in detected directories | No prompt (per 0.2.0 simplification) |
ctx7 skills suggest | Scan package.json, requirements.txt, pyproject.toml and recommend skills | Based on project dependencies |
ctx7 skills generate | AI-powered generation of a new skill (OAuth-gated) | Includes a feedback loop and a weekly quota |
ctx7 login / logout | OAuth 2.0 authentication | Stores a refreshable token |
ctx7 whoami | Display identity, teamspace, and active teamspace name | Uses the internal API endpoint |
These commands are documented in the CLI's user-facing README Source: [packages/cli/README.md:1-70] and their evolution is tracked in the CHANGELOG Source: [packages/cli/CHANGELOG.md:1-110].
Agent Setup Workflow
What `ctx7 setup` Does
ctx7 setup is the canonical onboarding flow. It performs three logical steps:
- Authenticate via OAuth 2.0 and persist a refreshable token plus an API key Source: [packages/cli/CHANGELOG.md:78-92].
- Write an MCP server entry to the agent's config file, using the agent-specific key (
mcpServers,mcp_config.json, etc.). - Install a rule and a skill so the agent knows when to invoke Context7 automatically.
The --antigravity flag (added in 0.4.5) installs the skill to .agent/skills, appends a GEMINI.md rule section (Antigravity reads Gemini-family config), and writes the MCP config to ~/.gemini/config/mcp_config.json using httpUrl for HTTP transport Source: [packages/cli/CHANGELOG.md:1-10].
Supported Agents
graph LR
Setup[ctx7 setup] --> Claude[--claude<br/>Claude Code]
Setup --> Cursor[--cursor<br/>Cursor]
Setup --> OpenCode[--opencode<br/>OpenCode / AGENTS.md]
Setup --> Antigravity[--antigravity<br/>Antigravity 2.0]
Setup --> Codex[Codex<br/>AGENTS.md append]
Setup --> All[--all-agents]- Claude Code — installs the
context7plugin via the Claude marketplace; ships adocs-researcheragent, a/context7:docscommand, and afind-docsskill Source: [plugins/claude/context7/README.md:1-30]. - Cursor — writes
mcp.json, an always-onuse-context7rule (withalwaysApply: true), and acontext7-docs-lookupskill Source: [plugins/cursor/context7/README.md:1-22]. - OpenCode / Codex — write to
AGENTS.md(OpenCode was migrated from.opencode/rules/in0.3.10) Source: [packages/cli/CHANGELOG.md:38-45]. - Antigravity — global config at
~/.gemini/config/mcp_config.json, project-level rule inGEMINI.md, skill in.agent/skillsSource: [packages/cli/CHANGELOG.md:1-10].
Version Pinning
The Cursor plugin documentation explicitly notes that a specific version can be requested by including the version in the library name (e.g., Next.js 13), so that the resolver returns a tag-pinned library ID Source: [plugins/cursor/context7/README.md:25-30]. This addresses the community interest in documentation versioning (see issue #45).
Path Resolution and Security
The setup flow writes configuration into well-known directories. Several CHANGELOG entries show hardening around path resolution:
0.3.7: removedshell: truefrom thespawncall in thegeneratecommand to prevent command injection via theEDITORenvironment variable Source: [packages/cli/CHANGELOG.md:55-58].0.3.7: prevented directory traversal in skill file installation by validating that resolved paths stay within the target directory Source: [packages/cli/CHANGELOG.md:59-61].0.3.13: fixed skill installation path validation on Windows so that valid files inside the target directory are not rejected due to backslash-separated resolved paths Source: [packages/cli/CHANGELOG.md:22-25].
The find-docs skill is the canonical trigger: the CHANGELOG notes its description was rewritten in 0.3.10 to push invocation rates from 66% to 98% Source: [packages/cli/CHANGELOG.md:38-45].
Skills System
What a Skill Is in Context7
A skill is a bundle of files (typically a SKILL.md plus optional auxiliary assets) that teaches an AI agent *when and how* to use Context7's MCP tools. Skills are agent-agnostic in their on-disk representation but installed into agent-specific directories by the CLI Source: [packages/cli/src/types.ts:1-15].
The internal type model distinguishes between hub skills (downloadable from the Context7 skill hub) and setup skills (the locally generated find-docs skill that is bundled with the CLI). This split is reflected in the TODO(deprecate-skills-phase-2) comment in the types file, which marks the legacy Skill, SkillSearchResult, LibrarySearchResult, and related response types for removal Source: [packages/cli/src/types.ts:1-80].
Skill Metadata
Hub skills expose a small set of metadata fields used for ranking and trust signaling:
| Field | Type | Description |
|---|---|---|
name | string | Display name shown in prompts and search results |
description | string | One-line description used for the skill's invocation trigger |
url | string | Canonical URL on context7.com |
installCount | number | Cumulative install counter, shown as ↓100+ style buckets Source: [packages/cli/CHANGELOG.md:95-100] |
trustScore | number | 0–10 score surfaced in the Trust(0–10) column of search results Source: [packages/cli/CHANGELOG.md:108-112] |
A skill is "blocked" if prompt-injection heuristics flag its description; the blockedSkillsCount field on ListSkillsResponse is the public surface for that signal Source: [packages/cli/src/types.ts:30-35].
Skill Lifecycle Commands
graph TD
A[skills suggest] -->|scan deps| B[Recommended skills]
B --> C[skills search]
C -->|pick one| D[skills install]
D -->|write to| E[Agent skill dir]
F[skills generate] -->|OAuth required| G[Wizard: questions, then generation]
G --> H[Save to disk / open in $EDITOR]
I[skills list] --> J[Inventory of installed skills]
K[skills remove] --> EEach command maps to a specific user goal:
skills suggestscanspackage.json,requirements.txt, andpyproject.tomlto recommend skills that match the project's actual dependencies Source: [packages/cli/CHANGELOG.md:115-118].skills searchreturns a ranked list with install counts and trust scores; items are presented with numbered rows, hover highlighting, and Enter-to-select Source: [packages/cli/CHANGELOG.md:130-140].skills installsupports--all-agents(write to every detected agent) and--yes(non-interactive) Source: [packages/cli/CHANGELOG.md:18-21].skills generateis the AI wizard: it asks clarifying questions, streams query progress, lets the user give feedback, and enforces a weekly quota. Generation requires OAuth, and0.2.2added auto-login via OAuth when the command is run unauthenticated Source: [packages/cli/CHANGELOG.md:108-115].skills listis now promptless since0.2.0; it shows all detected IDE skill directories Source: [packages/cli/CHANGELOG.md:125-127].
Skill Installation Paths
Universal global skills are installed to ~/.agents/skills (this was changed from ~/.config/agents/skills in 0.3.10) Source: [packages/cli/CHANGELOG.md:46-48]. Per-agent paths are listed in the table above.
Prompt Injection Defense
Since 0.1.4, the CLI runs a prompt-injection detector on downloaded skill content; blocked skills are reported via a warning message rather than being installed silently Source: [packages/cli/CHANGELOG.md:148-150].
Library and Documentation Commands
The two commands that touch the documentation API itself are library and docs.
`ctx7 library`
Resolves a human-readable name to a Context7 library ID. The result includes, for each candidate, the ID, title, description, branch, snippet count, token estimate, star count, trust score, benchmark score, and available versions Source: [packages/cli/src/types.ts:60-72]. A --json flag emits the raw response for piping.
`ctx7 docs`
Fetches documentation for a specific library ID. Output is, by default, a human-readable summary that includes code examples when the underlying snippets contain them. A --json flag exposes the raw payload. Since 0.4.0, a --research flag engages a deep, agent-driven research mode that orchestrates multiple resolution and query calls Source: [packages/cli/CHANGELOG.md:5-10].
The MCP server exposes the same surface as the researchMode tool, so the same flag exists programmatically Source: [packages/cli/CHANGELOG.md:5-10].
Authentication and API Keys
The CLI uses OAuth 2.0 for human authentication. The flow is:
ctx7 loginopens a browser window, performs the OAuth dance, and stores a refreshable token plus an API key.- The API key is written to the agent's MCP config so the editor can authenticate against the Context7 API.
ctx7 whoamireports the identity, teamspace, and active teamspace name; the0.3.6release centralized the auth constants and switchedwhoamito the internal API endpoint Source: [packages/cli/CHANGELOG.md:72-78].
0.3.6 also added token refresh support so long-lived sessions do not silently break Source: [packages/cli/CHANGELOG.md:75-78].
For SDK-based integrations, an API key is also accepted directly. The tools-ai-sdk package documents that an unset key falls back to the CONTEXT7_API_KEY environment variable, with IP-based rate limits as the default for unauthenticated usage Source: [packages/pi/README.md:14-22].
Configuration and Environment
| Variable | Purpose | Source |
|---|---|---|
CONTEXT7_API_KEY | Fallback API key for CLI and SDK calls | packages/pi/README.md:18-22 |
CTX7_TELEMETRY_DISABLED | Suppresses the fire-and-forget telemetry events emitted to /api/v2/cli/events | packages/cli/CHANGELOG.md:102-106 |
EDITOR | Used by skills generate to open the produced skill in the user's editor (no shell: true since 0.3.7) | packages/cli/CHANGELOG.md:55-58 |
The CLI also caches an "update available" state, surfaced as a non-blocking notice before interactive commands, and provides a dedicated ctx7 upgrade path for npm, pnpm, and bun installations Source: [packages/cli/CHANGELOG.md:11-17].
SDK-Level Documentation Flow
The CLI mirrors the multi-step documentation flow that the AI SDK exposes. The Context7Agent class encapsulates the same workflow that an LLM using generateText would produce manually Source: [packages/tools-ai-sdk/src/agents/context7.ts:1-50].
graph TD
Q[User question] --> R[Step 1: resolveLibraryId]
R --> S[Review candidates<br/>trust, benchmark, snippet count]
S --> T[Step 2: queryDocs<br/>libraryId + question]
T --> U[Compose answer<br/>with code examples + citations]
U --> V[Final response]The two underlying tools have explicit input schemas and descriptions:
resolveLibraryId(libraryName)— returns a list of candidate library IDs with the metadata fields described above. The system prompt instructs the agent to prefer official sources, higher snippet counts, and higher benchmark scores Source: [packages/tools-ai-sdk/src/prompts/system.ts:1-30].queryDocs(libraryId, query, { topic?, tokens? })— fetches documentation snippets and code examples. The tool is built with Vercel AI SDK'stool()helper and can be used directly withgenerateText/streamTextSource: [packages/tools-ai-sdk/src/tools/query-docs.ts:1-30].
Context7Agent wires these tools together, defaults stopWhen to stepCountIs(5), and prefixes the system prompt with AGENT_PROMPT so the multi-step workflow is enforced Source: [packages/tools-ai-sdk/src/agents/context7.ts:1-50].
The index module re-exports both tools, the agent, the prompts, and useful SDK types (Context7Config, Library, Documentation, GetContextOptions) so consumers can build their own agent scaffolds Source: [packages/tools-ai-sdk/src/index.ts:1-15].
Telemetry and Lifecycle Hooks
Since 0.2.1, the CLI emits telemetry events (commands, searches, installs, generation feedback) to /api/v2/cli/events on a fire-and-forget basis. Setting CTX7_TELEMETRY_DISABLED=1 disables it. The 0.3.5 release added an install-count event when ctx7 setup provisions a new agent Source: [packages/cli/CHANGELOG.md:80-88].
Common Failure Modes
| Symptom | Likely Cause | Mitigation |
|---|---|---|
ctx7 setup writes a config file the agent ignores | Wrong agent flag (e.g., --cursor for a Claude project) | Re-run with the correct flag or use --all-agents |
skills install rejects a path on Windows | Backslash path normalization (fixed in 0.3.13) | Upgrade CLI to >= 0.3.13 Source: [packages/cli/CHANGELOG.md:22-25] |
skills generate opens a vulnerable editor | EDITOR injection via shell: true (fixed in 0.3.7) | Upgrade CLI to >= 0.3.7 Source: [packages/cli/CHANGELOG.md:55-58] |
| Editor keeps using stale training data | Skill find-docs not installed or alwaysApply: false | Re-run ctx7 setup and verify the rule was written |
| Network or DNS failures inside Codex sandbox | Codex defaults to a sandboxed network | The CLI ships Codex-specific guidance to rerun outside the sandbox Source: [packages/cli/CHANGELOG.md:26-30] |
| High-traffic requests throttled | Unauthenticated IP-based rate limit | Generate a free key at context7.com/dashboard and export CONTEXT7_API_KEY Source: [packages/pi/README.md:16-22] |
Community Context and Known Gaps
The community context surfaces several recurring requests that intersect with the CLI surface area. While none of them are fully addressed in the current source tree, they are worth documenting for wiki readers:
- Self-hosting the documentation backend (issue #59) — every CLI command ultimately calls the central
context7.com/api; there is no documentedCTX7_API_BASEoverride in the retrieved sources. - Offline / air-gapped operation (issue #320) — the CLI's
docsandlibrarycommands require network access to the hosted API; local skill bundles are usable offline but library resolution is not. - Private documents and per-user API keys (issue #34) — the OAuth + teamspace model added in
0.2.0/0.3.6is a step in this direction, but a dedicated "personal docs index" feature is not present in the retrieved sources. - Error reports (issue #19) — the high comment count suggests intermittent setup failures; the hardening entries in
0.3.7,0.3.10,0.3.13, and0.4.5reflect ongoing fixes for these reports. - Documentation versioning (issue #45) — the Cursor plugin already documents version pinning via the library name, but the CLI does not yet expose a first-class
--versionflag in the retrieved sources.
Upgrade Path and Changelog Highlights
| Version | Change | Source |
|---|---|---|
0.4.5 | --antigravity support for ctx7 setup | packages/cli/CHANGELOG.md:1-10 |
0.4.0 | researchMode MCP tool and ctx7 docs --research | packages/cli/CHANGELOG.md:5-10 |
0.3.6 | OAuth refresh, centralized auth, whoami teamspace | packages/cli/CHANGELOG.md:72-78 |
0.3.10 | Universal skills at ~/.agents/skills, OpenCode → AGENTS.md, find-docs description rewrite | packages/cli/CHANGELOG.md:38-45 |
0.3.7 | shell: true removal; directory-traversal fix | packages/cli/CHANGELOG.md:55-61 |
0.3.11 | skills install --all-agents --yes | packages/cli/CHANGELOG.md:18-21 |
0.2.3 | skills suggest dependency scan | packages/cli/CHANGELOG.md:115-118 |
0.2.2 | --json skills search, OAuth auto-login in generate | packages/cli/CHANGELOG.md:108-115 |
0.2.0 | skills generate wizard + OAuth login/logout/whoami | packages/cli/CHANGELOG.md:120-128 |
See Also
- Context7 Main README — overview, install links, and video tutorials.
@upstash/context7-tools-ai-sdkREADME — Vercel AI SDK integration for custom agents.- Cursor plugin README — Cursor-specific MCP and rule setup.
- Claude Code plugin README — Claude Code plugin installation and tools.
- pi extension README —
picoding agent integration. - Community issues referenced: #59 Self-hosting, #320 Offline, #34 Private docs, #19 Errors, #45 Versioning.
Source: https://github.com/upstash/context7 / Human Manual
SDKs, Extensions, and Plugin Ecosystem
Related topics: MCP Server and Core Documentation Tools, ctx7 CLI, Agent Setup, and Skills System
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: MCP Server and Core Documentation Tools, ctx7 CLI, Agent Setup, and Skills System
SDKs, Extensions, and Plugin Ecosystem
Overview
Context7 is distributed as a monorepo containing multiple packages that together form a developer-facing documentation retrieval ecosystem. The ecosystem is designed so that the same Context7 backend (exposed at https://context7.com/api) can be invoked from several different surfaces: a programmatic TypeScript SDK, a Vercel AI SDK tool/agent integration, a Model Context Protocol (MCP) server, a standalone CLI, a pi coding-agent extension, and a Claude Code plugin.
The goal of the SDKs, extensions, and plugin ecosystem is to provide up-to-date, version-specific library documentation and code examples to any AI-assisted coding workflow, while keeping the integration surface small and consistent. Every entry point ultimately calls the same two backend capabilities: resolving a human-readable library name into a Context7 library ID, and querying documentation/code snippets for that library ID (Source: README.md:1-120).
Ecosystem Architecture
The following diagram shows how the various packages in the ecosystem relate to one another and to the central Context7 API.
graph TD
User[Developer / AI Agent]
subgraph "Client Surfaces"
CLI["ctx7 CLI<br/>(packages/cli)"]
MCP["context7-mcp<br/>(packages/mcp)"]
AISDK["@upstash/context7-tools-ai-sdk<br/>(packages/tools-ai-sdk)"]
Pi["@upstash/context7-pi<br/>(packages/pi)"]
Claude["Claude Code Plugin<br/>(plugins/claude/context7)"]
end
subgraph "Core"
SDK["@upstash/context7-sdk<br/>(packages/sdk)"]
end
API["context7.com/api<br/>(resolve + docs endpoints)"]
User --> CLI
User --> MCP
User --> AISDK
User --> Pi
User --> Claude
CLI --> SDK
MCP --> API
AISDK --> SDK
Pi --> SDK
Claude --> MCP
SDK --> APITwo important takeaways from the architecture:
- The
@upstash/context7-sdkpackage is the canonical TypeScript client. Most other clients either wrap it directly (AI SDK tools, Pi extension) or expose the same two-tool surface (MCP server, CLI) against the same backend. - The MCP server talks to the Context7 HTTP API directly, while the Vercel AI SDK tools and the Pi extension go through the SDK client. This layering keeps HTTP details in one place and lets higher-level packages focus on agent ergonomics (Source: packages/tools-ai-sdk/src/index.ts:1-20).
Package Inventory
| Package | Type | Primary Consumer | Authentication |
|---|---|---|---|
@upstash/context7-sdk | Core TypeScript SDK | Application developers, other packages | CONTEXT7_API_KEY or constructor apiKey |
@upstash/context7-tools-ai-sdk | Vercel AI SDK tools + agent | Vercel AI SDK applications | CONTEXT7_API_KEY or per-tool apiKey |
context7-mcp | MCP server (Model Context Protocol) | MCP-compatible clients (Claude Desktop, Cursor, etc.) | Optional CONTEXT7_API_KEY for higher rate limits |
ctx7 | Standalone CLI (npx) | Developers, agent setups | Optional API key; OAuth flow for some commands |
@upstash/context7-pi | Extension for the pi coding agent | pi users | CONTEXT7_API_KEY env var, IP-based fallback |
Claude Code plugin (context7-plugin) | Marketplace plugin | Claude Code | Optional CONTEXT7_API_KEY |
The root monorepo is a workspace using npm/pnpm-style packages, with shared TypeScript and ESLint configuration across the SDK and CLI (Source: package.json:1-30, Source: packages/sdk/eslint.config.js:1-30).
Core SDK: `@upstash/context7-sdk`
The SDK is the lowest-level programmatic entry point. It exposes a Context7 class and a small set of command modules. The two commands that the rest of the ecosystem is built on are:
- Search library — converts a library name into a list of matching Context7 library IDs.
- Get context — fetches documentation snippets and code examples for a given library ID and query.
The get-context command returns a strongly-typed payload composed of codeSnippets and infoSnippets, with each snippet carrying token counts, page identifiers, and structured code/language metadata (Source: packages/sdk/src/commands/get-context/types.ts:1-15).
The SDK is consumed transitively by the AI SDK tools package, which re-exports the relevant types alongside its own tool/agent exports (Source: packages/tools-ai-sdk/src/index.ts:15-20).
Vercel AI SDK Tools: `@upstash/context7-tools-ai-sdk`
This package provides Vercel AI SDK v5+ compatible tools and a pre-configured agent. According to the package README, its purpose is to:
- Add documentation lookup tools to AI SDK workflows using
generateTextorstreamText. - Provide a
Context7Agentfor higher-level agent loops. - Enable RAG pipelines that retrieve accurate, version-specific code examples (Source: packages/tools-ai-sdk/README.md:1-15).
Public Exports
The package's main entry point re-exports:
- Agent —
Context7Agentand itsContext7AgentConfigtype from@agents. - Tools —
resolveLibraryId,queryDocs, andContext7ToolsConfigfrom@tools. - Prompts —
SYSTEM_PROMPT,AGENT_PROMPT,RESOLVE_LIBRARY_ID_DESCRIPTION,QUERY_DOCS_DESCRIPTIONfrom@prompts. - Re-exported SDK types —
Context7Config,Library,Documentation,GetContextOptions(Source: packages/tools-ai-sdk/src/index.ts:1-20).
The Two Tools
The two AI SDK tools mirror the MCP tool naming and contract:
| Tool name | Purpose | Key input(s) |
|---|---|---|
resolveLibraryId | Convert a human-readable library name into a Context7 library ID | libraryName (required), query (required for relevance ranking) |
queryDocs | Fetch up-to-date documentation and code examples for a library | libraryId (required, /org/project format), query (required) |
Both tools can be invoked with or without configuration. If no apiKey is passed, the tool falls back to the CONTEXT7_API_KEY environment variable (Source: packages/tools-ai-sdk/src/tools/query-docs.ts:1-30).
Prompt System
The prompt module defines three layers of guidance that control how an LLM should use these tools:
SYSTEM_PROMPT— A minimal, role-level description ("documentation search assistant powered by Context7"). Useful when the model only needs a high-level orientation (Source: packages/tools-ai-sdk/src/prompts/system.ts:1-15).AGENT_PROMPT— A four-step explicit workflow: callresolveLibraryIdfirst, rank results, callqueryDocswith the chosen ID, then answer citing the library ID. It encodes selection heuristics such as preferring official sources, name similarity, source reputation (High/Medium), code snippet count, and benchmark score (Source: packages/tools-ai-sdk/src/prompts/system.ts:15-80).QUERY_DOCS_DESCRIPTION— The tool-level description that is included verbatim in the tool's schema, instructing the model not to call the tool more than 3 times per question (Source: packages/tools-ai-sdk/src/prompts/system.ts:80-100).
These prompts are also surfaced as named exports from the prompts barrel for consumers who want to compose their own agents (Source: packages/tools-ai-sdk/src/prompts/index.ts:1-10).
Tool Wiring with `generateText`
A typical integration uses generateText from the Vercel AI SDK, wires in both tools, and uses stepCountIs(5) (or similar) to bound the agent loop (Source: packages/tools-ai-sdk/README.md:25-55):
import { resolveLibraryId, queryDocs } from "@upstash/context7-tools-ai-sdk";
import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";
const { text } = await generateText({
model: openai("gpt-4o"),
prompt: "How do I use React Server Components?",
tools: {
resolveLibraryId: resolveLibraryId(),
getLibraryDocs: queryDocs(),
},
stopWhen: stepCountIs(5),
});
The integration tests in the package exercise both tools end-to-end against a real LLM (Bedrock Claude 3 Haiku in the test suite) and assert that the LLM calls the expected tool and receives a stringified payload containing "Context7-compatible library ID" (Source: packages/tools-ai-sdk/src/index.test.ts:25-60).
MCP Server: `context7-mcp`
The Model Context Protocol server is published as context7-mcp and is the recommended integration path for MCP-aware clients (Claude Desktop, Cursor, Windsurf, and others). The MCP server is implemented using @modelcontextprotocol/sdk and the runtime dependencies are listed in its package.json (Source: packages/mcp/package.json:1-40).
Server Identity and Instructions
When the MCP server starts, it registers server metadata (name, version, website, icon) and a detailed instructions string. The instructions tell the host exactly when to call the tools — including which kinds of questions warrant a Context7 lookup (libraries, frameworks, SDKs, APIs, CLIs, cloud services) and which do not (refactoring, scripts from scratch, business-logic debugging, code review, general programming concepts) (Source: packages/mcp/src/index.ts:1-30).
MCP Tools
The server registers two tools with titles and descriptions that mirror the AI SDK tools:
resolve-library-id— title "Resolve Context7 Library ID". Required inputs arelibraryNameandquery(the latter is used to rank results by relevance).query-docs— fetches documentation for the resolved ID (Source: packages/mcp/src/index.ts:30-50).
This naming parity is intentional: it allows the same agent prompt content (e.g. the rule installed by ctx7 setup) to work across the MCP server, the CLI, and direct AI SDK tool calls (Source: packages/cli/src/setup/templates.ts:1-80).
CLI: `ctx7`
The CLI is the on-ramp most developers encounter first. It is distributed as a bin entry (used by npx ctx7@latest …) and ships rule/skill templates that the ctx7 setup command installs into a project's coding-agent configuration (Source: packages/cli/CHANGELOG.md:1-30).
Core Commands
| Command | Purpose |
|---|---|
ctx7 library <name> <query> | Search the Context7 index by name and return matching libraries with IDs. |
ctx7 docs <libraryId> <query> | Fetch documentation for a library using its Context7 ID. |
ctx7 setup | Install Context7 rules, skills, and MCP config into the current project. |
ctx7 skills suggest | Scan project dependencies and recommend relevant skills. |
ctx7 skills generate | AI-powered generation of a new skill. |
ctx7 skills install | Install a discovered skill. |
ctx7 skills search | Browse available skills with install counts and trust scores. |
(Sources: README.md:60-90, packages/cli/CHANGELOG.md:1-30.)
Setup Templates and Agent Targeting
The setup command uses bundled templates that target multiple agent environments. The latest release (ctx7 0.4.5) added explicit support for Antigravity: the command now installs skills to .agent/skills, adds a GEMINI.md rule section, and writes MCP config to Antigravity 2.0's documented global path ~/.gemini/config/mcp_config.json (using httpUrl for HTTP, matching the Gemini convention) (Source: community release notes for [email protected]).
The templates also include generic fallback rules that teach an agent when to reach for the Context7 tools (or CLI) and when not to. The fallback rules explicitly direct the model to prefer Context7 over web search for library docs and to call resolve-library-id first, then query-docs with the user's full question (Source: packages/cli/src/setup/templates.ts:1-80).
Recent CLI Improvements
The 0.2.x CLI changelog also describes:
- An
installsandtrustcolumn in skill search results, aligned column headers, and a "View skill" action that opens the skill in$EDITOR(Source: packages/cli/CHANGELOG.md:15-30). - Telemetry for usage metrics, opt-out via
CTX7_TELEMETRY_DISABLED(Source: packages/cli/CHANGELOG.md:25-40). - OAuth-based auto-login when the generate command requires authentication (Source: packages/cli/CHANGELOG.md:15-30).
Pi Coding Agent Extension: `@upstash/context7-pi`
The Pi extension is installed with pi install npm:@upstash/context7-pi and contributes two LLM-callable tools, a skill, and a slash command. The two tools are resolve-library-id and query-docs, sharing names and contracts with the MCP and AI SDK tools (Source: packages/pi/README.md:1-30).
A /c7-docs <library> <question> slash command is provided for manual lookup, running the resolve + query flow in a single invocation. Authentication uses the CONTEXT7_API_KEY env var for higher quotas, with an IP-based rate limit fallback when no key is set (Source: packages/pi/README.md:20-50).
Claude Code Plugin: `context7-plugin`
The Claude Code plugin is distributed as a marketplace plugin and bundles the MCP server with Claude-specific extras:
- MCP server — connects Claude Code to Context7's documentation service.
- Skills — auto-trigger documentation lookups when the user asks about a library.
- Agents — a dedicated
docs-researcheragent for focused lookups. - Commands —
/context7:docsfor manual queries.
Installation is performed via the marketplace commands claude plugin marketplace add upstash/context7 and claude plugin install context7-plugin@context7-marketplace (Source: plugins/claude/context7/README.md:1-30).
Authentication and Configuration Patterns
The ecosystem consistently uses a single environment variable — CONTEXT7_API_KEY — to authenticate against the central Context7 API. The pattern is:
- SDK and AI SDK tools — pass
apiKeyto the constructor/tool factory, or setCONTEXT7_API_KEYand let the client fall back to it (Source: packages/tools-ai-sdk/src/tools/query-docs.ts:15-30). - MCP server — configured in the host's MCP config;
CONTEXT7_API_KEYis optional, but the rate limit is higher when provided. - CLI — relies on the same env var for higher limits; some flows (e.g.
ctx7 skills generate) trigger an OAuth login instead of failing with an error (Source: packages/cli/CHANGELOG.md:15-30). - Pi extension — same
CONTEXT7_API_KEYenv var, with IP-based fallback (Source: packages/pi/README.md:20-40).
The shared tool surface and naming (resolve-library-id / resolveLibraryId, query-docs / queryDocs) means that the same agent rule — and the same prompt — can be reused across all surfaces without modification (Source: packages/cli/src/setup/templates.ts:1-60).
Data Model: `get-context` Response
The get-context SDK command returns a typed payload that is reused by every consumer in the ecosystem. Its structure is:
| Field | Type | Description |
|---|---|---|
codeSnippets | ApiCodeSnippet[] | Extracted code examples with title, description, language, and a per-language codeList. |
infoSnippets | ApiInfoSnippet[] | Prose documentation snippets with breadcrumb and pageId for citation. |
Each ApiCodeSnippet carries a codeId (used to dedupe and reference) and optional codeTokens for budgeting; each ApiInfoSnippet carries a pageId and optional contentTokens (Source: packages/sdk/src/commands/get-context/types.ts:1-15). This single typed contract is what the AI SDK, MCP server, CLI, and Pi extension ultimately surface to the LLM as tool output.
Typical Resolution → Query Flow
Every consumer implements the same logical flow. The MCP server's tool description spells it out for the host LLM:
graph TD
A[User asks about a library] --> B{User provided<br/>/org/project or<br/>/org/project/version?}
B -- Yes --> D[query-docs with libraryId and full question]
B -- No --> C[resolve-library-id with libraryName and full question]
C --> E[Rank results by<br/>name match, reputation,<br/>snippets, benchmark]
E --> F[Pick best Context7 library ID]
F --> D
D --> G[Compose answer,<br/>cite library ID and snippets]This is enforced at the prompt level for the AI SDK: the AGENT_PROMPT mandates the same four-step procedure and bounds queryDocs to a maximum of 3 calls per question (Source: packages/tools-ai-sdk/src/prompts/system.ts:15-80). The CLI's fallback rule template, the MCP server's instructions, and the Pi extension's bundled skill all encode the same flow with the same selection criteria (Source: packages/cli/src/setup/templates.ts:1-80, Source: packages/mcp/src/index.ts:1-50, Source: packages/pi/README.md:30-50).
Community Context and Known Limitations
Several of the most-engaged community issues describe limitations that the SDKs, extensions, and plugin ecosystem inherits from its current single-backend architecture:
- Self-hosting the documentation backend (issue #59) — there is currently no supported way to point any of the SDKs, MCP server, CLI, or Pi extension at a self-hosted documentation API; everything routes through
context7.com/api. ThehttpUrlconfiguration introduced in the Antigravity setup is still pointed at the hosted service. - Offline / air-gapped environments (issue #320) — the MCP server and CLI both require internet access to resolve libraries and fetch docs. The SDK and AI SDK tools have no built-in cache or local index that would let them function fully offline.
- Private documents (issue #34) — there is no per-user account, document index, or per-user API key flow that would let the SDKs scope queries to private documents. The
CONTEXT7_API_KEYmodel is currently shared/global, not per-user. - Documentation versioning (issue #45) — version pinning is supported by including the version in the library ID (
/org/project/version) and in natural-language prompts, but the SDK does not expose a typed version-pinning option, and the AI SDK tool schemas do not require an explicit version field.
These are worth keeping in mind when designing integrations: any ecosystem consumer built today inherits the same hosted-only, online-only, public-only constraints.
See Also
- README.md — High-level overview and quickstart.
- packages/sdk/src/commands/get-context/types.ts — Canonical response types.
- packages/tools-ai-sdk/src/prompts/system.ts — Agent and tool prompt strings.
- packages/cli/src/setup/templates.ts — Agent rules and skill templates installed by
ctx7 setup. - packages/mcp/src/index.ts — MCP server tool registrations and instructions.
Source: https://github.com/upstash/context7 / Human Manual
Doramagic Pitfall Log
Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.
Developers may expose sensitive permissions or credentials: [Bug]: OAuth metadata issuer mismatch for MCP OAuth endpoint
Upgrade or migration may change expected behavior: @upstash/[email protected]
Developers may fail before the first successful local run: Add tool to search by npm package name to skip the initial docs index search, makes MCP server faster
Developers may fail before the first successful local run: [Feature Request] Local docs sync and numerous dx improvements
Doramagic Pitfall Log
Found 32 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.
1. Security or permission risk: Security or permission risk requires verification
- Severity: high
- Finding: Developers should check this security_permissions risk before relying on the project: [Bug]: OAuth metadata issuer mismatch for MCP OAuth endpoint
- User impact: Developers may expose sensitive permissions or credentials: [Bug]: OAuth metadata issuer mismatch for MCP OAuth endpoint
- Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: OAuth metadata issuer mismatch for MCP OAuth endpoint. Context: Source discussion did not expose a precise runtime context.
- Evidence: failure_mode_cluster:github_issue | fmev_95c37b5d4ec8d5ee4507509dad3c2a1f | https://github.com/upstash/context7/issues/2723
2. Installation risk: Installation risk requires verification
- Severity: medium
- Finding: Developers should check this installation risk before relying on the project: @upstash/[email protected]
- User impact: Upgrade or migration may change expected behavior: @upstash/[email protected]
- Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: @upstash/[email protected]. Context: Observed when using node
- Evidence: failure_mode_cluster:github_release | fmev_46f371ada1fbace84d952510823b7f4b | https://github.com/upstash/context7/releases/tag/%40upstash/context7-pi%400.1.0
3. Installation risk: Installation risk requires verification
- Severity: medium
- Finding: Developers should check this installation risk before relying on the project: Add tool to search by npm package name to skip the initial docs index search, makes MCP server faster
- User impact: Developers may fail before the first successful local run: Add tool to search by npm package name to skip the initial docs index search, makes MCP server faster
- Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Add tool to search by npm package name to skip the initial docs index search, makes MCP server faster. Context: Observed when using node
- Evidence: failure_mode_cluster:github_issue | fmev_97f541b9c1bdf6a270413d479cb65002 | https://github.com/upstash/context7/issues/230
4. Installation risk: Installation risk requires verification
- Severity: medium
- Finding: Developers should check this installation risk before relying on the project: [Feature Request] Local docs sync and numerous dx improvements
- User impact: Developers may fail before the first successful local run: [Feature Request] Local docs sync and numerous dx improvements
- Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [Feature Request] Local docs sync and numerous dx improvements. Context: Observed during installation or first-run setup.
- Evidence: failure_mode_cluster:github_issue | fmev_33ab52cf164db9dced1235e8c17026f6 | https://github.com/upstash/context7/issues/103
5. Installation risk: Installation risk requires verification
- Severity: medium
- Finding: Developers should check this installation risk before relying on the project: ctx7 setup --cli: downloadSkillFromGitHub missing Authorization header causes 403
- User impact: Developers may fail before the first successful local run: ctx7 setup --cli: downloadSkillFromGitHub missing Authorization header causes 403
- Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: ctx7 setup --cli: downloadSkillFromGitHub missing Authorization header causes 403. Context: Observed when using macos
- Evidence: failure_mode_cluster:github_issue | fmev_f983d67f6d5644dbb372458c86f98034 | https://github.com/upstash/context7/issues/2363
6. Installation risk: Installation risk requires verification
- Severity: medium
- Finding: Developers should check this installation risk before relying on the project: [email protected]
- User impact: Upgrade or migration may change expected behavior: [email protected]
- Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [email protected]. Context: Observed during installation or first-run setup.
- Evidence: failure_mode_cluster:github_release | fmev_9786b7981f1e51c97bd00ed6170af655 | https://github.com/upstash/context7/releases/tag/ctx7%400.4.5
7. Installation risk: Installation risk requires verification
- Severity: medium
- Finding: Developers should check this installation risk before relying on the project: [email protected]
- User impact: Upgrade or migration may change expected behavior: [email protected]
- Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [email protected]. Context: Observed when using docker
- Evidence: failure_mode_cluster:github_release | fmev_5ee21e73150b416333eaa911b8e0c948 | https://github.com/upstash/context7/releases/tag/ctx7%400.5.1
8. Installation risk: Installation risk requires verification
- Severity: medium
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_37c5d19255fa423199c3f5f0b317c9b1 | https://github.com/upstash/context7/issues/230
9. Configuration risk: Configuration risk requires verification
- Severity: medium
- Finding: Developers should check this configuration risk before relying on the project: @upstash/[email protected]
- User impact: Upgrade or migration may change expected behavior: @upstash/[email protected]
- Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: @upstash/[email protected]. Context: Source discussion did not expose a precise runtime context.
- Evidence: failure_mode_cluster:github_release | fmev_554228c877dad4ddb42a45c3dcf8b001 | https://github.com/upstash/context7/releases/tag/%40upstash/context7-mcp%403.1.0
10. Configuration risk: Configuration risk requires verification
- Severity: medium
- Finding: Developers should check this configuration risk before relying on the project: Feature Request: Support multiple product docs in one repo
- User impact: Developers may misconfigure credentials, environment, or host setup: Feature Request: Support multiple product docs in one repo
- Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Feature Request: Support multiple product docs in one repo. Context: Source discussion did not expose a precise runtime context.
- Evidence: failure_mode_cluster:github_issue | fmev_752d9c6ad1111e7576eb2b756e09be9a | https://github.com/upstash/context7/issues/328
11. Configuration risk: Configuration risk requires verification
- Severity: medium
- Finding: Developers should check this configuration risk before relying on the project: [Bug]: ctx7 setup on a remote server fails login
- User impact: Developers may misconfigure credentials, environment, or host setup: [Bug]: ctx7 setup on a remote server fails login
- Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: ctx7 setup on a remote server fails login. Context: Observed when using node
- Evidence: failure_mode_cluster:github_issue | fmev_8bd9c73c4b097b45bbb9bf50dec280be | https://github.com/upstash/context7/issues/2693
12. Configuration risk: Configuration risk requires verification
- Severity: medium
- Finding: Developers should check this configuration risk before relying on the project: [email protected]
- User impact: Upgrade or migration may change expected behavior: [email protected]
- Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [email protected]. Context: Observed when using docker, linux
- Evidence: failure_mode_cluster:github_release | fmev_3704dcb3c12460ca1521e1f999dbba13 | https://github.com/upstash/context7/releases/tag/ctx7%400.5.0
Source: Doramagic discovery, validation, and Project Pack records
Community Discussion Evidence
These external discussion links are review inputs, not standalone proof that the project is production-ready.
Count of project-level external discussion links exposed on this manual page.
Open the linked issues or discussions before treating the pack as ready for your environment.
Community Discussion Evidence
Doramagic exposes project-level community discussion separately from official documentation. Review these links before using context7 with real data or production workflows.
- ctx7 setup --cli: downloadSkillFromGitHub missing Authorization header c - github / github_issue
- Library Report: /powershell/powershell - Missing or incorrect documentat - github / github_issue
- Add tool to search by npm package name to skip the initial docs index se - github / github_issue
- Library Report: /websites/openwrt - Missing or incorrect documentation. - github / github_issue
- Library Report: /websites/help_obsidian_md - Missing or incorrect docume - github / github_issue
- Library Report: /websites/antigravity_google_home - Missing or incorrect - github / github_issue
- Security or permission risk requires verification - GitHub / issue
- Installation risk requires verification - GitHub / issue
- Installation risk requires verification - GitHub / issue
- Installation risk requires verification - GitHub / issue
- Installation risk requires verification - GitHub / issue
- Configuration risk requires verification - GitHub / issue
Source: Project Pack community evidence and pitfall evidence