Skip to content

Commit 3fb0412

Browse files
author
DeepWiki Dev
committed
docs: describe the local-first Context7 fork
Replace the upstream marketing-oriented landing page with concise documentation for this repository's quota-free local MCP server. Document automatic library indexing and refresh, durable local storage, Codex/VS Code/OpenCode configuration, maintenance commands, local retrieval, and the security boundary. Remove hosted API-key, OAuth, telemetry, badges, and service instructions that do not apply to this fork. Validated the README with Prettier and checked the patch for whitespace errors.
1 parent bd1167c commit 3fb0412

1 file changed

Lines changed: 116 additions & 130 deletions

File tree

‎README.md‎

Lines changed: 116 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -1,174 +1,160 @@
1-
![Cover](https://github.com/upstash/context7/blob/master/public/cover.png?raw=true)
1+
# Context7 Local
22

3-
[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D)
3+
A local-first, Context7-compatible MCP server for current library documentation.
44

5-
# Context7 Platform - Up-to-date Code Docs For Any Prompt
5+
It keeps documentation indexes on your machine, builds missing libraries automatically, and refreshes stale libraries from their public GitHub repositories. It does not use the hosted Context7 API, so there are no Context7 API keys, quotas, or rate limits.
66

7-
> [!IMPORTANT]
8-
> This checkout is a quota-free local-first fork. It serves commit-pinned SQLite
9-
> indexes from `C:\Apps\System\Context7\index`, performs no Context7 telemetry or
10-
> hosted authentication, and automatically builds or refreshes missing libraries.
11-
> See [the MCP local-first guide](packages/mcp/README.md#local-first-index).
7+
## What it does
128

13-
[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [![NPM Version](https://img.shields.io/npm/v/%40upstash%2Fcontext7-mcp?color=red)](https://www.npmjs.com/package/@upstash/context7-mcp) [![MIT licensed](https://img.shields.io/npm/l/%40upstash%2Fcontext7-mcp)](./LICENSE)
9+
- Supports the standard `resolve-library-id` and `query-docs` workflow.
10+
- Discovers and indexes a missing public GitHub library during the first request.
11+
- Stores each index with the exact source commit and refreshes it every 24 hours by default.
12+
- Publishes rebuilt indexes atomically so existing documentation remains available during updates.
13+
- Uses local SQLite full-text search, rank fusion, and optional local Ollama embeddings.
14+
- Includes a catalog for prebuilding 1,000 commonly queried libraries.
15+
- Sends no Context7 telemetry and has no hosted authentication path.
1416

15-
[![繁體中文](https://img.shields.io/badge/docs-繁體中文-yellow)](./i18n/README.zh-TW.md) [![简体中文](https://img.shields.io/badge/docs-简体中文-yellow)](./i18n/README.zh-CN.md) [![日本語](https://img.shields.io/badge/docs-日本語-b7003a)](./i18n/README.ja.md) [![한국어 문서](https://img.shields.io/badge/docs-한국어-green)](./i18n/README.ko.md) [![Documentación en Español](https://img.shields.io/badge/docs-Español-orange)](./i18n/README.es.md) [![Documentation en Français](https://img.shields.io/badge/docs-Français-blue)](./i18n/README.fr.md) [![Documentação em Português (Brasil)](<https://img.shields.io/badge/docs-Português%20(Brasil)-purple>)](./i18n/README.pt-BR.md) [![Documentazione in italiano](https://img.shields.io/badge/docs-Italian-red)](./i18n/README.it.md) [![Dokumentasi Bahasa Indonesia](https://img.shields.io/badge/docs-Bahasa%20Indonesia-pink)](./i18n/README.id-ID.md) [![Dokumentation auf Deutsch](https://img.shields.io/badge/docs-Deutsch-darkgreen)](./i18n/README.de.md) [![Документация на русском языке](https://img.shields.io/badge/docs-Русский-darkblue)](./i18n/README.ru.md) [![Українська документація](https://img.shields.io/badge/docs-Українська-lightblue)](./i18n/README.uk.md) [![Türkçe Doküman](https://img.shields.io/badge/docs-Türkçe-blue)](./i18n/README.tr.md) [![Arabic Documentation](https://img.shields.io/badge/docs-Arabic-white)](./i18n/README.ar.md) [![Tiếng Việt](https://img.shields.io/badge/docs-Tiếng%20Việt-red)](./i18n/README.vi.md)
17+
On Windows, indexes are stored in `C:\Apps\System\Context7\index` by default. On other platforms, the default is `~/.cache/context7-local`.
1618

17-
## ❌ Without Context7
19+
## Requirements
1820

19-
LLMs rely on outdated or generic information about the libraries you use. You get:
21+
- Node.js 22.12 or newer
22+
- pnpm
23+
- Git
24+
- Optional: Ollama with `qwen3-embedding:0.6b` for local semantic reranking
2025

21-
- ❌ Code examples are outdated and based on year-old training data
22-
- ❌ Hallucinated APIs that don't even exist
23-
- ❌ Generic answers for old package versions
26+
## Build
2427

25-
## ✅ With Context7
26-
27-
Context7 pulls up-to-date, version-specific documentation and code examples straight from the source — and places them directly into your prompt.
28-
29-
```txt
30-
Create a Next.js middleware that checks for a valid JWT in cookies
31-
and redirects unauthenticated users to `/login`. use context7
28+
```powershell
29+
git clone https://github.com/sm18lr88/context7-local.git
30+
cd context7-local
31+
pnpm install --frozen-lockfile
32+
pnpm --filter @upstash/context7-mcp build
3233
```
3334

34-
```txt
35-
Configure a Cloudflare Worker script to cache
36-
JSON API responses for five minutes. use context7
37-
```
35+
Run the MCP server over stdio:
3836

39-
```txt
40-
Show me the Supabase auth API for email/password sign-up.
37+
```powershell
38+
node packages/mcp/dist/index.js --transport stdio
4139
```
4240

43-
Context7 fetches up-to-date code examples and documentation right into your LLM's context. No tab-switching, no hallucinated APIs that don't exist, no outdated code generation.
41+
## MCP configuration
4442

45-
Works in two modes:
43+
Replace the path below if you cloned the repository somewhere else.
4644

47-
- **CLI + Skills** — installs a skill that guides your agent to fetch docs using `ctx7` CLI commands (no MCP required)
48-
- **MCP** — registers a Context7 MCP server so your agent can call documentation tools natively
45+
Codex, in `~/.codex/config.toml`:
4946

50-
## Installation
47+
```toml
48+
[mcp_servers.context7]
49+
command = "node"
50+
args = [
51+
"D:\\Apps\\LLM\\context7-local\\packages\\mcp\\dist\\index.js",
52+
"--transport",
53+
"stdio"
54+
]
5155

52-
> [!NOTE]
53-
> **API Key Recommended**: Get a free API key at [context7.com/dashboard](https://context7.com/dashboard) for higher rate limits.
54-
55-
Set up Context7 for your coding agents with a single command. The `ctx7` CLI requires Node.js 18 or newer.
56-
57-
```bash
58-
npx ctx7 setup
56+
[mcp_servers.context7.env]
57+
CONTEXT7_LOCAL_STORAGE_DIR = "C:\\Apps\\System\\Context7\\index"
5958
```
6059

61-
Authenticates via OAuth, generates an API key, and installs the appropriate skill. You can choose between CLI + Skills or MCP mode. Use `--cursor`, `--claude`, or `--opencode` to target a specific agent.
62-
63-
To remove the generated setup later, run `npx ctx7 remove`. If you globally installed the CLI with `npm install -g ctx7`, remove that package separately with `npm uninstall -g ctx7`.
64-
65-
To configure manually, use the Context7 server URL `https://mcp.context7.com/mcp` with your MCP client and pass your API key via the `CONTEXT7_API_KEY` header. See the link below for client-specific setup instructions.
66-
67-
**[Manual Installation / Other Clients →](https://context7.com/docs/resources/all-clients)**
68-
69-
## Important Tips
70-
71-
### Use Library Id
72-
73-
If you already know exactly which library you want to use, add its Context7 ID to your prompt. That way, Context7 can skip the library-matching step and directly retrieve docs.
74-
75-
```txt
76-
Implement basic authentication with Supabase. use library /supabase/supabase for API and docs.
60+
VS Code, in the user or workspace `mcp.json`:
61+
62+
```json
63+
{
64+
"servers": {
65+
"context7": {
66+
"type": "stdio",
67+
"command": "node",
68+
"args": [
69+
"D:\\Apps\\LLM\\context7-local\\packages\\mcp\\dist\\index.js",
70+
"--transport",
71+
"stdio"
72+
],
73+
"env": {
74+
"CONTEXT7_LOCAL_STORAGE_DIR": "C:\\Apps\\System\\Context7\\index"
75+
}
76+
}
77+
}
78+
}
7779
```
7880

79-
The slash syntax tells Context7 exactly which library to load docs for.
80-
81-
### Specify a Version
82-
83-
To get documentation for a specific library version, just mention the version in your prompt:
84-
85-
```txt
86-
How do I set up Next.js 14 middleware? use context7
81+
OpenCode, in `~/.config/opencode/opencode.json`:
82+
83+
```json
84+
{
85+
"mcp": {
86+
"context7": {
87+
"type": "local",
88+
"command": [
89+
"node",
90+
"D:\\Apps\\LLM\\context7-local\\packages\\mcp\\dist\\index.js",
91+
"--transport",
92+
"stdio"
93+
],
94+
"environment": {
95+
"CONTEXT7_LOCAL_STORAGE_DIR": "C:\\Apps\\System\\Context7\\index"
96+
},
97+
"enabled": true
98+
}
99+
}
100+
}
87101
```
88102

89-
Context7 will automatically match the appropriate version.
103+
Restart or reload clients that were already running when their configuration changed.
90104

91-
### Add a Rule
105+
## Tools
92106

93-
If you installed via `ctx7 setup`, a skill is configured automatically that triggers Context7 for library-related questions. To set up a rule manually instead, add one to your coding agent:
107+
- `resolve-library-id`: finds a Context7-compatible library ID.
108+
- `query-docs`: returns answer-ready documentation and builds the library first when needed.
109+
- `search-docs`: returns ranked previews with commit-bound result keys.
110+
- `read-docs`: reads a selected result with adjacent sections.
111+
- `grep-docs`: searches locally for an exact API name, option, or error.
112+
- `local-index-status`: reports freshness, migration, prewarm, and semantic-cache state.
113+
- `refresh-local-index`: refreshes a library to its current upstream commit.
94114

95-
- **Cursor**: `Cursor Settings > Rules`
96-
- **Claude Code**: `CLAUDE.md`
97-
- Or the equivalent in your coding agent
115+
## Index maintenance
98116

99-
**Example rule:**
117+
Prebuild the common-library catalog:
100118

101-
```txt
102-
Always use Context7 when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask.
119+
```powershell
120+
node packages/mcp/dist/prewarm.js --target 1000 --candidates 1600 --concurrency 2
103121
```
104122

105-
## Available Tools
106-
107-
### CLI Commands
108-
109-
- `ctx7 library <name> <query>`: Searches the Context7 index by library name and returns matching libraries with their IDs.
110-
- `ctx7 docs <libraryId> <query>`: Retrieves documentation for a library using a Context7-compatible library ID (e.g., `/mongodb/docs`, `/vercel/next.js`).
111-
112-
### MCP Tools
123+
Upgrade existing indexes after a parser change:
113124

114-
- `resolve-library-id`: Resolves a general library name into a Context7-compatible library ID.
115-
- `query` (required): The user's question or task (used to rank results by relevance)
116-
- `libraryName` (required): The name of the library to search for
117-
- `query-docs`: Retrieves documentation for a library using a Context7-compatible library ID.
118-
- `libraryId` (required): Exact Context7-compatible library ID (e.g., `/mongodb/docs`, `/vercel/next.js`)
119-
- `query` (required): The question or task to get relevant documentation for
120-
- `search-docs`: Returns concise fused/hybrid results with commit-bound keys.
121-
- `read-docs`: Reads one result with adjacent document sections.
122-
- `grep-docs`: Finds exact API names, options, and error fragments locally.
123-
- `local-index-status`: Reports freshness, parser migration, prewarm, and semantic-cache state.
124-
- `refresh-local-index`: Atomically refreshes one library to its current upstream commit.
125-
126-
## More Documentation
127-
128-
- [CLI Reference](https://context7.com/docs/clients/cli) - Full CLI documentation
129-
- [MCP Clients](https://context7.com/docs/resources/all-clients) - Manual MCP installation for 30+ clients
130-
- [Adding Libraries](https://context7.com/docs/adding-libraries) - Submit your library to Context7
131-
- [Troubleshooting](https://context7.com/docs/resources/troubleshooting) - Common issues and solutions
132-
- [API Reference](https://context7.com/docs/api-guide) - REST API documentation
133-
- [Developer Guide](https://context7.com/docs/resources/developer) - Run Context7 MCP locally
134-
135-
## Packages
136-
137-
- [`@upstash/context7-mcp`](https://www.npmjs.com/package/@upstash/context7-mcp) - MCP server
138-
- [`ctx7`](https://www.npmjs.com/package/ctx7) - CLI
139-
- [`@upstash/context7-sdk`](https://www.npmjs.com/package/@upstash/context7-sdk) - TypeScript SDK
140-
- [`@upstash/context7-tools-ai-sdk`](https://www.npmjs.com/package/@upstash/context7-tools-ai-sdk) - Vercel AI SDK tools
141-
- [`@upstash/context7-pi`](https://www.npmjs.com/package/@upstash/context7-pi) - pi.dev extension
125+
```powershell
126+
node packages/mcp/dist/migrate-index.js --concurrency 2
127+
```
142128

143-
## Disclaimer
129+
Run the retrieval regression suite:
144130

145-
1- Context7 projects are community-contributed and while we strive to maintain high quality, we cannot guarantee the accuracy, completeness, or security of all library documentation. Projects listed in Context7 are developed and maintained by their respective owners, not by Context7. If you encounter any suspicious, inappropriate, or potentially harmful content, please use the "Report" button on the project page to notify us immediately. We take all reports seriously and will review flagged content promptly to maintain the integrity and safety of our platform. By using Context7, you acknowledge that you do so at your own discretion and risk.
131+
```powershell
132+
node packages/mcp/dist/evaluate-retrieval.js
133+
```
146134

147-
2- This repository hosts the MCP server’s source code. The supporting components — API backend, parsing engine, and crawling engine — are private and not part of this repository.
135+
Progress and evaluation history are kept inside the index directory, so interrupted jobs can resume and retrieval changes can be compared over time.
148136

149-
## 🤝 Connect with Us
137+
## Configuration
150138

151-
Stay updated and join our community:
139+
The most useful environment variables are:
152140

153-
- 📢 Follow us on [X](https://x.com/context7ai) for the latest news and updates
154-
- 🌐 Visit our [Website](https://context7.com)
155-
- 💬 Join our [Discord Community](https://upstash.com/discord)
141+
| Variable | Default | Purpose |
142+
| ------------------------------ | ----------------------------- | -------------------------------------------------- |
143+
| `CONTEXT7_LOCAL_STORAGE_DIR` | Platform-specific local cache | Index location |
144+
| `CONTEXT7_REFRESH_INTERVAL_MS` | `86400000` | Upstream freshness-check interval |
145+
| `CONTEXT7_LOCAL_EMBEDDINGS` | Enabled | Set to `off` for lexical retrieval only |
146+
| `CONTEXT7_EMBEDDING_MODEL` | `qwen3-embedding:0.6b` | Local Ollama embedding model |
147+
| `CONTEXT7_EMBEDDING_BASE_URL` | `http://127.0.0.1:11434` | Local Ollama endpoint |
148+
| `GITHUB_TOKEN` or `GH_TOKEN` | Unset | Optional GitHub search and metadata authentication |
156149

157-
## 📺 Context7 In Media
150+
All limits and architecture details are documented in [packages/mcp/README.md](packages/mcp/README.md) and [packages/mcp/LOCAL_ARCHITECTURE.md](packages/mcp/LOCAL_ARCHITECTURE.md).
158151

159-
- [Better Stack: "Free Tool Makes Cursor 10x Smarter"](https://youtu.be/52FC3qObp9E)
160-
- [Cole Medin: "This is Hands Down the BEST MCP Server for AI Coding Assistants"](https://www.youtube.com/watch?v=G7gK8H6u7Rs)
161-
- [Income Stream Surfers: "Context7 + SequentialThinking MCPs: Is This AGI?"](https://www.youtube.com/watch?v=-ggvzyLpK6o)
162-
- [Julian Goldie SEO: "Context7: New MCP AI Agent Update"](https://www.youtube.com/watch?v=CTZm6fBYisc)
163-
- [JeredBlu: "Context 7 MCP: Get Documentation Instantly + VS Code Setup"](https://www.youtube.com/watch?v=-ls0D-rtET4)
164-
- [Income Stream Surfers: "Context7: The New MCP Server That Will CHANGE AI Coding"](https://www.youtube.com/watch?v=PS-2Azb-C3M)
165-
- [AICodeKing: "Context7 + Cline & RooCode: This MCP Server Makes CLINE 100X MORE EFFECTIVE!"](https://www.youtube.com/watch?v=qZfENAPMnyo)
166-
- [Sean Kochel: "5 MCP Servers For Vibe Coding Glory (Just Plug-In & Go)"](https://www.youtube.com/watch?v=LqTQi8qexJM)
152+
## Security
167153

168-
## ⭐ Star History
154+
Repository documentation is treated as untrusted input. Agent-instruction files are excluded, file and response sizes are bounded, Git hooks and filters are disabled, and returned source links are pinned to the indexed commit.
169155

170-
[![Star History Chart](https://api.star-history.com/svg?repos=upstash/context7&type=Date)](https://www.star-history.com/#upstash/context7&Date)
156+
HTTP transport binds to loopback by default. Use an authenticated reverse proxy or SSH tunnel if another machine needs access.
171157

172-
## 📄 License
158+
## License
173159

174-
MIT
160+
MIT. This project is based on [Upstash Context7](https://github.com/upstash/context7).

0 commit comments

Comments
 (0)