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

Section Related Pages

Continue reading this section for the full explanation and source context.

Section 1.1 The Problem Context7 Solves

Continue reading this section for the full explanation and source context.

Section 1.2 High-Level Capabilities

Continue reading this section for the full explanation and source context.

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

ProblemHow Context7 Responds
Year-old training data in LLMsFresh, source-driven docs fetched at request time
Hallucinated APIsSnippets keyed to a real libraryId (e.g. /vercel/next.js)
Generic answers for old versionsVersioned library IDs and slash-command hints (e.g. use library /vercel/next.js/v14.2.0)
Repetitive boilerplate explanationsPre-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

Section Related Pages

Continue reading this section for the full explanation and source context.

Section resolve-library-id

Continue reading this section for the full explanation and source context.

Section query-docs

Continue reading this section for the full explanation and source context.

Section Recommended Two-Step Workflow

Continue reading this section for the full explanation and source context.

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.-> A

The 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.

ParameterTypeRequiredDescription
querystringyesThe user's question or task. Used to rank results by relevance.
libraryNamestringyesThe 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/project form.
  • Name and Description.
  • Code Snippets count — higher is better.
  • Source ReputationHigh, Medium, Low, or Unknown.
  • 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:

  1. Analyze the query to understand the library/package the user wants.
  2. 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

ParameterTypeRequiredDescription
libraryIdstringyesExact Context7-compatible library ID (e.g., /mongodb/docs, /vercel/next.js).
querystringyesThe 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

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

AgentMCP config fileRule fileSkill directory
claude~/.claude.json / .mcp.jsonCLAUDE.md.claude/skills
cursor~/.cursor/mcp.json / .cursor/mcp.jsonCursor Rules.cursor/skills
codex~/.codex/config.tomlAGENTS.md.codex/skills
opencodeopencode.jsonAGENTS.md.opencode/skill
gemini~/.gemini/settings.jsonGEMINI.md
antigravity~/.gemini/config/mcp_config.json~/.gemini/GEMINI.md / GEMINI.md.agent/skills

Source: packages/cli/src/setup/agents.ts

`setup` Command Flags

FlagEffect
--claudeConfigure for Claude Code
--cursorConfigure for Cursor
--codexConfigure for Codex CLI
--opencodeConfigure for opencode
--geminiConfigure for Gemini CLI
--antigravityConfigure for Antigravity 2.0 (added in [email protected])
--projectWrite config to the project (vs. the user's home directory)
--stdioUse stdio transport instead of HTTP
--mcpSetup mode: install only the MCP config
--cliSetup mode: install only the CLI
--api-key <k>Use a specific API key
--oauthAuthenticate via OAuth
--yesNon-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 setup now properly supports --antigravity, installing skills to .agent/skills, a GEMINI.md rule section (Antigravity reads Gemini-family config), and MCP config to Antigravity 2.0's documented global path ~/.gemini/config/mcp_config.json (with httpUrl for 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-idquery-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:

SurfaceHow to invoke research mode
MCP toolCall the researchMode MCP tool
CLIctx7 docs --research <libraryId> <query>

Source: packages/cli/CHANGELOG.md

"Expose research mode through the MCP researchMode tool and the CLI docs --research flag 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

CommandDescription
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> --researchUse research mode for deeper, agent-driven answers.
`ctx7 setup [--claude\--cursor\...]`One-shot installer for a coding agent.
ctx7 removeCleanup counterpart to ctx7 setup; preserves non-Context7 MCP entries.
ctx7 upgradeCheck for a newer CLI version with safer guidance across npm/pnpm/bun.
ctx7 skills suggestScan 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 generateAI-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-docs skill 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| API

Configuration Reference

Environment variableUsed byPurpose
CONTEXT7_API_KEYMCP server, AI SDK, pi, CLIAuthenticated requests, raises quota above IP-based limits.
CTX7_TELEMETRY_DISABLEDCLIDisable fire-and-forget usage events posted to /api/v2/cli/events.
EDITORCLIEditor 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 setup so the agent's MCP config is regenerated and the rule/skill are installed.
  • Export CONTEXT7_API_KEY in 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 install path 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 --- IDX

Source: README.md, packages/mcp/package.json

See Also

  • Context7 Platform README
  • @upstash/context7-mcp package 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 setup command
  • 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

Section Related Pages

Continue reading this section for the full explanation and source context.

Section What ctx7 setup Does

Continue reading this section for the full explanation and source context.

Section Supported Agents

Continue reading this section for the full explanation and source context.

Section Version Pinning

Continue reading this section for the full explanation and source context.

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:

PackageRoleSource
packages/mcpModel Context Protocol server for editors that speak MCPpackages/mcp/package.json:1-15
packages/tools-ai-sdkVercel AI SDK tools (resolveLibraryId, queryDocs) and a Context7Agentpackages/tools-ai-sdk/src/index.ts:1-15
packages/cli (ctx7)Human-facing CLI for library lookups, agent setup, and skill managementpackages/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.

CommandPurposeKey Flags / Notes
ctx7 setupConfigure MCP + rules + skills for one or more AI agents--cursor, --claude, --opencode, --antigravity, --all-agents, --yes
ctx7 removeUndo a setup, removing only Context7-owned artifactsPrompts only for agents that actually contain Context7 entries
ctx7 upgradeUpdate 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 installInstall one or more skills into detected agent directories--all-agents, --yes
ctx7 skills searchBrowse the skill hub with install counts and trust scoresColumns: Installs, Trust (0–10)
ctx7 skills listList skills already present in detected directoriesNo prompt (per 0.2.0 simplification)
ctx7 skills suggestScan package.json, requirements.txt, pyproject.toml and recommend skillsBased on project dependencies
ctx7 skills generateAI-powered generation of a new skill (OAuth-gated)Includes a feedback loop and a weekly quota
ctx7 login / logoutOAuth 2.0 authenticationStores a refreshable token
ctx7 whoamiDisplay identity, teamspace, and active teamspace nameUses 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:

  1. Authenticate via OAuth 2.0 and persist a refreshable token plus an API key Source: [packages/cli/CHANGELOG.md:78-92].
  2. Write an MCP server entry to the agent's config file, using the agent-specific key (mcpServers, mcp_config.json, etc.).
  3. 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 context7 plugin via the Claude marketplace; ships a docs-researcher agent, a /context7:docs command, and a find-docs skill Source: [plugins/claude/context7/README.md:1-30].
  • Cursor — writes mcp.json, an always-on use-context7 rule (with alwaysApply: true), and a context7-docs-lookup skill Source: [plugins/cursor/context7/README.md:1-22].
  • OpenCode / Codex — write to AGENTS.md (OpenCode was migrated from .opencode/rules/ in 0.3.10) Source: [packages/cli/CHANGELOG.md:38-45].
  • Antigravity — global config at ~/.gemini/config/mcp_config.json, project-level rule in GEMINI.md, skill in .agent/skills Source: [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: removed shell: true from the spawn call in the generate command to prevent command injection via the EDITOR environment 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:

FieldTypeDescription
namestringDisplay name shown in prompts and search results
descriptionstringOne-line description used for the skill's invocation trigger
urlstringCanonical URL on context7.com
installCountnumberCumulative install counter, shown as ↓100+ style buckets Source: [packages/cli/CHANGELOG.md:95-100]
trustScorenumber0–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] --> E

Each command maps to a specific user goal:

  • skills suggest scans package.json, requirements.txt, and pyproject.toml to recommend skills that match the project's actual dependencies Source: [packages/cli/CHANGELOG.md:115-118].
  • skills search returns 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 install supports --all-agents (write to every detected agent) and --yes (non-interactive) Source: [packages/cli/CHANGELOG.md:18-21].
  • skills generate is the AI wizard: it asks clarifying questions, streams query progress, lets the user give feedback, and enforces a weekly quota. Generation requires OAuth, and 0.2.2 added auto-login via OAuth when the command is run unauthenticated Source: [packages/cli/CHANGELOG.md:108-115].
  • skills list is now promptless since 0.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:

  1. ctx7 login opens a browser window, performs the OAuth dance, and stores a refreshable token plus an API key.
  2. The API key is written to the agent's MCP config so the editor can authenticate against the Context7 API.
  3. ctx7 whoami reports the identity, teamspace, and active teamspace name; the 0.3.6 release centralized the auth constants and switched whoami to 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

VariablePurposeSource
CONTEXT7_API_KEYFallback API key for CLI and SDK callspackages/pi/README.md:18-22
CTX7_TELEMETRY_DISABLEDSuppresses the fire-and-forget telemetry events emitted to /api/v2/cli/eventspackages/cli/CHANGELOG.md:102-106
EDITORUsed 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's tool() helper and can be used directly with generateText/streamText Source: [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

SymptomLikely CauseMitigation
ctx7 setup writes a config file the agent ignoresWrong 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 WindowsBackslash 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 editorEDITOR 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 dataSkill find-docs not installed or alwaysApply: falseRe-run ctx7 setup and verify the rule was written
Network or DNS failures inside Codex sandboxCodex defaults to a sandboxed networkThe CLI ships Codex-specific guidance to rerun outside the sandbox Source: [packages/cli/CHANGELOG.md:26-30]
High-traffic requests throttledUnauthenticated IP-based rate limitGenerate 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 documented CTX7_API_BASE override in the retrieved sources.
  • Offline / air-gapped operation (issue #320) — the CLI's docs and library commands 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.6 is 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, and 0.4.5 reflect 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 --version flag in the retrieved sources.

Upgrade Path and Changelog Highlights

VersionChangeSource
0.4.5--antigravity support for ctx7 setuppackages/cli/CHANGELOG.md:1-10
0.4.0researchMode MCP tool and ctx7 docs --researchpackages/cli/CHANGELOG.md:5-10
0.3.6OAuth refresh, centralized auth, whoami teamspacepackages/cli/CHANGELOG.md:72-78
0.3.10Universal skills at ~/.agents/skills, OpenCode → AGENTS.md, find-docs description rewritepackages/cli/CHANGELOG.md:38-45
0.3.7shell: true removal; directory-traversal fixpackages/cli/CHANGELOG.md:55-61
0.3.11skills install --all-agents --yespackages/cli/CHANGELOG.md:18-21
0.2.3skills suggest dependency scanpackages/cli/CHANGELOG.md:115-118
0.2.2--json skills search, OAuth auto-login in generatepackages/cli/CHANGELOG.md:108-115
0.2.0skills generate wizard + OAuth login/logout/whoamipackages/cli/CHANGELOG.md:120-128

See Also

  • Context7 Main README — overview, install links, and video tutorials.
  • @upstash/context7-tools-ai-sdk README — 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 — pi coding 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

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Public Exports

Continue reading this section for the full explanation and source context.

Section The Two Tools

Continue reading this section for the full explanation and source context.

Section Prompt System

Continue reading this section for the full explanation and source context.

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 --> API

Two important takeaways from the architecture:

  1. The @upstash/context7-sdk package 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.
  2. 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

PackageTypePrimary ConsumerAuthentication
@upstash/context7-sdkCore TypeScript SDKApplication developers, other packagesCONTEXT7_API_KEY or constructor apiKey
@upstash/context7-tools-ai-sdkVercel AI SDK tools + agentVercel AI SDK applicationsCONTEXT7_API_KEY or per-tool apiKey
context7-mcpMCP server (Model Context Protocol)MCP-compatible clients (Claude Desktop, Cursor, etc.)Optional CONTEXT7_API_KEY for higher rate limits
ctx7Standalone CLI (npx)Developers, agent setupsOptional API key; OAuth flow for some commands
@upstash/context7-piExtension for the pi coding agentpi usersCONTEXT7_API_KEY env var, IP-based fallback
Claude Code plugin (context7-plugin)Marketplace pluginClaude CodeOptional 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 generateText or streamText.
  • Provide a Context7Agent for 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:

  • AgentContext7Agent and its Context7AgentConfig type from @agents.
  • ToolsresolveLibraryId, queryDocs, and Context7ToolsConfig from @tools.
  • PromptsSYSTEM_PROMPT, AGENT_PROMPT, RESOLVE_LIBRARY_ID_DESCRIPTION, QUERY_DOCS_DESCRIPTION from @prompts.
  • Re-exported SDK typesContext7Config, 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 namePurposeKey input(s)
resolveLibraryIdConvert a human-readable library name into a Context7 library IDlibraryName (required), query (required for relevance ranking)
queryDocsFetch up-to-date documentation and code examples for a librarylibraryId (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: call resolveLibraryId first, rank results, call queryDocs with 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 are libraryName and query (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

CommandPurpose
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 setupInstall Context7 rules, skills, and MCP config into the current project.
ctx7 skills suggestScan project dependencies and recommend relevant skills.
ctx7 skills generateAI-powered generation of a new skill.
ctx7 skills installInstall a discovered skill.
ctx7 skills searchBrowse 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 installs and trust column 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-researcher agent for focused lookups.
  • Commands/context7:docs for 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 apiKey to the constructor/tool factory, or set CONTEXT7_API_KEY and 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_KEY is 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_KEY env 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:

FieldTypeDescription
codeSnippetsApiCodeSnippet[]Extracted code examples with title, description, language, and a per-language codeList.
infoSnippetsApiInfoSnippet[]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. The httpUrl configuration 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_KEY model 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.

high Security or permission risk requires verification

Developers may expose sensitive permissions or credentials: [Bug]: OAuth metadata issuer mismatch for MCP OAuth endpoint

medium Installation risk requires verification

Upgrade or migration may change expected behavior: @upstash/[email protected]

medium Installation risk requires verification

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

medium Installation risk requires verification

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.

Sources 12

Count of project-level external discussion links exposed on this manual page.

Use Review before install

Open the linked issues or discussions before treating the pack as ready for your environment.

Source: Project Pack community evidence and pitfall evidence