alihan/claude-context-mcp
1
0
Fork 0
mirror of https://github.com/zilliztech/claude-context.git synced 2025-10-06 01:10:02 +03:00
Code Issues Packages Projects Releases Wiki Activity

Add and optimize docs

Browse Source 
Signed-off-by: ChengZi <chen.zhang@zilliz.com>
This commit is contained in:
ChengZi
2025-08-21 20:59:54 +08:00
committed by Cheney Zhang
parent c21b62c17e
commit 643796a0d3
16 changed files with 509 additions and 266 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.env.example
View File

@@ -1,8 +1,10 @@
# Claude Context Environment Variables Example
#
# Copy this file to ~/.context/.env and modify the values as needed
# Copy this file to ~/.context/.env as a global setting, modify the values as needed
#
# Usage: cp env.example ~/.context/.env
#
# Note: This file does not work if you put it in your codebase directory (because it may conflict with the environment variables of your codebase project)
# =============================================================================
# Embedding Provider Configuration

6
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@@ -10,6 +10,9 @@ assignees: ''
**Describe the bug**
Please describe your problem in **English**
**Troubleshooting Guide**
Try to follow the [Troubleshooting Guide](https://github.com/zilliztech/claude-context/blob/main/docs/troubleshooting/troubleshooting-guide.md) to solve the problem. If you can not solve the problem, please open an issue.
## For MCP Use Cases
**Get your MCP logs first**
- If you use Claude Code or Gemini CLI, you can start them with `--debug` mode, e.g.,`claude --debug` or `gemini --debug` to get the detailed MCP logs.
@@ -30,6 +33,9 @@ Try to locate the issue and provide more detailed setting information.
## Other Information
**Whether you can reproduce the error**
Try to see if the results of reproduced errors are the same every time.
**Screenshots**
If applicable, add screenshots to help explain your problem.

80
README.md
View File

@@ -60,14 +60,17 @@ Copy your key and use it in the configuration examples below as `your-openai-api
Use the command line interface to add the Claude Context MCP server:
```bash
# Add the Claude Context MCP server
claude mcp add claude-context -e OPENAI_API_KEY=your-openai-api-key -e MILVUS_TOKEN=your-zilliz-cloud-api-key -- npx @zilliz/claude-context-mcp@latest
claude mcp add claude-context \
-e OPENAI_API_KEY=sk-your-openai-api-key \
-e MILVUS_TOKEN=your-zilliz-cloud-api-key \
-- npx @zilliz/claude-context-mcp@latest
```
See the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for more details about MCP server management.
### Other MCP Client Configurations (Gemini CLI, Cursor, Windsurf, etc.)
### Other MCP Client Configurations
<details>
<summary><strong>Gemini CLI</strong></summary>
@@ -412,11 +415,55 @@ npx @zilliz/claude-context-mcp@latest
</details>
---
**How to configure environment variables for MCP:** For more detailed MCP environment variable configuration, see our [Environment Variables Guide](docs/getting-started/environment-variables.md).
### Usage in Your Codebase
**Using Different Embedding Models with MCP:** To configure specific embedding models (e.g., `text-embedding-3-large` for OpenAI, `voyage-code-3` for VoyageAI), see the [MCP Configuration Examples](packages/mcp/README.md#embedding-provider-configuration) for detailed setup instructions for each provider.
1. **Open Claude Code**
```
cd your-project-directory
claude
```
2. **Index your codebase**:
```
Index this codebase
```
3. **Check indexing status**:
```
Check the indexing status
```
4. **Start searching**:
```
Find functions that handle user authentication
```
📚 **Need more help?** Check out our [complete documentation](docs/) for detailed guides and troubleshooting tips.
🎉 **That's it!** You now have semantic code search in Claude Code.
---
### Environment Variables Configuration
For more detailed MCP environment variable configuration, see our [Environment Variables Guide](docs/getting-started/environment-variables.md).
### Using Different Embedding Models
To configure custom embedding models (e.g., `text-embedding-3-large` for OpenAI, `voyage-code-3` for VoyageAI), see the [MCP Configuration Examples](packages/mcp/README.md#embedding-provider-configuration) for detailed setup instructions for each provider.
### File Inclusion & Exclusion Rules
For detailed explanation of file inclusion and exclusion rules, and how to customize them, see our [File Inclusion & Exclusion Rules](docs/dive-deep/file-inclusion-rules.md).
### Available Tools
#### 1. `index_codebase`
Index a codebase directory for hybrid search (BM25 + dense vector).
#### 2. `search_code`
Search the indexed codebase using natural language queries with hybrid search (BM25 + dense vector).
#### 3. `clear_index`
Clear the search index for a specific codebase.
#### 4. `get_indexing_status`
Get the current indexing status of a codebase. Shows progress percentage for actively indexing codebases and completion status for indexed codebases.
---
@@ -545,25 +592,6 @@ cd examples/basic-usage
pnpm dev
```
### Supported File Extensions
By default, Claude Context supports:
- Programming languages: `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.java`, `.cpp`, `.c`, `.h`, `.hpp`, `.cs`, `.go`, `.rs`, `.php`, `.rb`, `.swift`, `.kt`, `.scala`, `.m`, `.mm`
- Documentation: `.md`, `.markdown`, `.ipynb`
### Ignore Patterns
Common directories and files are automatically ignored:
- Build outputs: `node_modules/**`, `dist/**`, `build/**`, `out/**`, `target/**`, `coverage/**`, `.nyc_output/**`
- Version control: `.git/**`, `.svn/**`, `.hg/**`
- IDE/Editor files: `.vscode/**`, `.idea/**`, `*.swp`, `*.swo`
- Cache directories: `.cache/**`, `__pycache__/**`, `.pytest_cache/**`
- Logs and temporary: `logs/**`, `tmp/**`, `temp/**`, `*.log`
- Environment files: `.env`, `.env.*`, `*.local`
- Minified/bundled files: `*.min.js`, `*.min.css`, `*.bundle.js`, `*.bundle.css`, `*.chunk.js`, `*.map`
See [FAQ Guide](docs/troubleshooting/faq.md) for detailed and customized configuration of supported file extensions and ignore patterns.
---
## 📖 Examples
@@ -594,6 +622,8 @@ For detailed evaluation methodology and results, see the [evaluation directory](
For detailed answers and more troubleshooting tips, see our [FAQ Guide](docs/troubleshooting/faq.md).
📚 **Need more help?** Check out our [complete documentation](docs/) for detailed guides and troubleshooting tips.
---
## 🤝 Contributing

BIN
assets/docs/file-inclusion-flow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 360 KiB

BIN
assets/docs/indexing-flow-diagram.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 133 KiB

BIN
assets/docs/indexing-sequence-diagram.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 180 KiB

7
docs/README.md
View File

@@ -6,8 +6,8 @@ Welcome to the Claude Context documentation! Claude Context is a powerful tool t
## 🚀 Quick Navigation
### Getting Started
- [📋 Project Overview](getting-started/overview.md) - What is Claude Context and how it works
- [🛠️ Prerequisites](getting-started/prerequisites.md) - What you need before starting
- [🔍 Environment Variables](getting-started/environment-variables.md) - How to configure environment variables for MCP
- [⚡ Quick Start Guide](getting-started/quick-start.md) - Get up and running in 1 minutes
@@ -16,8 +16,13 @@ Welcome to the Claude Context documentation! Claude Context is a powerful tool t
- [VSCode Extension](../packages/vscode-extension/README.md) - The VSCode extension of Claude Context
- [Core Package](../packages/core/README.md) - The core package of Claude Context
### Dive Deep
- [File Inclusion & Exclusion Rules](dive-deep/file-inclusion-rules.md) - Detailed explanation of file inclusion and exclusion rules
- [Asynchronous Indexing Workflow](dive-deep/asynchronous-indexing-workflow.md) - Detailed explanation of asynchronous indexing workflow
### Troubleshooting
- [❓ FAQ](troubleshooting/faq.md) - Frequently asked questions
- [🐛 Troubleshooting Guide](troubleshooting/troubleshooting-guide.md) - Troubleshooting guide
## 🔗 External Resources

44
docs/dive-deep/asynchronous-indexing-workflow.md Normal file
View File

@@ -0,0 +1,44 @@
# Asynchronous Indexing Workflow
This document explains how Claude Context MCP handles codebase indexing asynchronously in the background.
## Core Concept
Claude Context MCP server allows users to start indexing and get an immediate response, while the actual indexing happens in the background. Users can search and monitor progress at any time.
## How It Works
![Sequence Diagram](../../assets/docs/indexing-sequence-diagram.png)
The sequence diagram above demonstrates the timing and interaction between the agent, MCP server, and background process.
The agent receives an immediate response when starting indexing, then the users can perform searches and status checks through the agent while indexing continues in the background.
## State Flow
![Indexing Flow Diagram](../../assets/docs/indexing-flow-diagram.png)
The flow diagram above shows the complete indexing workflow, illustrating how the system handles different states and user interactions. The key insight is that indexing starts immediately but runs in the background, allowing users to interact with the system at any time.
## MCP Tools
- **`index_codebase`** - Starts background indexing, returns immediately
- **`search_code`** - Searches codebase (works during indexing with partial results)
- **`get_indexing_status`** - Shows current progress and status
- **`clear_index`** - Removes indexed data
## Status States
- **`indexed`** - ✅ Ready for search
- **`indexing`** - 🔄 Background process running
- **`indexfailed`** - ❌ Error occurred, can retry
- **`not_found`** - ❌ Not indexed yet
## Key Benefits
- **Non-blocking**: Agent gets immediate response
- **Progressive**: Can search partial results while indexing
- **Resilient**: Handles errors gracefully with retry capability
- **Transparent**: Always know current status

102
docs/dive-deep/file-inclusion-rules.md Normal file
View File

@@ -0,0 +1,102 @@
# File Inclusion & Exclusion Rules
This document explains how Claude Context determines which files to include in the indexing process and which files to exclude.
## Overview
Claude Context uses a comprehensive rule system that combines multiple sources of file extensions and ignore patterns to determine what gets indexed.
## The Core Rule
```
Final Files = (All Supported Extensions) - (All Ignore Patterns)
```
Where:
- **All Supported Extensions** = Default + MCP Custom + Environment Variable Extensions
- **All Ignore Patterns** = Default + MCP Custom + Environment Variable + .gitignore + .xxxignore + Global .contextignore
## File Inclusion Flow
![File Inclusion Flow](../../assets/docs/file-inclusion-flow.png)
The diagram above shows how different sources contribute to the final file selection process.
## Extension Sources (Additive)
All extension sources are combined together:
### 1. Default Extensions
Built-in supported file extensions including:
- Programming languages: `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.java`, `.cpp`, `.c`, `.h`, `.hpp`, `.cs`, `.go`, `.rs`, `.php`, `.rb`, `.swift`, `.kt`, `.scala`, `.m`, `.mm`
- Documentation: `.md`, `.markdown`, `.ipynb`
For more details, see [DEFAULT_SUPPORTED_EXTENSIONS](../../packages/core/src/context.ts) in the context.ts file.
### 2. MCP Custom Extensions
Additional extensions passed dynamically via MCP `customExtensions` parameter:
```json
{
"customExtensions": [".vue", ".svelte", ".astro"]
}
```
Just dynamically tell the agent what extensions you want to index to invoke this parameter. For example:
```
"Index this codebase, and include .vue, .svelte, .astro files"
```
### 3. Environment Variable Extensions
Extensions from `CUSTOM_EXTENSIONS` environment variable:
```bash
export CUSTOM_EXTENSIONS=".vue,.svelte,.astro"
```
See [Environment Variables](../getting-started/environment-variables.md) for more details about how to set environment variables.
## Ignore Pattern Sources (Additive)
All ignore pattern sources are combined together:
### 1. Default Ignore Patterns
Built-in patterns for common files/directories to exclude:
- **Build outputs**: `node_modules/**`, `dist/**`, `build/**`, `out/**`, `target/**`, `coverage/**`, `.nyc_output/**`
- **IDE files**: `.vscode/**`, `.idea/**`, `*.swp`, `*.swo`
- **Version control**: `.git/**`, `.svn/**`, `.hg/**`
- **Cache directories**: `.cache/**`, `__pycache__/**`, `.pytest_cache/**`
- **Logs and temporary**: `logs/**`, `tmp/**`, `temp/**`, `*.log`
- **Environment files**: `.env`, `.env.*`, `*.local`
- **Minified files**: `*.min.js`, `*.min.css`, `*.min.map`, `*.bundle.js`, `*.bundle.css`, `*.chunk.js`, `*.vendor.js`, `*.polyfills.js`, `*.runtime.js`, `*.map`
For more details, see [DEFAULT_IGNORE_PATTERNS](../../packages/core/src/context.ts) in the context.ts file.
### 2. MCP Custom Ignore Patterns
Additional patterns passed dynamically via MCP `ignorePatterns` parameter:
```json
{
"ignorePatterns": ["temp/**", "*.backup", "private/**"]
}
```
Just dynamically tell the agent what patterns you want to exclude to invoke this parameter. For example:
```
"Index this codebase, and exclude temp/**, *.backup, private/** files"
```
### 3. Environment Variable Ignore Patterns
Patterns from `CUSTOM_IGNORE_PATTERNS` environment variable:
```bash
export CUSTOM_IGNORE_PATTERNS="temp/**,*.backup,private/**"
```
See [Environment Variables](../getting-started/environment-variables.md) for more details about how to set environment variables.
### 4. .gitignore Files
Standard Git ignore patterns in codebase root.
### 5. .xxxignore Files
Any file in codebase root matching pattern `.xxxignore`:
- `.cursorignore`
- `.codeiumignore`
- `.contextignore`
- etc.
### 6. Global .contextignore
User-wide patterns in `~/.context/.contextignore`.

2
docs/getting-started/environment-variables.md
View File

@@ -75,6 +75,8 @@ MILVUS_TOKEN=your-zilliz-cloud-api-key
EOF
```
See the [Example File](../../.env.example) for more details.
### 2. Simplified MCP Configuration
**Claude Code:**

114
docs/getting-started/overview.md
View File

@@ -1,114 +0,0 @@
# Project Overview
## What is Claude Context?
Claude Context is a powerful semantic code search tool that gives AI coding assistants deep understanding of your entire codebase. Instead of traditional keyword-based search, Claude Context uses vector embeddings and AI to understand the meaning and context of your code.
## Key Features
### 🔍 Hybrid Code Search
Ask natural language questions like "find functions that handle user authentication" and get relevant code snippets from across your entire codebase using advanced hybrid search (BM25 + dense vector).
### 🧠 Context-Aware Understanding
Discover relationships between different parts of your code, even across millions of lines. The system understands code structure, patterns, and dependencies.
### ⚡ Incremental Indexing
Efficiently re-index only changed files using Merkle trees, making it fast to keep your search index up-to-date.
### 🧩 Intelligent Code Chunking
Uses Abstract Syntax Trees (AST) to intelligently split code into meaningful chunks that preserve context and structure.
### 🗄️ Scalable Architecture
Integrates with Zilliz Cloud for scalable vector search, handling codebases of any size.
### 🛠️ Highly Customizable
Configure file extensions, ignore patterns, embedding models, and search parameters to fit your specific needs.
## How It Works
### 1. Code Analysis
Claude Context analyzes your codebase using AST parsers to understand code structure and semantics.
### 2. Intelligent Chunking
Code is split into meaningful chunks that preserve context, function boundaries, and logical groupings.
### 3. Vector Embeddings
Each code chunk is converted into high-dimensional vectors using state-of-the-art embedding models.
### 4. Vector Storage
Embeddings are stored in a vector database (Milvus/Zilliz Cloud) for efficient similarity search.
### 5. Hybrid Search
Natural language queries are processed using both dense vector embeddings and BM25 sparse retrieval, then combined with RRF (Reciprocal Rank Fusion) for optimal results.
## Architecture Components
### Core Engine (`@zilliz/claude-context-core`)
The foundational indexing engine that handles:
- Code parsing and analysis
- Embedding generation
- Vector database operations
- Search algorithms
### MCP Server (`@zilliz/claude-context-mcp`)
Model Context Protocol server that enables integration with AI assistants:
- Standardized tool interface
- Compatible with Claude Code, Cursor, Windsurf, and more
- Real-time indexing and search capabilities
### VSCode Extension
Native Visual Studio Code integration:
- Semantic search sidebar
- Context-aware code navigation
- Progressive indexing with visual feedback
### Chrome Extension
GitHub integration for web-based development:
- Semantic search on GitHub repositories
- Context-aware code browsing
- Cross-repository search capabilities
## Supported Technologies
### Programming Languages
- **Compiled Languages**: TypeScript, JavaScript, Java, C++, C#, Go, Rust
- **Scripting Languages**: Python, PHP, Ruby
- **Mobile**: Swift, Kotlin, Scala, Objective-C
- **Documentation**: Markdown
### Embedding Providers
- **OpenAI**: `text-embedding-3-small`, `text-embedding-3-large`
- **VoyageAI**: `voyage-code-3`, specialized for code understanding
- **Gemini**: Google's embedding models with Matryoshka representation
- **Ollama**: Local embedding models for privacy-focused development
### Vector Databases
- **Milvus**: Open-source vector database
- **Zilliz Cloud**: Fully managed vector database service
### AI Assistant Integration
- **Claude Code**: Native MCP integration
- **Cursor**: MCP configuration support
- **Windsurf**: JSON-based MCP setup
- **VSCode**: Direct extension + MCP support
- **And more**: Any MCP-compatible AI assistant
## Use Cases
### Large Codebase Navigation
Quickly find relevant code patterns, implementations, and examples across massive codebases.
### Code Review Assistance
Identify similar code patterns, potential duplications, and related functionality during reviews.
### Learning and Onboarding
Help new team members understand codebase structure and find relevant examples.
### Refactoring Support
Locate all instances of specific patterns or implementations that need updating.
### API Discovery
Find usage examples and implementations of specific APIs or libraries.
### Cross-Language Development
Search for similar functionality across different programming languages in polyglot codebases.

93
docs/getting-started/quick-start.md
View File

@@ -32,15 +32,46 @@ Replace the API keys with your actual keys.
```
Index this codebase
```
3. **Start searching**:
3. **Check indexing status**:
```
Check the indexing status
```
4. **Start searching**:
```
Find functions that handle user authentication
```
🎉 **That's it!** You now have semantic code search in Claude Code.
## Alternative Quick Setups
<details>
<summary><strong>Gemini CLI</strong></summary>
Gemini CLI requires manual configuration through a JSON file:
1. Create or edit the `~/.gemini/settings.json` file.
2. Add the following configuration:
```json
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
}
}
```
3. Save the file and restart Gemini CLI to apply the changes.
</details>
<details>
<summary><strong>Qwen Code</strong></summary>
@@ -169,7 +200,6 @@ Add the following configuration to your Void MCP settings:
</details>
<details>
<summary><strong>Claude Desktop</strong></summary>
@@ -192,23 +222,6 @@ Add to your Claude Desktop configuration:
</details>
<details>
<summary><strong>Claude Code</strong></summary>
Use the command line interface to add the Claude Context MCP server:
```bash
# Add the Claude Context MCP server
claude mcp add claude-context -e OPENAI_API_KEY=your-openai-api-key -e MILVUS_TOKEN=your-zilliz-cloud-api-key -- npx @zilliz/claude-context-mcp@latest
```
See the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for more details about MCP server management.
</details>
<details>
<summary><strong>Windsurf</strong></summary>
@@ -301,7 +314,6 @@ Cline uses a JSON configuration file to manage MCP servers. To integrate the pro
</details>
<details>
<summary><strong>Augment</strong></summary>
@@ -342,14 +354,9 @@ To configure Claude Context MCP in Augment Code, you can use either the graphica
{
"name": "claude-context",
"command": "npx",
"args": ["-y", "@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
]
"args": ["-y", "@zilliz/claude-context-mcp@latest"]
}
]
}
```
@@ -372,7 +379,6 @@ Roo Code utilizes a JSON configuration file for MCP servers:
"args": ["@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
@@ -385,6 +391,33 @@ Roo Code utilizes a JSON configuration file for MCP servers:
</details>
<details>
<summary><strong>Zencoder</strong></summary>
Zencoder offers support for MCP tools and servers in both its JetBrains and VS Code plugin versions.
1. Go to the Zencoder menu (...)
2. From the dropdown menu, select `Tools`
3. Click on the `Add Custom MCP`
4. Add the name (i.e. `Claude Context` and server configuration from below, and make sure to hit the `Install` button
```json
{
"command": "npx",
"args": ["@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
```
5. Save the server by hitting the `Install` button.
</details>
<details>
<summary><strong>Other MCP Clients</strong></summary>

50
docs/troubleshooting/faq.md
View File

@@ -2,51 +2,17 @@
## Q: What files does Claude Context decide to embed?
**A:** Claude Context embeds files based on the following rules:
**A:** Claude Context uses a comprehensive rule system to determine which files to include in indexing:
**Files that are included:**
- Files with supported extensions from multiple sources:
- DEFAULT_SUPPORTED_EXTENSIONS (built-in defaults)
- MCP custom extensions (via `customExtensions` parameter)
- Environment variable custom extensions (via `CUSTOM_EXTENSIONS`)
**Simple Rule:**
```
Final Files = (All Supported Extensions) - (All Ignore Patterns)
```
**Files that are excluded:**
- Files matching ignore patterns from multiple sources:
- DEFAULT_IGNORE_PATTERNS (built-in defaults)
- MCP custom ignore patterns (via `ignorePatterns` parameter)
- Environment variable custom ignore patterns (via `CUSTOM_IGNORE_PATTERNS`)
- Files matching patterns in .gitignore
- Files matching patterns in any .xxxignore files (e.g., .cursorignore, .codeiumignore)
- Files matching patterns in global ~/.context/.contextignore
- **Extensions are additive**: Default extensions + MCP custom + Environment variables
- **Ignore patterns are additive**: Default patterns + MCP custom + Environment variables + .gitignore + .xxxignore files + global .contextignore
The final rule is: `(DEFAULT_SUPPORTED_EXTENSIONS + MCP custom extensions + custom extensions from env variable) - (DEFAULT_IGNORE_PATTERNS + MCP custom ignore patterns + custom ignore patterns from env variable + .gitignore + .xxxignore files + global .contextignore)`
**Extension sources (all patterns are combined):**
1. **Default extensions**: Built-in supported file extensions (.ts, .js, .py, .java, .cpp, .md, etc.)
2. **MCP custom extensions**: Additional extensions passed via MCP `customExtensions` parameter
3. **Environment custom extensions**: Extensions from `CUSTOM_EXTENSIONS` env variable (comma-separated, e.g., `.vue,.svelte,.astro`)
**Ignore pattern sources (all patterns are combined):**
1. **Default patterns**: Built-in ignore patterns for common build outputs, dependencies, etc.
2. **MCP custom ignore patterns**: Additional patterns passed via MCP `ignorePatterns` parameter
3. **Environment custom ignore patterns**: Patterns from `CUSTOM_IGNORE_PATTERNS` env variable (comma-separated)
4. **.gitignore**: Standard Git ignore patterns in codebase root
5. **.xxxignore files**: Any file in codebase root matching pattern `.xxxignore` (e.g., `.cursorignore`, `.codeiumignore`)
6. **Global ignore**: `~/.context/.contextignore` for user-wide patterns
All patterns are merged together - MCP custom patterns and environment variables will NOT be overwritten by file-based patterns.
**Environment Variables:**
- `CUSTOM_EXTENSIONS`: Comma-separated list of file extensions (e.g., `.vue,.svelte,.astro`)
- `CUSTOM_IGNORE_PATTERNS`: Comma-separated list of ignore patterns (e.g., `temp/**,*.backup,private/**`)
These environment variables can be set in:
- System environment variables (highest priority)
- Global `~/.context/.env` file (lower priority)
Supported extensions include common programming languages (.ts, .js, .py, .java, .cpp, etc.) and documentation files (.md, .markdown). Default ignore patterns cover build outputs, dependencies (node_modules), IDE files, and temporary files.
**See the `DEFAULT_SUPPORTED_EXTENSIONS` and `DEFAULT_IGNORE_PATTERNS` definition:** [`packages/core/src/context.ts`](../../packages/core/src/context.ts)
**For detailed explanation see:** [File Inclusion Rules](../dive-deep/file-inclusion-rules.md)
## Q: Can I use a fully local deployment setup?

128
docs/troubleshooting/troubleshooting-guide.md Normal file
View File

@@ -0,0 +1,128 @@
# Troubleshooting Guide
When you encounter errors or issues with Claude Context, don't panic! This guide provides a systematic approach to identify and resolve problems.
- For MCP use cases, see [MCP Use Cases](#for-mcp-use-cases) section.
- For VSCode Extension use cases, see [VSCode Extension Use Cases](#for-vscode-extension-use-cases) section.
## For MCP Use Cases
### Step 1: Check Indexing Status First
Since indexing [runs in the background](../dive-deep/asynchronous-indexing-workflow.md), many issues are related to indexing status.
**Start by checking the indexing status:**
Tell your agent:
```
"Check the indexing status"
```
, which will call `get_indexing_status` tool to get error messages, progress information, or status details. They are helpful for troubleshooting.
### Step 2: Get Debug Logs
If Step 1 doesn't reveal the issue, collect detailed debug information:
**Get your MCP logs:**
- If you use Claude Code or Gemini CLI, start them with `--debug` mode:
```bash
claude --debug
# or
gemini --debug
```
- If you use Cursor-like GUI IDEs, find the MCP logs in the Output panel, e.g. Cursor:
1. Open the Output panel in Cursor (⌘⇧U)
2. Select "MCP Logs" from the dropdown
3. See [Cursor MCP FAQ](https://docs.cursor.com/en/context/mcp#faq) for details
**Check your MCP Client Setting:**
If logs don't solve the problem, note:
- Which MCP client you're using
- Your MCP configuration JSON contents
- This helps locate configuration issues
### Step 3: Reconnect MCP Server After Configuration Changes
If you locate the problem at [Step 1](#step-1-check-indexing-status-first) or [Step 2](#step-2-get-debug-logs), and have made changes to your environment configuration (such as [environment variables](../getting-started/environment-variables.md), API keys, or MCP settings), try restarting and reconnecting to the MCP server:
**Reconnection methods:**
- **Claude Code**: Use the command in the interactive mode:
```
/mcp reconnect claude-context
```
For more details, see [this comment](https://github.com/anthropics/claude-code/issues/605#issuecomment-3138778529).
- **Gemini CLI**: Use the command in the interactive mode:
```
/mcp refresh
```
For more details, see [this PR](https://github.com/google-gemini/gemini-cli/pull/4566).
- **Cursor and other GUI IDEs**: Look for a toggle icon or restart button to restart the MCP connection. e.g. [Cursor MCP FAQ](https://docs.cursor.com/en/context/mcp#faq)
After reconnecting, test if your issue is resolved and the system works normally.
### Step 4: Search Documentation and Community
If the previous steps don't solve the issue, search existing resources:
1. **Check Documentation:**
- [Main Documentation](../README.md) - General usage and setup
2. **Check FAQ:**
- [Troubleshooting FAQ](./faq.md) - Common issues and solutions
3. **Search GitHub Issues:**
- [GitHub Issues](https://github.com/zilliztech/claude-context/issues) - Known issues and discussions
- Search for similar problems and solutions
- Check both open and closed issues
### Step 5: Report the Issue
If none of the above steps resolve your problem, please [create a GitHub issue](https://github.com/zilliztech/claude-context/issues/new/choose).
### Step 6: After Version Updates
If the offical version of Claude Context has been updated, try reconnecting to the MCP server using the methods described in [Step 3](#step-3-reconnect-mcp-server-after-configuration-changes):
**Reconnection methods:**
- **Claude Code**: `/mcp reconnect claude-context`
- **Gemini CLI**: `/mcp refresh`
- **Cursor and other GUI IDEs**: Use the toggle icon or restart button
After reconnecting, test your use case again to see if the update resolved any previous issues or if new functionality is working as expected.
## For VSCode Extension Use Cases
### Step 1: Get Debug Logs
**Get your logs:**
- In the global search panel, type `> Toggle Developer Tools`
- Open the Chrome DevTools window to view logs
- See [VSCode Developer Tools guide](https://stackoverflow.com/questions/30765782/what-is-the-use-of-the-developer-tools-in-vs-code) for details
**Report your settings:**
- Include extension settings from the panel if possible
- This information helps locate configuration issues
### Step 2: Search Documentation and Community
If debug logs don't solve the issue, search existing resources:
1. **Check Documentation:**
- [Main Documentation](../README.md) - General usage and setup
2. **Check FAQ:**
- [Troubleshooting FAQ](./faq.md) - Common issues and solutions
3. **Search GitHub Issues:**
- [GitHub Issues](https://github.com/zilliztech/claude-context/issues) - Known issues and discussions
- Search for similar problems and solutions
- Check both open and closed issues
### Step 3: Report the Issue
If none of the above steps resolve your problem, please [create a GitHub issue](https://github.com/zilliztech/claude-context/issues/new/choose).
### Step 4: After Version Updates
If the offical version of VSCode Extension has been updated, try reinstalling the extension.

30
packages/core/README.md
View File

@@ -104,8 +104,10 @@ results.forEach(result => {
## Embedding Providers
- **OpenAI Embeddings** (`text-embedding-3-small`, `text-embedding-3-large`)
- **VoyageAI Embeddings** - High-quality embeddings optimized for code
- **OpenAI Embeddings** (`text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`)
- **VoyageAI Embeddings** - High-quality embeddings optimized for code (`voyage-code-3`, `voyage-3.5`, etc.)
- **Gemini Embeddings** - Google's embedding models (`gemini-embedding-001`)
- **Ollama Embeddings** - Local embedding models via Ollama
## Vector Database Support
@@ -127,6 +129,8 @@ interface ContextConfig {
codeSplitter?: Splitter; // Code splitting strategy
supportedExtensions?: string[]; // File extensions to index
ignorePatterns?: string[]; // Patterns to ignore
customExtensions?: string[]; // Custom extensions from MCP
customIgnorePatterns?: string[]; // Custom ignore patterns from MCP
}
```
@@ -138,16 +142,19 @@ interface ContextConfig {
'.ts', '.tsx', '.js', '.jsx', '.py', '.java', '.cpp', '.c', '.h', '.hpp',
'.cs', '.go', '.rs', '.php', '.rb', '.swift', '.kt', '.scala', '.m', '.mm',
// Text and markup files
'.md', '.markdown'
'.md', '.markdown', '.ipynb'
]
```
### Default Ignore Patterns
- `node_modules/**`, `dist/**`, `build/**`, `out/**`
- `.git/**`, `.vscode/**`, `.idea/**`
- `*.min.js`, `*.bundle.js`, `*.map`
- Log files, cache directories, and temporary files
- Build and dependency directories: `node_modules/**`, `dist/**`, `build/**`, `out/**`, `target/**`
- Version control: `.git/**`, `.svn/**`, `.hg/**`
- IDE files: `.vscode/**`, `.idea/**`, `*.swp`, `*.swo`
- Cache directories: `.cache/**`, `__pycache__/**`, `.pytest_cache/**`, `coverage/**`
- Minified files: `*.min.js`, `*.min.css`, `*.bundle.js`, `*.map`
- Log and temp files: `logs/**`, `tmp/**`, `temp/**`, `*.log`
- Environment files: `.env`, `.env.*`, `*.local`
## API Reference
@@ -155,13 +162,17 @@ interface ContextConfig {
#### Methods
- `indexCodebase(path, progressCallback?)` - Index an entire codebase
- `semanticSearch(path, query, topK?, threshold?)` - Search indexed code semantically
- `indexCodebase(path, progressCallback?, forceReindex?)` - Index an entire codebase
- `reindexByChange(path, progressCallback?)` - Incrementally re-index only changed files
- `semanticSearch(path, query, topK?, threshold?, filterExpr?)` - Search indexed code semantically
- `hasIndex(path)` - Check if codebase is already indexed
- `clearIndex(path, progressCallback?)` - Remove index for a codebase
- `updateIgnorePatterns(patterns)` - Update ignore patterns
- `addCustomIgnorePatterns(patterns)` - Add custom ignore patterns
- `addCustomExtensions(extensions)` - Add custom file extensions
- `updateEmbedding(embedding)` - Switch embedding provider
- `updateVectorDatabase(vectorDB)` - Switch vector database
- `updateSplitter(splitter)` - Switch code splitter
### Search Results
@@ -173,7 +184,6 @@ interface SemanticSearchResult {
endLine: number; // Ending line number
language: string; // Programming language
score: number; // Similarity score (0-1)
fileExtension: string; // File extension
}
```

115
packages/mcp/README.md
View File

@@ -174,6 +174,50 @@ These settings work in combination with tool parameters - patterns from both sou
## Usage with MCP Clients
<details>
<summary><strong>Claude Code</strong></summary>
Use the command line interface to add the Claude Context MCP server:
```bash
# Add the Claude Context MCP server
claude mcp add claude-context -e OPENAI_API_KEY=your-openai-api-key -e MILVUS_TOKEN=your-zilliz-cloud-api-key -- npx @zilliz/claude-context-mcp@latest
```
See the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for more details about MCP server management.
</details>
<details>
<summary><strong>Gemini CLI</strong></summary>
Gemini CLI requires manual configuration through a JSON file:
1. Create or edit the `~/.gemini/settings.json` file.
2. Add the following configuration:
```json
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
}
}
```
3. Save the file and restart Gemini CLI to apply the changes.
</details>
<details>
<summary><strong>Qwen Code</strong></summary>
@@ -324,21 +368,6 @@ Add to your Claude Desktop configuration:
</details>
<details>
<summary><strong>Claude Code</strong></summary>
Use the command line interface to add the Claude Context MCP server:
```bash
# Add the Claude Context MCP server
claude mcp add claude-context -e OPENAI_API_KEY=your-openai-api-key -e MILVUS_TOKEN=your-zilliz-cloud-api-key -- npx @zilliz/claude-context-mcp@latest
```
See the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for more details about MCP server management.
</details>
<details>
<summary><strong>Windsurf</strong></summary>
@@ -479,34 +508,6 @@ To configure Claude Context MCP in Augment Code, you can use either the graphica
</details>
<details>
<summary><strong>Gemini CLI</strong></summary>
Gemini CLI requires manual configuration through a JSON file:
1. Create or edit the `~/.gemini/settings.json` file.
2. Add the following configuration:
```json
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
}
}
```
3. Save the file and restart Gemini CLI to apply the changes.
</details>
<details>
<summary><strong>Roo Code</strong></summary>
@@ -535,6 +536,34 @@ Roo Code utilizes a JSON configuration file for MCP servers:
</details>
<details>
<summary><strong>Zencoder</strong></summary>
Zencoder offers support for MCP tools and servers in both its JetBrains and VS Code plugin versions.
1. Go to the Zencoder menu (...)
2. From the dropdown menu, select `Tools`
3. Click on the `Add Custom MCP`
4. Add the name (i.e. `Claude Context` and server configuration from below, and make sure to hit the `Install` button
```json
{
"command": "npx",
"args": ["@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
```
5. Save the server by hitting the `Install` button.
</details>
<details>
<summary><strong>Other MCP Clients</strong></summary>