# upstash/context7 architecture

> Architecture diagram of the GitHub repository upstash/context7, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/upstash/context7
- Repository: https://github.com/upstash/context7
- Video tour (about a minute): https://gitdiagram.com/upstash/context7/video

## Overview

Context7 delivers current, version-specific library documentation and source code to AI coding agents. The primary workflow is an agent invoking a Context7 tool, which resolves or uses a library ID, fetches documentation or code from the Context7 API, and returns results to the agent. The repository also provides CLI setup and authentication, client integrations, an SDK, and an administrative MCP console. Relationships below are limited to README statements and the supplied excerpts or SOURCE INDEX references; unsampled subsystem details are not inferred.

Main entry points: [`packages/mcp/src/index.ts`](https://github.com/upstash/context7/blob/master/packages/mcp/src/index.ts) (MCP entry), [`packages/mcp/src/lib/api.ts`](https://github.com/upstash/context7/blob/master/packages/mcp/src/lib/api.ts) (Context API), [`packages/admin-mcp/src/server.ts`](https://github.com/upstash/context7/blob/master/packages/admin-mcp/src/server.ts) (Admin MCP server), [`packages/admin-mcp/ui/src/app.tsx`](https://github.com/upstash/context7/blob/master/packages/admin-mcp/ui/src/app.tsx) (Console UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP service"]
  node_mcp["MCP entry<br/>[index.ts]"]
  node_api["Context API<br/>[api.ts]"]
  node_search["Library discovery<br/>[api.ts]"]
  node_docs["Documentation query<br/>[index.ts]"]
  node_code["Code query<br/>[query-code-tool.ts]"]
  node_preview["Preview tools"]
  node_auth["HTTP auth<br/>[mcp-http-auth.ts]"]
  node_telemetry["Telemetry runtime"]
end

subgraph group_cli["CLI setup"]
  node_setup["CLI setup<br/>[setup.ts]"]
  node_cliauth["CLI authentication<br/>[auth.ts]"]
  node_authutil["Credential handling<br/>[auth.ts]"]
  node_storage["Credential paths<br/>[storage-paths.ts]"]
  node_clisearch["CLI search<br/>[search.ts]"]
end

subgraph group_clients["Client integrations"]
  node_sdk["JavaScript SDK<br/>[client.ts]"]
  node_aisdk["AI SDK tools<br/>[query-docs.ts]"]
  node_pi["Pi integration<br/>[query-docs.ts]"]
  node_opencode["OpenCode integration<br/>[index.ts]"]
end

subgraph group_admin["Admin console"]
  node_adminserver["Admin MCP server<br/>[server.ts]"]
  node_admintools["Admin tools<br/>[tools.ts]"]
  node_consoleui["Console UI<br/>[app.tsx]"]
  node_uidata["Console data<br/>[data.ts]"]
  node_components["Console components<br/>[components.tsx]"]
  node_consolehtml["Console HTML<br/>[console-html.ts]"]
end

node_agent(("AI coding agent"))
node_upstream["Context7 API service"]
node_cliuser(("CLI operator"))

node_agent -->|"invokes tools"| node_mcp
node_mcp -->|"uses API"| node_api
node_mcp -->|"registers tools"| node_preview
node_mcp -->|"configures auth"| node_auth
node_mcp -->|"configures telemetry"| node_telemetry
node_preview -->|"registers query"| node_code
node_code -->|"fetches code"| node_api
node_search -->|"searches libraries"| node_upstream
node_api -->|"requests data"| node_upstream
node_agent -->|"uses client"| node_sdk
node_agent -->|"uses tools"| node_aisdk
node_agent -->|"uses integration"| node_pi
node_agent -.->|"uses integration"| node_opencode
node_cliuser -->|"runs setup"| node_setup
node_setup -->|"authenticates"| node_cliauth
node_cliauth -->|"starts login"| node_authutil
node_authutil -->|"resolves paths"| node_storage
node_cliuser -.->|"searches docs"| node_clisearch
node_cliuser -->|"configures MCP"| node_mcp
node_adminserver -->|"runs tools"| node_admintools
node_consoleui -->|"renders components"| node_components
node_consoleui -->|"uses data"| node_uidata
node_adminserver -->|"serves console"| node_consolehtml

click node_mcp "https://github.com/upstash/context7/blob/master/packages/mcp/src/index.ts"
click node_api "https://github.com/upstash/context7/blob/master/packages/mcp/src/lib/api.ts"
click node_search "https://github.com/upstash/context7/blob/master/packages/mcp/src/lib/api.ts"
click node_docs "https://github.com/upstash/context7/blob/master/packages/mcp/src/index.ts"
click node_code "https://github.com/upstash/context7/blob/master/packages/mcp/src/lib/query-code-tool.ts"
click node_preview "https://github.com/upstash/context7/blob/master/packages/mcp/src/lib/research-preview-tools.ts"
click node_auth "https://github.com/upstash/context7/blob/master/packages/mcp/src/lib/mcp-http-auth.ts"
click node_telemetry "https://github.com/upstash/context7/blob/master/packages/mcp/src/lib/telemetry-runtime.ts"
click node_setup "https://github.com/upstash/context7/blob/master/packages/cli/src/commands/setup.ts"
click node_cliauth "https://github.com/upstash/context7/blob/master/packages/cli/src/commands/auth.ts"
click node_authutil "https://github.com/upstash/context7/blob/master/packages/cli/src/utils/auth.ts"
click node_storage "https://github.com/upstash/context7/blob/master/packages/cli/src/utils/storage-paths.ts"
click node_clisearch "https://github.com/upstash/context7/blob/master/packages/cli/src/commands/search.ts"
click node_sdk "https://github.com/upstash/context7/blob/master/packages/sdk/src/client.ts"
click node_aisdk "https://github.com/upstash/context7/blob/master/packages/tools-ai-sdk/src/tools/query-docs.ts"
click node_pi "https://github.com/upstash/context7/blob/master/packages/pi/lib/tools/query-docs.ts"
click node_opencode "https://github.com/upstash/context7/blob/master/packages/opencode/src/index.ts"
click node_adminserver "https://github.com/upstash/context7/blob/master/packages/admin-mcp/src/server.ts"
click node_admintools "https://github.com/upstash/context7/blob/master/packages/admin-mcp/src/tools.ts"
click node_consoleui "https://github.com/upstash/context7/blob/master/packages/admin-mcp/ui/src/app.tsx"
click node_uidata "https://github.com/upstash/context7/blob/master/packages/admin-mcp/ui/src/data.ts"
click node_components "https://github.com/upstash/context7/blob/master/packages/admin-mcp/ui/src/components.tsx"
click node_consolehtml "https://github.com/upstash/context7/blob/master/packages/admin-mcp/src/ui/console-html.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_api,node_search,node_docs,node_code,node_preview,node_auth,node_telemetry toneBlue
class node_setup,node_cliauth,node_authutil,node_storage,node_clisearch toneAmber
class node_sdk,node_aisdk,node_pi,node_opencode,node_upstream toneMint
class node_adminserver,node_admintools,node_consoleui,node_uidata,node_components,node_consolehtml toneRose
class node_agent,node_cliuser toneIndigo
```

## Components

### MCP service

- [MCP entry](https://github.com/upstash/context7/blob/master/packages/mcp/src/index.ts): `packages/mcp/src/index.ts`
- [Context API](https://github.com/upstash/context7/blob/master/packages/mcp/src/lib/api.ts): `packages/mcp/src/lib/api.ts`
- [Library discovery](https://github.com/upstash/context7/blob/master/packages/mcp/src/lib/api.ts): `packages/mcp/src/lib/api.ts`
- [Documentation query](https://github.com/upstash/context7/blob/master/packages/mcp/src/index.ts): `packages/mcp/src/index.ts`
- [Code query](https://github.com/upstash/context7/blob/master/packages/mcp/src/lib/query-code-tool.ts): `packages/mcp/src/lib/query-code-tool.ts`
- [Preview tools](https://github.com/upstash/context7/blob/master/packages/mcp/src/lib/research-preview-tools.ts): `packages/mcp/src/lib/research-preview-tools.ts`
- [HTTP auth](https://github.com/upstash/context7/blob/master/packages/mcp/src/lib/mcp-http-auth.ts): `packages/mcp/src/lib/mcp-http-auth.ts`
- [Telemetry runtime](https://github.com/upstash/context7/blob/master/packages/mcp/src/lib/telemetry-runtime.ts): `packages/mcp/src/lib/telemetry-runtime.ts`

### CLI setup

- [CLI setup](https://github.com/upstash/context7/blob/master/packages/cli/src/commands/setup.ts): `packages/cli/src/commands/setup.ts`
- [CLI authentication](https://github.com/upstash/context7/blob/master/packages/cli/src/commands/auth.ts): `packages/cli/src/commands/auth.ts`
- [Credential handling](https://github.com/upstash/context7/blob/master/packages/cli/src/utils/auth.ts): `packages/cli/src/utils/auth.ts`
- [Credential paths](https://github.com/upstash/context7/blob/master/packages/cli/src/utils/storage-paths.ts): `packages/cli/src/utils/storage-paths.ts`
- [CLI search](https://github.com/upstash/context7/blob/master/packages/cli/src/commands/search.ts): `packages/cli/src/commands/search.ts`

### Client integrations

- [JavaScript SDK](https://github.com/upstash/context7/blob/master/packages/sdk/src/client.ts): `packages/sdk/src/client.ts`
- [AI SDK tools](https://github.com/upstash/context7/blob/master/packages/tools-ai-sdk/src/tools/query-docs.ts): `packages/tools-ai-sdk/src/tools/query-docs.ts`
- [Pi integration](https://github.com/upstash/context7/blob/master/packages/pi/lib/tools/query-docs.ts): `packages/pi/lib/tools/query-docs.ts`
- [OpenCode integration](https://github.com/upstash/context7/blob/master/packages/opencode/src/index.ts): `packages/opencode/src/index.ts`

### Admin console

- [Admin MCP server](https://github.com/upstash/context7/blob/master/packages/admin-mcp/src/server.ts): `packages/admin-mcp/src/server.ts`
- [Admin tools](https://github.com/upstash/context7/blob/master/packages/admin-mcp/src/tools.ts): `packages/admin-mcp/src/tools.ts`
- [Console UI](https://github.com/upstash/context7/blob/master/packages/admin-mcp/ui/src/app.tsx): `packages/admin-mcp/ui/src/app.tsx`
- [Console data](https://github.com/upstash/context7/blob/master/packages/admin-mcp/ui/src/data.ts): `packages/admin-mcp/ui/src/data.ts`
- [Console components](https://github.com/upstash/context7/blob/master/packages/admin-mcp/ui/src/components.tsx): `packages/admin-mcp/ui/src/components.tsx`
- [Console HTML](https://github.com/upstash/context7/blob/master/packages/admin-mcp/src/ui/console-html.ts): `packages/admin-mcp/src/ui/console-html.ts`

### Other components

- **AI coding agent**
- **Context7 API service**
- **CLI operator**

## Connections

- AI coding agent → MCP entry: invokes tools (evidence: `README.md`)
- MCP entry → Context API: uses API (evidence: `packages/mcp/src/index.ts`)
- MCP entry → Preview tools: registers tools (evidence: `packages/mcp/src/index.ts`)
- MCP entry → HTTP auth: configures auth (evidence: `packages/mcp/src/index.ts`)
- MCP entry → Telemetry runtime: configures telemetry (evidence: `packages/mcp/src/index.ts`)
- Preview tools → Code query: registers query (evidence: `packages/mcp/src/lib/research-preview-tools.ts`)
- Code query → Context API: fetches code (evidence: `packages/mcp/src/lib/query-code-tool.ts`)
- Library discovery → Context7 API service: searches libraries (evidence: `packages/mcp/src/lib/api.ts`)
- Context API → Context7 API service: requests data (evidence: `packages/mcp/src/lib/api.ts`)
- AI coding agent → JavaScript SDK: uses client (evidence: `README.md`)
- AI coding agent → AI SDK tools: uses tools (evidence: `README.md`)
- AI coding agent → Pi integration: uses integration
- AI coding agent → OpenCode integration: uses integration
- CLI operator → CLI setup: runs setup (evidence: `README.md`)
- CLI setup → CLI authentication: authenticates
- CLI authentication → Credential handling: starts login (evidence: `packages/cli/src/commands/auth.ts`)
- Credential handling → Credential paths: resolves paths (evidence: `packages/cli/src/utils/auth.ts`)
- CLI operator → CLI search: searches docs
- CLI operator → MCP entry: configures MCP (evidence: `README.md`)
- Admin MCP server → Admin tools: runs tools (evidence: `packages/admin-mcp/src/server.ts`)
- Console UI → Console components: renders components (evidence: `packages/admin-mcp/ui/src/app.tsx`)
- Console UI → Console data: uses data (evidence: `packages/admin-mcp/ui/src/app.tsx`)
- Admin MCP server → Console HTML: serves console
