Getting Started#

@upstash/context7-sdk is a TypeScript SDK for Context7, enabling easier access to library documentation with full type coverage.

Using @upstash/context7-sdk you can:

• Search across available libraries
• Get documentation context for any library
• Access library metadata including trust scores and versions

You can find the Github Repository here.

Install#

npm install @upstash/context7-sdk

Usage#

Initializing the Client#

To use the Context7 SDK, you need an API key. You can get your API key from the Context7 Dashboard.

Using environment variables#

The SDK automatically reads from environment variables if no API key is provided in the config:

CONTEXT7_API_KEY="your_api_key_here"

When an environment variable is set, you can initialize the client without any parameters:

import { Context7 } from "@upstash/context7-sdk";const client = new Context7();

Using a configuration object#

If you prefer to pass configuration in code, the constructor accepts a config object containing the apiKey value. This could be useful if your application needs to interact with multiple projects, each with a different configuration.

import { Context7 } from "@upstash/context7-sdk";const client = new Context7({  apiKey: "YOUR_API_KEY",});

Production HTTP configuration#

The SDK applies a 30-second request timeout and retries transient network failures, 408, 425, 429, and 5xx responses. Only GET requests are retried; mutating requests remain single-attempt.

const client = new Context7({  apiKey: "YOUR_API_KEY",  timeout: 10_000,  retry: {    retries: 3,    backoff: (attempt) => 100 * 2 ** attempt,  },  onResponse: ({ status, requestId, rateLimit, attempt }) => {    console.log({ status, requestId, rateLimit, attempt });  },});

baseUrl defaults to https://context7.com/api and overrides where the SDK sends requests. Point it at a proxy or a self-hosted deployment to route the SDK elsewhere:

const client = new Context7({  apiKey: "YOUR_API_KEY",  baseUrl: "https://context7.internal.example/api",});

You can also configure additional headers, keepAlive, the native fetch cache mode, a client-wide abort signal, or a custom fetch implementation. The SDK always sets Authorization from the configured API key; additional headers cannot override it.

The MCP server reads the equivalent CONTEXT7_API_URL environment variable; see the Developer Guide.

Following the same convention as @upstash/redis, a signal factory can provide a fresh timeout signal for each request:

const client = new Context7({  apiKey: "YOUR_API_KEY",  signal: () => AbortSignal.timeout(10_000),});

Set retry: false to make exactly one request or timeout: false to disable the default timeout.

Quick Start Example#

import { Context7 } from "@upstash/context7-sdk";const client = new Context7();// Search for librariesconst libraries = await client.searchLibrary(  "I need to build a UI with components",  "react");console.log(`Found ${libraries.length} libraries`);console.log(libraries[0].id); // "/facebook/react"// Get documentation as JSON array (default)const docs = await client.getContext(  "How do I use hooks?",  "/facebook/react");console.log(docs[0].title, docs[0].content);// Get documentation context as plain textconst context = await client.getContext("How do I use hooks?", "/facebook/react", {  type: "txt",  timeout: 5_000,});console.log(context);

Error Handling#

The SDK throws Context7Error for API errors:

import { Context7, Context7Error } from "@upstash/context7-sdk";const client = new Context7();try {  const context = await client.getContext("query", "/invalid/library");} catch (error) {  if (error instanceof Context7Error) {    console.error("Context7 API Error:", {      message: error.message,      code: error.code,      status: error.status,      requestId: error.requestId,      rateLimit: error.rateLimit,      retryable: error.retryable,    });  } else {    console.error("Unexpected error:", error);  }}

Next Steps#

Explore the SDK commands:

• Search Library - Search for libraries
• Get Context - Retrieve library documentation context