Getting Started

Get started with the Context7 TypeScript SDK

Work in Progress: This SDK is currently under active development. The API is subject to change and may introduce breaking changes in future releases.

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

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",
});

The SDK checks for API keys in this order: 1. config.apiKey (if provided) 2. process.env.CONTEXT7_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 libraries
const 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 text
const 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