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%
|
History
|
||
|---|---|---|
| .github/workflows | ||
| scripts | ||
| src | ||
| tests | ||
| .gitignore | ||
| AGENTS.md | ||
| biome.json | ||
| bun.lock | ||
| bunfig.toml | ||
| CHANGELOG.md | ||
| docker-compose.yml | ||
| Dockerfile | ||
| OVERVIEW.md | ||
| package.json | ||
| PLAN.md | ||
| README.md | ||
| tsconfig.json | ||
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