0
Fork 0
mirror of https://codeberg.org/dkb/open-context-7.git synced 2026-11-17 19:44:05 +00:00
No description
  • TypeScript 99.4%
  • Dockerfile 0.6%
Find a file
History 2026-07-09 15:03:46 +05:30
.github/workflows Initial Commit 2026-07-09 15:03:46 +05:30
scripts Initial Commit 2026-07-09 15:03:46 +05:30
src Initial Commit 2026-07-09 15:03:46 +05:30
tests Initial Commit 2026-07-09 15:03:46 +05:30
.gitignore Initial Commit 2026-07-09 15:03:46 +05:30
AGENTS.md Initial Commit 2026-07-09 15:03:46 +05:30
biome.json Initial Commit 2026-07-09 15:03:46 +05:30
bun.lock Initial Commit 2026-07-09 15:03:46 +05:30
bunfig.toml Initial Commit 2026-07-09 15:03:46 +05:30
CHANGELOG.md Initial Commit 2026-07-09 15:03:46 +05:30
docker-compose.yml Initial Commit 2026-07-09 15:03:46 +05:30
Dockerfile Initial Commit 2026-07-09 15:03:46 +05:30
OVERVIEW.md Initial Commit 2026-07-09 15:03:46 +05:30
package.json Initial Commit 2026-07-09 15:03:46 +05:30
PLAN.md Initial Commit 2026-07-09 15:03:46 +05:30
README.md Initial Commit 2026-07-09 15:03:46 +05:30
tsconfig.json Initial Commit 2026-07-09 15:03:46 +05:30

context7-mcp

Semantic documentation indexer and retriever — an MCP server and CLI tool that ingests code repositories, chunks documentation semantically, embeds it, and exposes hybrid search (BM25 + vector + RRF) to LLM agents via the Model Context Protocol.

Quick Start

bun install && bun run migrate    # Install deps + create Redis indexes
bun run dev                        # Start MCP server (stdio)

Then in another terminal:

ctx7 index https://github.com/vercel/next.js  # Index a library
ctx7 docs /vercel/next.js "how to use server actions"  # Search

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Host (Claude, etc.)                  │
└───────────────────────────────┬─────────────────────────────────┘
                                │ JSON-RPC 2.0 over stdio / SSE
┌───────────────────────────────▼─────────────────────────────────┐
│                      MCP Server (Bun runtime)                    │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────────┐  │
│  │ Tool Handler │  │   Indexer    │  │  Embedding Provider   │  │
│  │  (resolve-   │  │ (git clone,  │  │  (OpenAI, Ollama,    │  │
│  │   library-id,│  │  parse,      │  │   Voyage, TEI, Jina) │  │
│  │  query-docs) │  │  chunk,      │  │                       │  │
│  │              │  │  embed,      │  │                       │  │
│  │              │  │  store)      │  │                       │  │
│  └──────┬──────┘  └──────┬───────┘  └───────────┬───────────┘  │
│         │                │                      │               │
│  ┌──────▼────────────────▼──────────────────────▼───────────┐  │
│  │                  Redis Stack (FT + Vector)                │  │
│  │  • HASH/JSON storage    • BM25 full-text                 │  │
│  │  • HNSW vector index    • FT.SEARCH hybrid queries       │  │
│  │  • Prefix-based keys    • AOF + RDB persistence          │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Prerequisites

  • Bun >= 1.2 (install)
  • Docker (for Redis Stack, or have a Redis Stack server running)
  • Git (for cloning repositories to index)

Installation

git clone https://github.com/anomalyco/context7.git
cd context7
bun install --frozen-lockfile

Start Redis

docker compose up -d          # Starts Redis Stack on port 6379

Create Indexes

bun run migrate               # Creates FT indexes in Redis

Start the Server

bun run dev                   # Starts MCP server on stdio transport

Configuration

All configuration is via environment variables, validated by Zod at startup.

Variable Default Description
REDIS_URL redis://localhost:6379 Redis connection string
EMBEDDING_PROVIDER fake One of: openai, ollama, fake
EMBEDDING_API_KEY — API key for your embedding provider
EMBEDDING_MODEL provider default Model name (e.g., text-embedding-3-small)
EMBEDDING_DIMENSIONS 384 Vector dimensions (must match model)
OLLAMA_BASE_URL http://localhost:11434/v1 Ollama endpoint URL
LOG_LEVEL info One of: trace, debug, info, warn, error, fatal
LOG_PRETTY true Pretty-print logs in dev (set false for JSON)
MAX_CHUNK_TOKENS 512 Maximum tokens per documentation chunk
MCP_PORT 3000 HTTP transport port (not used in stdio mode)
MCP_TRANSPORT stdio One of: stdio, http
RATE_LIMIT_MAX 60 Max requests per client per window
RATE_LIMIT_WINDOW_MS 60000 Rate limit window in milliseconds
INDEX_BATCH_SIZE 32 Documents to process per batch during indexing
GIT_CLONE_DEPTH 1 Shallow clone depth (1 = latest commit only)
RETRY_MAX_ATTEMPTS 3 Max retries for transient failures
RETRY_BASE_DELAY_MS 2000 Base delay for exponential backoff
SENTRY_DSN — Optional Sentry DSN for error tracking

MCP Client Setup

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "context7": {
      "command": "bun",
      "args": ["run", "/path/to/context7/src/main.ts"],
      "env": {
        "REDIS_URL": "redis://localhost:6379",
        "EMBEDDING_PROVIDER": "fake"
      }
    }
  }
}

Claude Code

claude mcp add context7 -- \
  bun run /path/to/context7/src/main.ts

Then set environment variables as needed (e.g., REDIS_URL).

CLI Usage

# Search for indexed libraries
ctx7 library "next.js"
ctx7 library "react" --json

# Search documentation
ctx7 docs /vercel/next.js "how to use server actions"
ctx7 docs /vercel/next.js "data fetching" --topk 5 --json

# Index a repository
ctx7 index https://github.com/vercel/next.js my-nextjs

# Check indexing status
ctx7 status
ctx7 status /vercel/next.js

Docker

Build

docker build -t context7-mcp .

Run

docker run --rm -it \
  -e REDIS_URL=redis://host.docker.internal:6379 \
  -e EMBEDDING_PROVIDER=ollama \
  context7-mcp

Docker Compose (full stack)

docker compose up -d

This starts Redis Stack (port 6379) and RedisInsight (port 8001). The MCP server runs outside the container for interactive stdio — use docker compose for the data layer and run the server directly.

Development

# Install dependencies
bun install

# Run linting
bun run lint

# Type-check
bun run type-check

# Run unit tests
bun run test

# Run integration tests (requires Redis)
bun run test:integration

# Run all tests
bun run test:all

# Full check (lint + type-check + test)
bun run check

Biome

This project uses Biome for linting and formatting. Configuration is in biome.json. Key rules:

  • No semicolons
  • Single quotes
  • Trailing commas in multiline
  • 100 character line width

Project Structure

src/
├── main.ts              # MCP server entry point
├── cli.ts               # CLI entry point
├── config/              # Zod-validated configuration
├── core/
│   ├── chunker/         # Semantic chunking strategies
│   ├── parser/          # Markdown/MDX → AST
│   ├── embedder/        # Embedding provider adapters
│   ├── indexer/         # Git ingestion pipeline
│   └── retriever/       # Hybrid search + RRF
├── mcp/
│   ├── server.ts        # MCP server setup
│   ├── tools/           # Tool implementations
│   ├── resources.ts     # Library metadata resources
│   └── prompts.ts       # System prompt templates
├── infra/
│   ├── redis/           # Client factory, repositories
│   ├── git/             # Clone, diff, file scanning
│   ├── rate-limiter.ts  # Token-bucket rate limiting
│   ├── retry.ts         # Exponential backoff
│   └── logger.ts        # Pino logger
└── types/               # Shared domain types

Scripts

Script Description
bun run dev Start MCP server (stdio)
bun run cli Run CLI (ctx7)
bun run lint Lint and auto-fix source files
bun run type-check TypeScript type checking
bun run test Unit tests
bun run test:integration Integration tests (requires Redis)
bun run check Full quality check
bun run bench Performance benchmarks
bun run migrate Create Redis FT indexes
bun run seed Seed index with sample data

License

MIT