This is page 1 of 6. Use http://codebase.md/zilliztech/claude-context?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .env.example
├── .eslintrc.js
├── .github
│ ├── ISSUE_TEMPLATE
│ │ └── bug_report.md
│ └── workflows
│ ├── ci.yml
│ └── release.yml
├── .gitignore
├── .npmrc
├── .vscode
│ ├── extensions.json
│ ├── launch.json
│ ├── settings.json
│ └── tasks.json
├── assets
│ ├── Architecture.png
│ ├── claude-context.png
│ ├── docs
│ │ ├── file-inclusion-flow.png
│ │ ├── indexing-flow-diagram.png
│ │ └── indexing-sequence-diagram.png
│ ├── file_synchronizer.png
│ ├── mcp_efficiency_analysis_chart.png
│ ├── signup_and_create_cluster.jpeg
│ ├── signup_and_get_apikey.png
│ ├── vscode-setup.png
│ └── zilliz_cloud_dashboard.jpeg
├── build-benchmark.json
├── CONTRIBUTING.md
├── docs
│ ├── dive-deep
│ │ ├── asynchronous-indexing-workflow.md
│ │ └── file-inclusion-rules.md
│ ├── getting-started
│ │ ├── environment-variables.md
│ │ ├── prerequisites.md
│ │ └── quick-start.md
│ ├── README.md
│ └── troubleshooting
│ ├── faq.md
│ └── troubleshooting-guide.md
├── evaluation
│ ├── .python-version
│ ├── analyze_and_plot_mcp_efficiency.py
│ ├── case_study
│ │ ├── django_14170
│ │ │ ├── both_conversation.log
│ │ │ ├── both_result.json
│ │ │ ├── grep_conversation.log
│ │ │ ├── grep_result.json
│ │ │ └── README.md
│ │ ├── pydata_xarray_6938
│ │ │ ├── both_conversation.log
│ │ │ ├── both_result.json
│ │ │ ├── grep_conversation.log
│ │ │ ├── grep_result.json
│ │ │ └── README.md
│ │ └── README.md
│ ├── client.py
│ ├── generate_subset_json.py
│ ├── pyproject.toml
│ ├── README.md
│ ├── retrieval
│ │ ├── __init__.py
│ │ ├── base.py
│ │ └── custom.py
│ ├── run_evaluation.py
│ ├── servers
│ │ ├── __init__.py
│ │ ├── edit_server.py
│ │ ├── grep_server.py
│ │ └── read_server.py
│ ├── utils
│ │ ├── __init__.py
│ │ ├── constant.py
│ │ ├── file_management.py
│ │ ├── format.py
│ │ └── llm_factory.py
│ └── uv.lock
├── examples
│ ├── basic-usage
│ │ ├── index.ts
│ │ ├── package.json
│ │ └── README.md
│ └── README.md
├── LICENSE
├── package.json
├── packages
│ ├── chrome-extension
│ │ ├── CONTRIBUTING.md
│ │ ├── package.json
│ │ ├── README.md
│ │ ├── src
│ │ │ ├── background.ts
│ │ │ ├── config
│ │ │ │ └── milvusConfig.ts
│ │ │ ├── content.ts
│ │ │ ├── icons
│ │ │ │ ├── icon128.png
│ │ │ │ ├── icon16.png
│ │ │ │ ├── icon32.png
│ │ │ │ └── icon48.png
│ │ │ ├── manifest.json
│ │ │ ├── milvus
│ │ │ │ └── chromeMilvusAdapter.ts
│ │ │ ├── options.html
│ │ │ ├── options.ts
│ │ │ ├── storage
│ │ │ │ └── indexedRepoManager.ts
│ │ │ ├── stubs
│ │ │ │ └── milvus-vectordb-stub.ts
│ │ │ ├── styles.css
│ │ │ └── vm-stub.js
│ │ ├── tsconfig.json
│ │ └── webpack.config.js
│ ├── core
│ │ ├── CONTRIBUTING.md
│ │ ├── package.json
│ │ ├── README.md
│ │ ├── src
│ │ │ ├── context.ts
│ │ │ ├── embedding
│ │ │ │ ├── base-embedding.ts
│ │ │ │ ├── gemini-embedding.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── ollama-embedding.ts
│ │ │ │ ├── openai-embedding.ts
│ │ │ │ └── voyageai-embedding.ts
│ │ │ ├── index.ts
│ │ │ ├── splitter
│ │ │ │ ├── ast-splitter.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── langchain-splitter.ts
│ │ │ ├── sync
│ │ │ │ ├── merkle.ts
│ │ │ │ └── synchronizer.ts
│ │ │ ├── types.ts
│ │ │ ├── utils
│ │ │ │ ├── env-manager.ts
│ │ │ │ └── index.ts
│ │ │ └── vectordb
│ │ │ ├── index.ts
│ │ │ ├── milvus-restful-vectordb.ts
│ │ │ ├── milvus-vectordb.ts
│ │ │ ├── types.ts
│ │ │ └── zilliz-utils.ts
│ │ └── tsconfig.json
│ ├── mcp
│ │ ├── CONTRIBUTING.md
│ │ ├── package.json
│ │ ├── README.md
│ │ ├── src
│ │ │ ├── config.ts
│ │ │ ├── embedding.ts
│ │ │ ├── handlers.ts
│ │ │ ├── index.ts
│ │ │ ├── snapshot.ts
│ │ │ ├── sync.ts
│ │ │ └── utils.ts
│ │ └── tsconfig.json
│ └── vscode-extension
│ ├── CONTRIBUTING.md
│ ├── copy-assets.js
│ ├── LICENSE
│ ├── package.json
│ ├── README.md
│ ├── resources
│ │ ├── activity_bar.svg
│ │ └── icon.png
│ ├── src
│ │ ├── commands
│ │ │ ├── indexCommand.ts
│ │ │ ├── searchCommand.ts
│ │ │ └── syncCommand.ts
│ │ ├── config
│ │ │ └── configManager.ts
│ │ ├── extension.ts
│ │ ├── stubs
│ │ │ ├── ast-splitter-stub.js
│ │ │ └── milvus-vectordb-stub.js
│ │ └── webview
│ │ ├── scripts
│ │ │ └── semanticSearch.js
│ │ ├── semanticSearchProvider.ts
│ │ ├── styles
│ │ │ └── semanticSearch.css
│ │ ├── templates
│ │ │ └── semanticSearch.html
│ │ └── webviewHelper.ts
│ ├── tsconfig.json
│ ├── wasm
│ │ ├── tree-sitter-c_sharp.wasm
│ │ ├── tree-sitter-cpp.wasm
│ │ ├── tree-sitter-go.wasm
│ │ ├── tree-sitter-java.wasm
│ │ ├── tree-sitter-javascript.wasm
│ │ ├── tree-sitter-python.wasm
│ │ ├── tree-sitter-rust.wasm
│ │ ├── tree-sitter-scala.wasm
│ │ └── tree-sitter-typescript.wasm
│ └── webpack.config.js
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
├── python
│ ├── README.md
│ ├── test_context.ts
│ ├── test_endtoend.py
│ └── ts_executor.py
├── README.md
├── scripts
│ └── build-benchmark.js
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/evaluation/.python-version:
--------------------------------------------------------------------------------
```
1 | 3.10
```
--------------------------------------------------------------------------------
/.npmrc:
--------------------------------------------------------------------------------
```
1 | # Enable shell emulator for cross-platform script execution
2 | shell-emulator=true
3 |
4 | # Ignore workspace root check warning (already configured in package.json)
5 | ignore-workspace-root-check=true
6 |
7 | # Build performance optimizations
8 | prefer-frozen-lockfile=true
9 | auto-install-peers=true
10 | dedupe-peer-dependents=true
11 |
12 | # Enhanced caching
13 | store-dir=~/.pnpm-store
14 | cache-dir=~/.pnpm-cache
15 |
16 | # Parallel execution optimization
17 | child-concurrency=4
18 |
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | # Dependencies
2 | node_modules/
3 | *.pnp
4 | .pnp.js
5 |
6 | # Production builds
7 | dist/
8 | build/
9 | *.tsbuildinfo
10 |
11 | # Environment variables
12 | .env
13 | .env.local
14 | .env.development.local
15 | .env.production.local
16 |
17 | # Logs
18 | npm-debug.log*
19 | yarn-debug.log*
20 | yarn-error.log*
21 | pnpm-debug.log*
22 | lerna-debug.log*
23 |
24 | # Runtime data
25 | pids
26 | *.pid
27 | *.seed
28 | *.pid.lock
29 |
30 |
31 |
32 | # IDE
33 | # .vscode/
34 | .idea/
35 | *.swp
36 | *.swo
37 | *~
38 |
39 | # OS
40 | .DS_Store
41 | .DS_Store?
42 | ._*
43 | .Spotlight-V100
44 | .Trashes
45 | ehthumbs.db
46 | Thumbs.db
47 |
48 | # Temporary files
49 | *.tmp
50 | *.temp
51 |
52 | # Extension specific
53 | *.vsix
54 | *.crx
55 | *.pem
56 |
57 | __pycache__/
58 | *.log
59 | !evaluation/case_study/**/*.log
60 |
61 | .claude/*
62 | CLAUDE.md
63 |
64 | .cursor/*
65 |
66 | evaluation/repos
67 | repos
68 |
69 | evaluation/retrieval_results*
70 | .venv/
```
--------------------------------------------------------------------------------
/.eslintrc.js:
--------------------------------------------------------------------------------
```javascript
1 | module.exports = {
2 | root: true,
3 | parser: '@typescript-eslint/parser',
4 | plugins: ['@typescript-eslint'],
5 | extends: [
6 | 'eslint:recommended',
7 | '@typescript-eslint/recommended',
8 | ],
9 | parserOptions: {
10 | ecmaVersion: 2020,
11 | sourceType: 'module',
12 | },
13 | env: {
14 | node: true,
15 | es6: true,
16 | },
17 | rules: {
18 | '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
19 | '@typescript-eslint/explicit-function-return-type': 'off',
20 | '@typescript-eslint/explicit-module-boundary-types': 'off',
21 | '@typescript-eslint/no-explicit-any': 'warn',
22 | },
23 | ignorePatterns: [
24 | 'dist',
25 | 'node_modules',
26 | '*.js',
27 | '*.d.ts',
28 | ],
29 | };
```
--------------------------------------------------------------------------------
/.env.example:
--------------------------------------------------------------------------------
```
1 | # Claude Context Environment Variables Example
2 | #
3 | # Copy this file to ~/.context/.env as a global setting, modify the values as needed
4 | #
5 | # Usage: cp env.example ~/.context/.env
6 | #
7 | # 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)
8 |
9 | # =============================================================================
10 | # Embedding Provider Configuration
11 | # =============================================================================
12 |
13 | # Embedding provider: OpenAI, VoyageAI, Gemini, Ollama
14 | EMBEDDING_PROVIDER=OpenAI
15 |
16 | # Embedding model (provider-specific)
17 | EMBEDDING_MODEL=text-embedding-3-small
18 |
19 | # Embedding batch size for processing (default: 100)
20 | # You can customize it according to the throughput of your embedding model. Generally, larger batch size means less indexing time.
21 | EMBEDDING_BATCH_SIZE=100
22 |
23 | # =============================================================================
24 | # OpenAI Configuration
25 | # =============================================================================
26 |
27 | # OpenAI API key
28 | OPENAI_API_KEY=your-openai-api-key-here
29 |
30 | # OpenAI base URL (optional, for custom endpoints)
31 | # OPENAI_BASE_URL=https://api.openai.com/v1
32 |
33 | # =============================================================================
34 | # VoyageAI Configuration
35 | # =============================================================================
36 |
37 | # VoyageAI API key
38 | # VOYAGEAI_API_KEY=your-voyageai-api-key-here
39 |
40 | # =============================================================================
41 | # Gemini Configuration
42 | # =============================================================================
43 |
44 | # Google Gemini API key
45 | # GEMINI_API_KEY=your-gemini-api-key-here
46 |
47 | # Gemini API base URL (optional, for custom endpoints)
48 | # GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
49 |
50 | # =============================================================================
51 | # Ollama Configuration
52 | # =============================================================================
53 |
54 | # Ollama model name
55 | # OLLAMA_MODEL=
56 |
57 | # Ollama host (default: http://localhost:11434)
58 | # OLLAMA_HOST=http://localhost:11434
59 |
60 | # =============================================================================
61 | # Vector Database Configuration (Milvus/Zilliz)
62 | # =============================================================================
63 |
64 | # Milvus server address. It's optional when you get Zilliz Personal API Key.
65 | MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint
66 |
67 | # Milvus authentication token. You can refer to this guide to get Zilliz Personal API Key as your Milvus token.
68 | # https://github.com/zilliztech/claude-context/blob/master/assets/signup_and_get_apikey.png
69 | MILVUS_TOKEN=your-zilliz-cloud-api-key
70 |
71 |
72 | # =============================================================================
73 | # Code Splitter Configuration
74 | # =============================================================================
75 |
76 | # Code splitter type: ast, langchain
77 | SPLITTER_TYPE=ast
78 |
79 | # =============================================================================
80 | # Custom File Processing Configuration
81 | # =============================================================================
82 |
83 | # Additional file extensions to include beyond defaults (comma-separated)
84 | # Example: .vue,.svelte,.astro,.twig,.blade.php
85 | # CUSTOM_EXTENSIONS=.vue,.svelte,.astro
86 |
87 | # Additional ignore patterns to exclude files/directories (comma-separated)
88 | # Example: temp/**,*.backup,private/**,uploads/**
89 | # CUSTOM_IGNORE_PATTERNS=temp/**,*.backup,private/**
90 |
91 | # Whether to use hybrid search mode. If true, it will use both dense vector and BM25; if false, it will use only dense vector search.
92 | # HYBRID_MODE=true
93 |
```
--------------------------------------------------------------------------------
/examples/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Claude Context Examples
2 |
3 | This directory contains usage examples for Claude Context.
4 |
```
--------------------------------------------------------------------------------
/evaluation/case_study/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Case Study
2 |
3 | This directory includes some case analysis. We compare the both method(grep + Claude Context semantic search) and the traditional grep only method.
4 |
5 | These cases are selected from the Princeton NLP's [SWE-bench_Verified](https://openai.com/index/introducing-swe-bench-verified/) dataset. The results and the logs are generated by the [run_evaluation.py](../run_evaluation.py) script. For more details, please refer to the [evaluation README.md](../README.md) file.
6 |
7 | - 📁 [django_14170](./django_14170/): Query optimization in YearLookup breaks filtering by "__iso_year"
8 | - 📁 [pydata_xarray_6938](./pydata_xarray_6938/): `.swap_dims()` can modify original object
9 |
10 | Each case study includes:
11 | - **Original Issue**: The GitHub issue description and requirements
12 | - **Problem Analysis**: Technical breakdown of the bug and expected solution
13 | - **Method Comparison**: Detailed comparison of both approaches
14 | - **Conversation Logs**: The interaction records showing how the LLM agent call the ols and generate the final answer.
15 | - **Results**: Performance metrics and outcome analysis
16 |
17 | ## Key Results
18 | Compared with traditional grep only, the both method(grep + Claude Context semantic search) is more efficient and accurate.
19 |
20 | ## Why Grep Fails
21 |
22 | 1. **Information Overload** - Generates hundreds of irrelevant matches
23 | 2. **No Semantic Understanding** - Only literal text matching
24 | 3. **Context Loss** - Can't understand code relationships
25 | 4. **Inefficient Navigation** - Produces many irrelevant results
26 |
27 | ## How Grep + Semantic Search Wins
28 |
29 | 1. **Intelligent Filtering** - Automatically ranks by relevance
30 | 2. **Conceptual Understanding** - Grasps code meaning and relationships
31 | 3. **Efficient Navigation** - Direct targeting of relevant sections
32 |
```
--------------------------------------------------------------------------------
/python/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Python → TypeScript Claude Context Bridge
2 |
3 | A simple utility to call TypeScript Claude Context methods from Python.
4 |
5 | ## What's This?
6 |
7 | This directory contains a basic bridge that allows you to run Claude Context TypeScript functions from Python scripts. It's not a full SDK - just a simple way to test and use the TypeScript codebase from Python.
8 |
9 | ## Files
10 |
11 | - `ts_executor.py` - Executes TypeScript methods from Python
12 | - `test_context.ts` - TypeScript test script with Claude Context workflow
13 | - `test_endtoend.py` - Python script that calls the TypeScript test
14 |
15 | ## Prerequisites
16 |
17 | ```bash
18 | # Make sure you have Node.js dependencies installed
19 | cd .. && pnpm install
20 |
21 | # Set your OpenAI API key (required for actual indexing)
22 | export OPENAI_API_KEY="your-openai-api-key"
23 |
24 | # Optional: Set Milvus address (defaults to localhost:19530)
25 | export MILVUS_ADDRESS="localhost:19530"
26 | ```
27 |
28 | ## Quick Usage
29 |
30 | ```bash
31 | # Run the end-to-end test
32 | python test_endtoend.py
33 | ```
34 |
35 | This will:
36 | 1. Create embeddings using OpenAI
37 | 2. Connect to Milvus vector database
38 | 3. Index the `packages/core/src` codebase
39 | 4. Perform a semantic search
40 | 5. Show results
41 |
42 | ## Manual Usage
43 |
44 | ```python
45 | from ts_executor import TypeScriptExecutor
46 |
47 | executor = TypeScriptExecutor()
48 | result = executor.call_method(
49 | './test_context.ts',
50 | 'testContextEndToEnd',
51 | {
52 | 'openaiApiKey': 'sk-your-key',
53 | 'milvusAddress': 'localhost:19530',
54 | 'codebasePath': '../packages/core/src',
55 | 'searchQuery': 'vector database configuration'
56 | }
57 | )
58 |
59 | print(result)
60 | ```
61 | ## How It Works
62 |
63 | 1. `ts_executor.py` creates temporary TypeScript wrapper files
64 | 2. Runs them with `ts-node`
65 | 3. Captures JSON output and returns to Python
66 | 4. Supports async functions and complex parameters
67 |
68 | That's it! This is just a simple bridge for testing purposes.
```
--------------------------------------------------------------------------------
/docs/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Claude Context Documentation
2 | 
3 |
4 | Welcome to the Claude Context documentation! Claude Context is a powerful tool that adds semantic code search capabilities to AI coding assistants through MCP.
5 |
6 | ## 🚀 Quick Navigation
7 |
8 | ### Getting Started
9 | - [🛠️ Prerequisites](getting-started/prerequisites.md) - What you need before starting
10 | - [🔍 Environment Variables](getting-started/environment-variables.md) - How to configure environment variables for MCP
11 | - [⚡ Quick Start Guide](getting-started/quick-start.md) - Get up and running in 1 minutes
12 |
13 |
14 | ### Components
15 | - [MCP Server](../packages/mcp/README.md) - The MCP server of Claude Context
16 | - [VSCode Extension](../packages/vscode-extension/README.md) - The VSCode extension of Claude Context
17 | - [Core Package](../packages/core/README.md) - The core package of Claude Context
18 |
19 | ### Dive Deep
20 | - [File Inclusion & Exclusion Rules](dive-deep/file-inclusion-rules.md) - Detailed explanation of file inclusion and exclusion rules
21 | - [Asynchronous Indexing Workflow](dive-deep/asynchronous-indexing-workflow.md) - Detailed explanation of asynchronous indexing workflow
22 |
23 | ### Troubleshooting
24 | - [❓ FAQ](troubleshooting/faq.md) - Frequently asked questions
25 | - [🐛 Troubleshooting Guide](troubleshooting/troubleshooting-guide.md) - Troubleshooting guide
26 |
27 | ## 🔗 External Resources
28 |
29 | - [GitHub Repository](https://github.com/zilliztech/claude-context)
30 | - [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=zilliz.semanticcodesearch)
31 | - [npm - Core Package](https://www.npmjs.com/package/@zilliz/claude-context-core)
32 | - [npm - MCP Server](https://www.npmjs.com/package/@zilliz/claude-context-mcp)
33 | - [Zilliz Cloud](https://cloud.zilliz.com)
34 |
35 | ## 💬 Support
36 |
37 | - **Issues**: [GitHub Issues](https://github.com/zilliztech/claude-context/issues)
38 | - **Discord**: [Join our Discord](https://discord.gg/mKc3R95yE5)
39 |
```
--------------------------------------------------------------------------------
/examples/basic-usage/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Basic Usage Example
2 |
3 | This example demonstrates the basic usage of Claude Context.
4 |
5 | ## Prerequisites
6 |
7 | 1. **OpenAI API Key**: Set your OpenAI API key for embeddings:
8 | ```bash
9 | export OPENAI_API_KEY="your-openai-api-key"
10 | ```
11 |
12 | 2. **Milvus Server**: Make sure Milvus server is running:
13 | - You can also use fully managed Milvus on [Zilliz Cloud](https://zilliz.com/cloud).
14 | In this case, set the `MILVUS_ADDRESS` as the Public Endpoint and `MILVUS_TOKEN` as the Token like this:
15 | ```bash
16 | export MILVUS_ADDRESS="https://your-cluster.zillizcloud.com"
17 | export MILVUS_TOKEN="your-zilliz-token"
18 | ```
19 |
20 |
21 | - You can also set up a Milvus server on [Docker or Kubernetes](https://milvus.io/docs/install-overview.md). In this setup, please use the server address and port as your `uri`, e.g.`http://localhost:19530`. If you enable the authentication feature on Milvus, set the `token` as `"<your_username>:<your_password>"`, otherwise there is no need to set the token.
22 | ```bash
23 | export MILVUS_ADDRESS="http://localhost:19530"
24 | export MILVUS_TOKEN="<your_username>:<your_password>"
25 | ```
26 |
27 |
28 | ## Running the Example
29 |
30 | 1. Install dependencies:
31 | ```bash
32 | pnpm install
33 | ```
34 |
35 | 2. Set environment variables (see examples above)
36 |
37 | 3. Run the example:
38 | ```bash
39 | pnpm run start
40 | ```
41 |
42 | ## What This Example Does
43 | 1. **Indexes Codebase**: Indexes the entire Claude Context project
44 | 2. **Performs Searches**: Executes semantic searches for different code patterns
45 | 3. **Shows Results**: Displays search results with similarity scores and file locations
46 |
47 | ## Expected Output
48 |
49 | ```
50 | 🚀 Claude Context Real Usage Example
51 | ===============================
52 | ...
53 | 🔌 Connecting to vector database at: ...
54 |
55 | 📖 Starting to index codebase...
56 | 🗑️ Existing index found, clearing it first...
57 | 📊 Indexing stats: 45 files, 234 code chunks
58 |
59 | 🔍 Performing semantic search...
60 |
61 | 🔎 Search: "vector database operations"
62 | 1. Similarity: 89.23%
63 | File: /path/to/packages/core/src/vectordb/milvus-vectordb.ts
64 | Language: typescript
65 | Lines: 147-177
66 | Preview: async search(collectionName: string, queryVector: number[], options?: SearchOptions)...
67 |
68 | 🎉 Example completed successfully!
69 | ```
70 |
```
--------------------------------------------------------------------------------
/packages/chrome-extension/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # GitHub Code Vector Search Chrome Extension
2 |
3 | A Chrome extension for indexing and semantically searching GitHub repository code, powered by Claude Context.
4 |
5 | > 📖 **New to Claude Context?** Check out the [main project README](../../README.md) for an overview and setup instructions.
6 |
7 | ## Features
8 |
9 | - 🔍 **Semantic Search**: Intelligent code search on GitHub repositories based on semantic understanding
10 | - 📁 **Repository Indexing**: Automatically index GitHub repositories and build semantic vector database
11 | - 🎯 **Context Search**: Search related code by selecting code snippets directly on GitHub
12 | - 🔧 **Multi-platform Support**: Support for OpenAI and VoyageAI as embedding providers
13 | - 💾 **Vector Storage**: Integrated with Milvus vector database for efficient storage and retrieval
14 | - 🌐 **GitHub Integration**: Seamlessly integrates with GitHub's interface
15 | - 📱 **Cross-Repository**: Search across multiple indexed repositories
16 | - ⚡ **Real-time**: Index and search code as you browse GitHub
17 |
18 | ## Installation
19 |
20 | ### From Chrome Web Store
21 |
22 | > **Coming Soon**: Extension will be available on Chrome Web Store
23 |
24 | ### Manual Installation (Development)
25 |
26 | 1. **Build the Extension**:
27 | ```bash
28 | cd packages/chrome-extension
29 | pnpm build
30 | ```
31 |
32 | 2. **Load in Chrome**:
33 | - Open Chrome and navigate to `chrome://extensions/`
34 | - Enable "Developer mode" in the top right
35 | - Click "Load unpacked" and select the `dist` folder
36 | - The extension should now appear in your extensions list
37 |
38 | ## Quick Start
39 |
40 | 1. **Configure Settings**:
41 | - Click the extension icon in Chrome toolbar
42 | - Go to Options/Settings
43 | - Configure embedding provider and API Key
44 | - Set up Milvus connection details
45 |
46 | 2. **Index a Repository**:
47 | - Navigate to any GitHub repository
48 | - Click the "Index Repository" button that appears in the sidebar
49 | - Wait for indexing to complete
50 |
51 | 3. **Start Searching**:
52 | - Use the search box that appears on GitHub repository pages
53 | - Enter natural language queries like "function that handles authentication"
54 | - Click on results to navigate to the code
55 |
56 | ## Configuration
57 |
58 | The extension can be configured through the options page:
59 |
60 | - **Embedding Provider**: Choose between OpenAI or VoyageAI
61 | - **Embedding Model**: Select specific model (e.g., `text-embedding-3-small`)
62 | - **API Key**: Your embedding provider API key
63 | - **Milvus Settings**: Vector database connection details
64 | - **GitHub Token**: Personal access token for private repositories (optional)
65 |
66 | ## Permissions
67 |
68 | The extension requires the following permissions:
69 |
70 | - **Storage**: To save configuration and index metadata
71 | - **Scripting**: To inject search UI into GitHub pages
72 | - **Unlimited Storage**: For storing vector embeddings locally
73 | - **Host Permissions**: Access to GitHub.com and embedding provider APIs
74 |
75 | ## File Structure
76 |
77 | - `src/content.ts` - Main content script that injects UI into GitHub pages
78 | - `src/background.ts` - Background service worker for extension lifecycle
79 | - `src/options.ts` - Options page for configuration
80 | - `src/config/milvusConfig.ts` - Milvus connection configuration
81 | - `src/milvus/chromeMilvusAdapter.ts` - Browser-compatible Milvus adapter
82 | - `src/storage/indexedRepoManager.ts` - Repository indexing management
83 | - `src/stubs/` - Browser compatibility stubs for Node.js modules
84 |
85 | ## Development Features
86 |
87 | - **Browser Compatibility**: Node.js modules adapted for browser environment
88 | - **WebAssembly Support**: Optimized for browser performance
89 | - **Offline Capability**: Local storage for indexed repositories
90 | - **Progress Tracking**: Real-time indexing progress indicators
91 | - **Error Handling**: Graceful degradation and user feedback
92 |
93 | ## Usage Examples
94 |
95 | ### Basic Search
96 | 1. Navigate to a GitHub repository
97 | 2. Enter query: "error handling middleware"
98 | 3. Browse semantic search results
99 |
100 | ### Context Search
101 | 1. Select code snippet on GitHub
102 | 2. Right-click and choose "Search Similar Code"
103 | 3. View related code across the repository
104 |
105 | ### Multi-Repository Search
106 | 1. Index multiple repositories
107 | 2. Use the extension popup to search across all indexed repos
108 | 3. Filter results by repository or file type
109 |
110 | ## Contributing
111 |
112 | This Chrome extension is part of the Claude Context monorepo. Please see:
113 | - [Main Contributing Guide](../../CONTRIBUTING.md) - General contribution guidelines
114 | - [Chrome Extension Contributing](CONTRIBUTING.md) - Specific development guide for this extension
115 |
116 | ## Related Packages
117 |
118 | - **[@zilliz/claude-context-core](../core)** - Core indexing engine used by this extension
119 | - **[@zilliz/claude-context-vscode-extension](../vscode-extension)** - VSCode integration
120 | - **[@zilliz/claude-context-mcp](../mcp)** - MCP server integration
121 |
122 | ## Tech Stack
123 |
124 | - **TypeScript** - Type-safe development
125 | - **Chrome Extension Manifest V3** - Modern extension architecture
126 | - **Webpack** - Module bundling and optimization
127 | - **Claude Context Core** - Semantic search engine
128 | - **Milvus Vector Database** - Vector storage and retrieval
129 | - **OpenAI/VoyageAI Embeddings** - Text embedding generation
130 |
131 | ## Browser Support
132 |
133 | - Chrome 88+
134 | - Chromium-based browsers (Edge, Brave, etc.)
135 |
136 | ## License
137 |
138 | MIT - See [LICENSE](../../LICENSE) for details
139 |
```
--------------------------------------------------------------------------------
/evaluation/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Claude Context MCP Evaluation
2 |
3 | This directory contains the evaluation framework and experimental results for comparing the efficiency of code retrieval using Claude Context MCP versus traditional grep-only approaches.
4 |
5 | ## Overview
6 |
7 | We conducted a controlled experiment to measure the impact of adding Claude Context MCP tool to a baseline coding agent. The evaluation demonstrates significant improvements in token efficiency while maintaining comparable retrieval quality.
8 |
9 | ## Experimental Design
10 |
11 | We designed a controlled experiment comparing two coding agents performing identical retrieval tasks. The baseline agent uses simple tools including read, grep, and edit functions. The enhanced agent adds Claude Context MCP tool to this same foundation. Both agents work on the same dataset using the same model to ensure fair comparison. We use [LangGraph MCP and ReAct framework](https://langchain-ai.github.io/langgraph/agents/mcp/#use-mcp-tools) to implement it.
12 |
13 | We selected 30 instances from Princeton NLP's [SWE-bench_Verified](https://openai.com/index/introducing-swe-bench-verified/) dataset, filtering for 15-60 minute difficulty problems with exactly 2 file modifications. This subset represents typical coding tasks and enables quick validation. The dataset generation is implemented in [`generate_subset_json.py`](./generate_subset_json.py).
14 |
15 | We chose [GPT-4o-mini](https://platform.openai.com/docs/models/gpt-4o-mini) as the default model for cost-effective considerations.
16 |
17 | We ran each method 3 times independently, giving us 6 total runs for statistical reliability. We measured token usage, tool calls, retrieval precision, recall, and F1-score across all runs. The main entry point for running evaluations is [`run_evaluation.py`](./run_evaluation.py).
18 |
19 | ## Key Results
20 |
21 | ### Performance Summary
22 |
23 | | Metric | Baseline (Grep Only) | With Claude Context MCP | Improvement |
24 | |--------|---------------------|--------------------------|-------------|
25 | | **Average F1-Score** | 0.40 | 0.40 | Comparable |
26 | | **Average Token Usage** | 73,373 | 44,449 | **-39.4%** |
27 | | **Average Tool Calls** | 8.3 | 5.3 | **-36.3%** |
28 |
29 | ### Key Findings
30 |
31 | **Dramatic Efficiency Gains**:
32 |
33 | With Claude Context MCP, we achieved:
34 | - **39.4% reduction** in token consumption (28,924 tokens saved per instance)
35 | - **36.3% reduction** in tool calls (3.0 fewer calls per instance)
36 |
37 |
38 | ## Conclusion
39 |
40 | The results demonstrate that Claude Context MCP provides:
41 |
42 | ### Immediate Benefits
43 | - **Cost Efficiency**: ~40% reduction in token usage directly reduces operational costs
44 | - **Speed Improvement**: Fewer tool calls and tokens mean faster code localization and task completion
45 | - **Better Quality**: This also means that, under the constraint of limited token context length, using Claude Context yields better retrieval and answer results.
46 |
47 | ### Strategic Advantages
48 | - **Better Resource Utilization**: Under fixed token budgets, Claude Context MCP enables handling more tasks
49 | - **Wider Usage Scenarios**: Lower per-task costs enable broader usage scenarios
50 | - **Improved User Experience**: Faster responses with maintained accuracy
51 |
52 |
53 | ## Running the Evaluation
54 |
55 | To reproduce these results:
56 |
57 | 1. **Install Dependencies**:
58 |
59 | For python environment, you can use `uv` to install the lockfile dependencies.
60 | ```bash
61 | cd evaluation && uv sync
62 | source .venv/bin/activate
63 | ```
64 | For node environment, make sure your `node` version is `Node.js >= 20.0.0 and < 24.0.0`.
65 |
66 | Our evaluation results are tested on `[email protected]`, you can change the `claude-context` mcp server setting in the `retrieval/custom.py` file to get the latest version or use a development version.
67 |
68 | 2. **Set Environment Variables**:
69 | ```bash
70 | export OPENAI_API_KEY=your_openai_api_key
71 | export MILVUS_ADDRESS=your_milvus_address
72 | ```
73 | For more configuration details, refer the `claude-context` mcp server settings in the `retrieval/custom.py` file.
74 |
75 | ```bash
76 | export GITHUB_TOKEN=your_github_token
77 | ```
78 | You need also prepare a `GITHUB_TOKEN` for automatically cloning the repositories, refer to [SWE-bench documentation](https://www.swebench.com/SWE-bench/guides/create_rag_datasets/#example-usage) for more details.
79 |
80 | 3. **Generate Dataset**:
81 | ```bash
82 | python generate_subset_json.py
83 | ```
84 |
85 | 4. **Run Baseline Evaluation**:
86 | ```bash
87 | python run_evaluation.py --retrieval_types grep --output_dir retrieval_results_grep
88 | ```
89 |
90 | 5. **Run Enhanced Evaluation**:
91 | ```bash
92 | python run_evaluation.py --retrieval_types cc,grep --output_dir retrieval_results_both
93 | ```
94 |
95 | 6. **Analyze Results**:
96 | ```bash
97 | python analyze_and_plot_mcp_efficiency.py
98 | ```
99 |
100 | The evaluation framework is designed to be reproducible and can be easily extended to test additional configurations or datasets. Due to the proprietary nature of LLMs, exact numerical results may vary between runs and cannot be guaranteed to be identical. However, the core conclusions drawn from the analysis remain consistent and robust across different runs.
101 |
102 | ## Results Visualization
103 |
104 | 
105 |
106 | *The chart above shows the dramatic efficiency improvements achieved by Claude Context MCP. The token usage and tool calls are significantly reduced.*
107 |
108 | ## Case Study
109 |
110 | For detailed analysis of why grep-only approaches have limitations and how semantic search addresses these challenges, please refer to our **[Case Study](./case_study/)** which provides in-depth comparisons and analysis on the this experiment results.
```
--------------------------------------------------------------------------------
/packages/vscode-extension/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Semantic Code Search VSCode Extension
2 |
3 | [](https://marketplace.visualstudio.com/items?itemName=zilliz.semanticcodesearch)
4 |
5 | A code indexing and semantic search VSCode extension powered by [Claude Context](https://github.com/zilliztech/claude-context).
6 |
7 | > 📖 **New to Claude Context?** Check out the [main project README](https://github.com/zilliztech/claude-context/blob/master/README.md) for an overview and setup instructions.
8 |
9 |
10 | 
11 |
12 | ## Features
13 |
14 | - 🔍 **Semantic Search**: Intelligent code search based on semantic understanding, not just keyword matching
15 | - 📁 **Codebase Indexing**: Automatically index entire codebase and build semantic vector database
16 | - 🎯 **Context Search**: Search related code by selecting code snippets
17 | - 🔧 **Multi-platform Support**: Support for OpenAI, VoyageAI, Gemini, and Ollama as embedding providers
18 | - 💾 **Vector Storage**: Integrated with Milvus vector database for efficient storage and retrieval
19 |
20 | ## Requirements
21 |
22 | - **VSCode Version**: 1.74.0 or higher
23 |
24 | ## Installation
25 |
26 | ### From VS Code Marketplace
27 |
28 | 1. **Direct Link**: [Install from VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=zilliz.semanticcodesearch)
29 |
30 | 2. **Manual Search**:
31 | - Open Extensions view in VSCode (Ctrl+Shift+X or Cmd+Shift+X on Mac)
32 | - Search for "Semantic Code Search"
33 | - Click Install
34 |
35 | ## Quick Start
36 |
37 | ### Configuration
38 | The first time you open Claude Context, you need to click on Settings icon to configure the relevant options.
39 |
40 | #### Embedding Configuration
41 | Configure your embedding provider to convert code into semantic vectors.
42 |
43 | **OpenAI Configuration:**
44 | - `Embedding Provider`: Select "OpenAI" from the dropdown
45 | - `Model name`: Choose the embedding model (e.g., `text-embedding-3-small`, `text-embedding-3-large`)
46 | - `OpenAI API key`: Your OpenAI API key for authentication
47 | - `Custom API endpoint URL`: Optional custom endpoint (defaults to `https://api.openai.com/v1`)
48 |
49 | **Other Supported Providers:**
50 | - **Gemini**: Google's state-of-the-art embedding model with Matryoshka representation learning
51 | - **VoyageAI**: Alternative embedding provider with competitive performance
52 | - **Ollama**: For local embedding models
53 |
54 | #### Code Splitter Configuration
55 | Configure how your code is split into chunks for indexing.
56 |
57 | **Splitter Settings:**
58 | - `Splitter Type`: Choose between "AST Splitter" (syntax-aware) or "LangChain Splitter" (character-based)
59 | - `Chunk Size`: Maximum size of each code chunk (default: 1000 characters)
60 | - `Chunk Overlap`: Number of overlapping characters between chunks (default: 200 characters)
61 |
62 | > **Recommendation**: Use AST Splitter for better semantic understanding of code structure.
63 |
64 |
65 | #### Zilliz Cloud configuration
66 | Get a free Milvus vector database on Zilliz Cloud.
67 |
68 | Claude Context needs a vector database. You can [sign up](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=2507-codecontext-readme) on Zilliz Cloud to get a free Serverless cluster.
69 |
70 | 
71 |
72 | After creating your cluster, open your Zilliz Cloud console and copy both the **public endpoint** and your **API key**.
73 | These will be used as `your-zilliz-cloud-public-endpoint` and `your-zilliz-cloud-api-key` in the configuration examples.
74 |
75 | 
76 |
77 | Keep both values handy for the configuration steps below.
78 |
79 | If you need help creating your free vector database or finding these values, see the [Zilliz Cloud documentation](https://docs.zilliz.com/docs/create-cluster) for detailed instructions.
80 |
81 | ```bash
82 | MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint
83 | MILVUS_TOKEN=your-zilliz-cloud-api-key
84 | ```
85 |
86 | ### Usage
87 |
88 | 1. **Set the Configuration**:
89 | - Open VSCode Settings (Ctrl+, or Cmd+, on Mac)
90 | - Search for "Semantic Code Search"
91 | - Set the configuration
92 |
93 | 2. **Index Codebase**:
94 | - Open Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac)
95 | - Run "Semantic Code Search: Index Codebase"
96 |
97 | 3. **Start Searching**:
98 | - Open Semantic Code Search panel in sidebar
99 | - Enter search query or right-click on selected code to search
100 |
101 | ## Commands
102 |
103 | - `Semantic Code Search: Semantic Search` - Perform semantic search
104 | - `Semantic Code Search: Index Codebase` - Index current codebase
105 | - `Semantic Code Search: Clear Index` - Clear the index
106 |
107 | ## Configuration
108 |
109 | - `semanticCodeSearch.embeddingProvider.provider` - Embedding provider (OpenAI/VoyageAI/Gemini/Ollama)
110 | - `semanticCodeSearch.embeddingProvider.model` - Embedding model to use
111 | - `semanticCodeSearch.embeddingProvider.apiKey` - API key for embedding provider
112 | - `semanticCodeSearch.embeddingProvider.baseURL` - Custom API endpoint URL (optional, for OpenAI and Gemini)
113 | - `semanticCodeSearch.embeddingProvider.outputDimensionality` - Output dimension for Gemini (supports 3072, 1536, 768, 256)
114 | - `semanticCodeSearch.milvus.address` - Milvus server address
115 |
116 | ## Contributing
117 |
118 | This VSCode extension is part of the Claude Context monorepo. Please see:
119 | - [Main Contributing Guide](https://github.com/zilliztech/claude-context/blob/master/CONTRIBUTING.md) - General contribution guidelines
120 | - [VSCode Extension Contributing](https://github.com/zilliztech/claude-context/blob/master/packages/vscode-extension/CONTRIBUTING.md) - Specific development guide for this extension
121 |
122 | ## Related Packages
123 |
124 | - **[@zilliz/claude-context-core](https://github.com/zilliztech/claude-context/tree/master/packages/core)** - Core indexing engine used by this extension
125 | - **[@zilliz/claude-context-mcp](https://github.com/zilliztech/claude-context/tree/master/packages/mcp)** - Alternative MCP server integration
126 |
127 | ## Tech Stack
128 |
129 | - TypeScript
130 | - VSCode Extension API
131 | - Milvus Vector Database
132 | - OpenAI/VoyageAI Embeddings
133 |
134 | ## License
135 |
136 | MIT - See [LICENSE](https://github.com/zilliztech/claude-context/blob/master/LICENSE) for details
```
--------------------------------------------------------------------------------
/evaluation/case_study/django_14170/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Django 14170: YearLookup ISO Year Bug
2 |
3 | A comparison showing how both methods(grep + semantic search) outperform grep-based approaches for complex Django ORM bugs.
4 |
5 | <details>
6 | <summary><strong>📋 Original GitHub Issue</strong></summary>
7 |
8 | ## Query optimization in YearLookup breaks filtering by "__iso_year"
9 |
10 | The optimization to use BETWEEN instead of the EXTRACT operation in YearLookup is also registered for the "__iso_year" lookup, which breaks the functionality provided by ExtractIsoYear when used via the lookup.
11 |
12 | **Problem**: When using `__iso_year` filters, the `YearLookup` class applies standard BETWEEN optimization which works for calendar years but fails for ISO week-numbering years.
13 |
14 | **Example**:
15 | ```python
16 | # This should use EXTRACT('isoyear' FROM ...) but incorrectly uses BETWEEN
17 | DTModel.objects.filter(start_date__iso_year=2020)
18 | # Generates: WHERE "start_date" BETWEEN 2020-01-01 AND 2020-12-31
19 | # Should be: WHERE EXTRACT('isoyear' FROM "start_date") = 2020
20 | ```
21 |
22 | **Files**: `django/db/models/lookups.py`, `django/db/backends/base/operations.py`
23 |
24 | </details>
25 |
26 | ## Results
27 |
28 | | Metric | Both Methods | Grep Method | Improvement |
29 | |--------|-------------|-------------|-------------|
30 | | **Token Usage** | 9,036 | 130,819 | **93% less** |
31 | | **Tool Calls** | 3 | 8 | **62% fewer** |
32 | | **Success Rate** | 50% hit | 0% hit | **Much better** |
33 |
34 | ## How Each Method Found the Problem
35 |
36 | ### 🎯 Both Methods
37 |
38 | ```log
39 | 🔧 search_code('YearLookup')
40 | ⚙️ Found 10 results for query: "YearLookup" in codebase
41 | 1. Code snippet (python) [repo__django__django]
42 | Location: django/db/models/lookups.py:568-577
43 | Context: YearExact class with get_bound_params method
44 | 2. Code snippet (python) [repo__django__django]
45 | Location: django/db/models/lookups.py:538-569
46 | Context: YearLookup base class with year_lookup_bounds method
47 |
48 | 🔧 edit_file(django/db/models/lookups.py)
49 | ⚙️ Arguments: {'file_path': 'django/db/models/lookups.py',
50 | 'old_string': 'def get_direct_rhs_sql(self, connection, rhs):\n return connection.operators[self.lookup_name] % rhs',
51 | 'new_string': "def get_direct_rhs_sql(self, connection, rhs):\n if self.lookup_name == '__iso_year':\n return 'EXTRACT(ISOYEAR FROM %s)' % rhs\n return connection.operators[self.lookup_name] % rhs"}
52 | Result: Successfully modified file
53 |
54 | 🔧 edit_file(django/db/models/lookups.py)
55 | ⚙️ Arguments: {'file_path': 'django/db/models/lookups.py',
56 | 'old_string': 'def year_lookup_bounds(self, connection, year):',
57 | 'new_string': "def year_lookup_bounds(self, connection, year):\n if self.lookup_name == '__iso_year':\n return (year - 1, year)"}
58 | Result: Successfully modified file
59 | ```
60 |
61 | **Key Success**: Semantic search immediately understood "YearLookup" as the core concept and found the exact classes that needed modification.
62 |
63 | ### 🔍 Grep Method
64 |
65 | ```log
66 | 🔧 directory_tree()
67 | ⚙️ Arguments: {'path': 'repo__django__django'}
68 | Result: Retrieved 3000+ lines of directory structure (~50k tokens)
69 | Problem: Massive information overload, no direct relevance
70 |
71 | 🔧 search_text('ExtractIsoYear')
72 | ⚙️ Arguments: {'pattern': 'ExtractIsoYear', 'path': 'repo__django__django'}
73 | Result: Found 21 matches across multiple files:
74 | - django/db/models/functions/__init__.py:5 (import statement)
75 | - django/db/models/functions/__init__.py:31 (export list)
76 | - django/db/models/functions/datetime.py:93 (class ExtractIsoYear)
77 | - django/db/models/functions/datetime.py:150 (DateField.register_lookup)
78 | Problem: Most were irrelevant imports and registrations
79 |
80 | 🔧 edit_file('django/db/models/functions/datetime.py')
81 | ⚙️ Arguments: {'old_string': 'ExtractIsoYear.register_lookup(YearExact)', 'new_string': '# ExtractIsoYear.register_lookup(YearExact)'}
82 | Result: Successfully modified file
83 |
84 | 🔧 edit_file('django/db/models/functions/datetime.py')
85 | ⚙️ Arguments: {'old_string': 'ExtractIsoYear.register_lookup(YearGt)', 'new_string': '# ExtractIsoYear.register_lookup(YearGt)'}
86 | Result: Successfully modified file
87 |
88 | 🔧 edit_file('django/db/models/functions/datetime.py')
89 | ⚙️ Arguments: {'old_string': 'ExtractIsoYear.register_lookup(YearGte)', 'new_string': '# ExtractIsoYear.register_lookup(YearGte)'}
90 | Result: Successfully modified file
91 |
92 | 🔧 edit_file('django/db/models/functions/datetime.py')
93 | ⚙️ Arguments: {'old_string': 'ExtractIsoYear.register_lookup(YearLt)', 'new_string': '# ExtractIsoYear.register_lookup(YearLt)'}
94 | Result: Successfully modified file
95 |
96 | 🔧 edit_file('django/db/models/functions/datetime.py')
97 | ⚙️ Arguments: {'old_string': 'ExtractIsoYear.register_lookup(YearLte)', 'new_string': '# ExtractIsoYear.register_lookup(YearLte)'}
98 | Result: Successfully modified file
99 |
100 | 🔧 edit_file('tests/db_functions/datetime/test_extract_trunc.py')
101 | ⚙️ Arguments: {'old_string': "self.assertEqual(DTModel.objects.filter(start_datetime__iso_year=ExtractIsoYear('start_datetime')).count(), 2)", 'new_string': "# self.assertEqual(DTModel.objects.filter(start_datetime__iso_year=ExtractIsoYear('start_datetime')).count(), 2)"}
102 | Result: Successfully modified file
103 | ```
104 |
105 | **Key Failure**: Text search focused on wrong components (ExtractIsoYear registrations) instead of the actual optimization logic (YearLookup class).
106 |
107 | ## Why Grep + Semantic Search Won
108 |
109 | 1. **Conceptual Understanding**: Recognized "YearLookup" as the optimization mechanism causing the issue
110 | 2. **Direct Navigation**: Immediately found the relevant classes without noise
111 | 3. **Root Cause Focus**: Identified the boundary calculation logic that needed ISO year awareness
112 | 4. **Efficient Execution**: 3 targeted operations vs 8 scattered attempts
113 |
114 | ## Why Grep Failed
115 |
116 | 1. **Information Overload**: Wasted 50k tokens on irrelevant directory structure
117 | 2. **Surface-Level Matching**: Focused on "ExtractIsoYear" strings instead of understanding the optimization conflict
118 | 3. **Wrong Solution**: Applied superficial fixes (commenting registrations) instead of addressing the core logic
119 | 4. **No Context**: Couldn't understand the relationship between YearLookup optimization and ISO year boundaries
120 |
121 | The semantic approach understood that the issue was about **optimization logic**, not just **ISO year functionality**, leading to the correct architectural fix.
122 |
123 | ## Files
124 |
125 | - [`both_conversation.log`](./both_conversation.log) - Both methods interaction log
126 | - [`grep_conversation.log`](./grep_conversation.log) - Grep method interaction log
127 | - [`both_result.json`](./both_result.json) - Both methods performance metrics
128 | - [`grep_result.json`](./grep_result.json) - Grep method performance metrics
```
--------------------------------------------------------------------------------
/evaluation/case_study/pydata_xarray_6938/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Xarray 6938: swap_dims() Mutation Bug
2 |
3 | A case study showing how both methods(grep + semantic search) efficiently identify object mutation bugs in scientific computing libraries.
4 |
5 | <details>
6 | <summary><strong>📋 Original GitHub Issue</strong></summary>
7 |
8 | ## `.swap_dims()` can modify original object
9 |
10 | **Problem**: In certain cases, `.swap_dims()` modifies the original object instead of returning a new one, violating immutability expectations.
11 |
12 | **Example**:
13 | ```python
14 | import numpy as np
15 | import xarray as xr
16 |
17 | nz = 11
18 | ds = xr.Dataset({
19 | "y": ("z", np.random.rand(nz)),
20 | "lev": ("z", np.arange(nz) * 10),
21 | })
22 |
23 | # This should not modify ds, but it does
24 | ds2 = ds.swap_dims(z="lev").rename_dims(lev="z").reset_index("lev").reset_coords()
25 | ds2.swap_dims(z='lev') # This modifies ds2['lev'] unexpectedly
26 |
27 | # ds2['lev'] now has dimension 'lev' instead of 'z'
28 | ```
29 |
30 | **Expected**: Original objects should remain unchanged after swap_dims operations.
31 | **Actual**: Original object's internal state gets modified during dimension swapping.
32 |
33 | **Files**: `xarray/core/dataset.py`, `xarray/core/variable.py`
34 |
35 | </details>
36 |
37 | ## Results
38 |
39 | | Metric | Both Methods | Grep Method | Improvement |
40 | |--------|-------------|-------------|-------------|
41 | | **Token Usage** | 15,826 | 41,999 | **62% less** |
42 | | **Tool Calls** | 3 | 11 | **73% fewer** |
43 | | **Success Rate** | 50% hit | 50% hit | **Equal accuracy** |
44 |
45 | ## How Each Method Found the Problem
46 |
47 | ### 🎯 Both Methods
48 |
49 | ```log
50 | 🔧 search_code('.swap_dims()')
51 | ⚙️ Arguments: {'path': 'repo__pydata__xarray', 'query': '.swap_dims()', 'limit': 10}
52 | Result: Found 10 results for query: ".swap_dims()" in codebase
53 | 1. Code snippet (python) [repo__pydata__xarray]
54 | Location: xarray/tests/test_formatting_html.py:67-76
55 | 2. Code snippet (python) [repo__pydata__xarray]
56 | Location: xarray/tests/test_dataset.py:2926-2979
57 |
58 | 🔧 edit_file('xarray/core/dataset.py')
59 | ⚙️ Arguments: {'old_string': 'result_dims = {dims_dict.get(dim, dim) for dim in self.dims}', 'new_string': 'result_dims = {dims_dict.get(dim, dim) for dim in self.dims if dim in dims_dict or dim not in self.variables}'}
60 | Result: Successfully modified file
61 |
62 | 🔧 edit_file('xarray/core/dataarray.py')
63 | ⚙️ Arguments: {'old_string': 'ds = self._to_temp_dataset().swap_dims(dims_dict)', 'new_string': 'ds = self._to_temp_dataset().swap_dims(dims_dict) # Ensure that ds does not modify the original DataArray'}
64 | Result: Successfully modified file
65 | ```
66 |
67 | **Key Success**: Semantic search immediately located the actual `swap_dims()` implementations and understood the functional context.
68 |
69 | ### 🔍 Grep Method
70 |
71 | ```log
72 | 🔧 list_directory('repo__pydata__xarray')
73 | ⚙️ Result: Retrieved directory structure with multiple subdirectories
74 | Problem: Basic directory navigation without targeted search
75 |
76 | 🔧 list_directory('repo__pydata__xarray/xarray')
77 | ⚙️ Result: Found core directories: backends, coding, core, plot, static, tests
78 |
79 | 🔧 list_directory('repo__pydata__xarray/xarray/core')
80 | ⚙️ Result: Found 50+ Python files including dataset.py, dataarray.py, variable.py
81 |
82 | 🔧 search_text('swap_dims')
83 | ⚙️ Arguments: {'pattern': 'swap_dims', 'path': 'repo__pydata__xarray/xarray/core', 'include': '*.py'}
84 | Result: Found 21 matches across core files:
85 | - xarray/core/common.py:600 (Dataset.swap_dims reference)
86 | - xarray/core/dataarray.py:753 (".rename() or .swap_dims() instead.")
87 | - xarray/core/dataarray.py:2026 (DataArray.swap_dims reference)
88 | - xarray/core/dataarray.py:2044 (def swap_dims method)
89 | Problem: Many matches across different contexts
90 |
91 | 🔧 read_file('xarray/core/dataarray.py', offset=2000, limit=40)
92 | ⚙️ Result: Read lines 2001-2040 showing rename method documentation
93 |
94 | 🔧 read_file('xarray/core/dataset.py', offset=3600, limit=40)
95 | ⚙️ Result: Read lines 3601-3640 showing rename_dims method
96 |
97 | 🔧 read_file('xarray/core/common.py', offset=590, limit=10)
98 | ⚙️ Result: Read lines 591-600 showing assign_coords documentation
99 |
100 | 🔧 edit_file('xarray/core/dataarray.py')
101 | ⚙️ Arguments: {'old_string': ' def swap_dims(', 'new_string': ' def swap_dims(self, dims_dict: Mapping[str, str] | None = None, **dims: str) -> DataArray:\n """Returns a new DataArray with swapped dimensions..."""'}
102 | Result: Successfully modified file
103 |
104 | 🔧 edit_file('xarray/core/dataset.py')
105 | ⚙️ Arguments: {'old_string': ' def swap_dims(', 'new_string': ' def swap_dims(self, dims_dict: Mapping[str, str] | None = None, **dims: str) -> Dataset:\n """Returns a new Dataset with swapped dimensions..."""'}
106 | Result: Successfully modified file
107 |
108 | 🔧 edit_file('xarray/core/common.py')
109 | ⚙️ Arguments: {'old_string': 'Dataset.swap_dims', 'new_string': '# The swap_dims method is being used here without modification, so ensure appropriate usage.'}
110 | Result: Successfully modified file
111 | ```
112 |
113 | **Key Inefficiency**: Used massive list_directory and read_file operations, instead of focusing on relevant methods.
114 |
115 | ## Why Grep + Semantic Search Won
116 |
117 | 1. **Method-Level Understanding**: Recognized `.swap_dims()` as a specific method with defined behavior
118 | 2. **Functional Context**: Understood the relationship between Dataset, DataArray, and Variable classes
119 | 3. **Efficient Navigation**: Directly located method implementations without searching through tests and docs
120 | 4. **Mutation Awareness**: Connected the symptom (unexpected changes) to likely causes (shared references)
121 |
122 | ## Why Grep Was Less Efficient
123 |
124 | 1. **Information Overload**: Generated hundreds of matches for common terms like 'swap_dims' and 'dimension'
125 | 2. **Context Loss**: Treated method names as text strings rather than functional concepts
126 | 3. **Inefficient Reading**: Required reading large portions of files to understand basic functionality
127 |
128 | ## Key Insights
129 |
130 | **Semantic Search Advantages**:
131 | - **Concept Recognition**: Understands `.swap_dims()` as a method concept, not just text
132 | - **Relationship Mapping**: Automatically connects related classes and methods
133 | - **Relevance Filtering**: Prioritizes implementation code over tests and documentation
134 | - **Efficiency**: Achieves same accuracy with 62% fewer tokens and 73% fewer operations
135 |
136 | **Traditional Search Limitations**:
137 | - **Text Literalism**: Treats code as text without understanding semantic meaning
138 | - **Noise Generation**: Produces excessive irrelevant matches across different contexts
139 | - **Resource Waste**: Consumes 2.6x more computational resources for equivalent results
140 | - **Scalability Issues**: Becomes increasingly inefficient with larger codebases
141 |
142 | This case demonstrates semantic search's particular value for scientific computing libraries where **data integrity** is paramount and **mutation bugs** can corrupt research results.
143 |
144 | ## Files
145 |
146 | - [`both_conversation.log`](./both_conversation.log) - Both methods interaction log
147 | - [`grep_conversation.log`](./grep_conversation.log) - Grep method interaction log
148 | - [`both_result.json`](./both_result.json) - Both methods performance metrics
149 | - [`grep_result.json`](./grep_result.json) - Grep method performance metrics
```
--------------------------------------------------------------------------------
/packages/core/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # @zilliz/claude-context-core
2 | 
3 |
4 | The core indexing engine for Claude Context - a powerful tool for semantic search and analysis of codebases using vector embeddings and AI.
5 |
6 | [](https://www.npmjs.com/package/@zilliz/claude-context-core)
7 | [](https://www.npmjs.com/package/@zilliz/claude-context-core)
8 |
9 | > 📖 **New to Claude Context?** Check out the [main project README](../../README.md) for an overview and quick start guide.
10 |
11 | ## Installation
12 |
13 | ```bash
14 | npm install @zilliz/claude-context-core
15 | ```
16 |
17 | ### Prepare Environment Variables
18 | #### OpenAI API key
19 | See [OpenAI Documentation](https://platform.openai.com/docs/api-reference) for more details to get your API key.
20 | ```bash
21 | OPENAI_API_KEY=your-openai-api-key
22 | ```
23 |
24 | #### Zilliz Cloud configuration
25 | Get a free Milvus vector database on Zilliz Cloud.
26 |
27 | Claude Context needs a vector database. You can [sign up](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=2507-codecontext-readme) on Zilliz Cloud to get a free Serverless cluster.
28 |
29 | 
30 |
31 | After creating your cluster, open your Zilliz Cloud console and copy both the **public endpoint** and your **API key**.
32 | These will be used as `your-zilliz-cloud-public-endpoint` and `your-zilliz-cloud-api-key` in the configuration examples.
33 |
34 | 
35 |
36 | Keep both values handy for the configuration steps below.
37 |
38 | If you need help creating your free vector database or finding these values, see the [Zilliz Cloud documentation](https://docs.zilliz.com/docs/create-cluster) for detailed instructions.
39 |
40 | ```bash
41 | MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint
42 | MILVUS_TOKEN=your-zilliz-cloud-api-key
43 | ```
44 |
45 | > 💡 **Tip**: For easier configuration management across different usage scenarios, consider using [global environment variables](../../docs/getting-started/environment-variables.md).
46 |
47 | ## Quick Start
48 |
49 | ```typescript
50 | import {
51 | Context,
52 | OpenAIEmbedding,
53 | MilvusVectorDatabase
54 | } from '@zilliz/claude-context-core';
55 |
56 | // Initialize embedding provider
57 | const embedding = new OpenAIEmbedding({
58 | apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',
59 | model: 'text-embedding-3-small'
60 | });
61 |
62 | // Initialize vector database
63 | const vectorDatabase = new MilvusVectorDatabase({
64 | address: process.env.MILVUS_ADDRESS || 'localhost:19530',
65 | token: process.env.MILVUS_TOKEN || ''
66 | });
67 |
68 | // Create context instance
69 | const context = new Context({
70 | embedding,
71 | vectorDatabase
72 | });
73 |
74 | // Index a codebase
75 | const stats = await context.indexCodebase('./my-project', (progress) => {
76 | console.log(`${progress.phase} - ${progress.percentage}%`);
77 | });
78 |
79 | console.log(`Indexed ${stats.indexedFiles} files with ${stats.totalChunks} chunks`);
80 |
81 | // Search the codebase
82 | const results = await context.semanticSearch(
83 | './my-project',
84 | 'function that handles user authentication',
85 | 5
86 | );
87 |
88 | results.forEach(result => {
89 | console.log(`${result.relativePath}:${result.startLine}-${result.endLine}`);
90 | console.log(`Score: ${result.score}`);
91 | console.log(result.content);
92 | });
93 | ```
94 |
95 | ## Features
96 |
97 | - **Multi-language Support**: Index TypeScript, JavaScript, Python, Java, C++, and many other programming languages
98 | - **Semantic Search**: Find code using natural language queries powered by AI embeddings
99 | - **Flexible Architecture**: Pluggable embedding providers and vector databases
100 | - **Smart Chunking**: Intelligent code splitting that preserves context and structure
101 | - **Batch Processing**: Efficient processing of large codebases with progress tracking
102 | - **Pattern Matching**: Built-in ignore patterns for common build artifacts and dependencies
103 | - **Incremental File Synchronization**: Efficient change detection using Merkle trees to only re-index modified files
104 |
105 | ## Embedding Providers
106 |
107 | - **OpenAI Embeddings** (`text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`)
108 | - **VoyageAI Embeddings** - High-quality embeddings optimized for code (`voyage-code-3`, `voyage-3.5`, etc.)
109 | - **Gemini Embeddings** - Google's embedding models (`gemini-embedding-001`)
110 | - **Ollama Embeddings** - Local embedding models via Ollama
111 |
112 | ## Vector Database Support
113 |
114 | - **Milvus/Zilliz Cloud** - High-performance vector database
115 |
116 | ## Code Splitters
117 |
118 | - **AST Code Splitter** - AST-based code splitting with automatic fallback (default)
119 | - **LangChain Code Splitter** - Character-based code chunking
120 |
121 | ## Configuration
122 |
123 | ### ContextConfig
124 |
125 | ```typescript
126 | interface ContextConfig {
127 | embedding?: Embedding; // Embedding provider
128 | vectorDatabase?: VectorDatabase; // Vector database instance (required)
129 | codeSplitter?: Splitter; // Code splitting strategy
130 | supportedExtensions?: string[]; // File extensions to index
131 | ignorePatterns?: string[]; // Patterns to ignore
132 | customExtensions?: string[]; // Custom extensions from MCP
133 | customIgnorePatterns?: string[]; // Custom ignore patterns from MCP
134 | }
135 | ```
136 |
137 | ### Supported File Extensions (Default)
138 |
139 | ```typescript
140 | [
141 | // Programming languages
142 | '.ts', '.tsx', '.js', '.jsx', '.py', '.java', '.cpp', '.c', '.h', '.hpp',
143 | '.cs', '.go', '.rs', '.php', '.rb', '.swift', '.kt', '.scala', '.m', '.mm',
144 | // Text and markup files
145 | '.md', '.markdown', '.ipynb'
146 | ]
147 | ```
148 |
149 | ### Default Ignore Patterns
150 |
151 | - Build and dependency directories: `node_modules/**`, `dist/**`, `build/**`, `out/**`, `target/**`
152 | - Version control: `.git/**`, `.svn/**`, `.hg/**`
153 | - IDE files: `.vscode/**`, `.idea/**`, `*.swp`, `*.swo`
154 | - Cache directories: `.cache/**`, `__pycache__/**`, `.pytest_cache/**`, `coverage/**`
155 | - Minified files: `*.min.js`, `*.min.css`, `*.bundle.js`, `*.map`
156 | - Log and temp files: `logs/**`, `tmp/**`, `temp/**`, `*.log`
157 | - Environment files: `.env`, `.env.*`, `*.local`
158 |
159 | ## API Reference
160 |
161 | ### Context
162 |
163 | #### Methods
164 |
165 | - `indexCodebase(path, progressCallback?, forceReindex?)` - Index an entire codebase
166 | - `reindexByChange(path, progressCallback?)` - Incrementally re-index only changed files
167 | - `semanticSearch(path, query, topK?, threshold?, filterExpr?)` - Search indexed code semantically
168 | - `hasIndex(path)` - Check if codebase is already indexed
169 | - `clearIndex(path, progressCallback?)` - Remove index for a codebase
170 | - `updateIgnorePatterns(patterns)` - Update ignore patterns
171 | - `addCustomIgnorePatterns(patterns)` - Add custom ignore patterns
172 | - `addCustomExtensions(extensions)` - Add custom file extensions
173 | - `updateEmbedding(embedding)` - Switch embedding provider
174 | - `updateVectorDatabase(vectorDB)` - Switch vector database
175 | - `updateSplitter(splitter)` - Switch code splitter
176 |
177 | ### Search Results
178 |
179 | ```typescript
180 | interface SemanticSearchResult {
181 | content: string; // Code content
182 | relativePath: string; // File path relative to codebase root
183 | startLine: number; // Starting line number
184 | endLine: number; // Ending line number
185 | language: string; // Programming language
186 | score: number; // Similarity score (0-1)
187 | }
188 | ```
189 |
190 |
191 | ## Examples
192 |
193 | ### Using VoyageAI Embeddings
194 |
195 | ```typescript
196 | import { Context, MilvusVectorDatabase, VoyageAIEmbedding } from '@zilliz/claude-context-core';
197 |
198 | // Initialize with VoyageAI embedding provider
199 | const embedding = new VoyageAIEmbedding({
200 | apiKey: process.env.VOYAGEAI_API_KEY || 'your-voyageai-api-key',
201 | model: 'voyage-code-3'
202 | });
203 |
204 | const vectorDatabase = new MilvusVectorDatabase({
205 | address: process.env.MILVUS_ADDRESS || 'localhost:19530',
206 | token: process.env.MILVUS_TOKEN || ''
207 | });
208 |
209 | const context = new Context({
210 | embedding,
211 | vectorDatabase
212 | });
213 | ```
214 |
215 | ### Custom File Filtering
216 |
217 | ```typescript
218 | const context = new Context({
219 | embedding,
220 | vectorDatabase,
221 | supportedExtensions: ['.ts', '.js', '.py', '.java'],
222 | ignorePatterns: [
223 | 'node_modules/**',
224 | 'dist/**',
225 | '*.spec.ts',
226 | '*.test.js'
227 | ]
228 | });
229 | ```
230 |
231 | ## File Synchronization Architecture
232 |
233 | Claude Context implements an intelligent file synchronization system that efficiently tracks and processes only the files that have changed since the last indexing operation. This dramatically improves performance when working with large codebases.
234 |
235 | 
236 |
237 | ### How It Works
238 |
239 | The file synchronization system uses a **Merkle tree-based approach** combined with SHA-256 file hashing to detect changes:
240 |
241 | #### 1. File Hashing
242 | - Each file in the codebase is hashed using SHA-256
243 | - File hashes are computed based on file content, not metadata
244 | - Hashes are stored with relative file paths for consistency across different environments
245 |
246 | #### 2. Merkle Tree Construction
247 | - All file hashes are organized into a Merkle tree structure
248 | - The tree provides a single root hash that represents the entire codebase state
249 | - Any change to any file will cause the root hash to change
250 |
251 | #### 3. Snapshot Management
252 | - File synchronization state is persisted to `~/.context/merkle/` directory
253 | - Each codebase gets a unique snapshot file based on its absolute path hash
254 | - Snapshots contain both file hashes and serialized Merkle tree data
255 |
256 | #### 4. Change Detection Process
257 | 1. **Quick Check**: Compare current Merkle root hash with stored snapshot
258 | 2. **Detailed Analysis**: If root hashes differ, perform file-by-file comparison
259 | 3. **Change Classification**: Categorize changes into three types:
260 | - **Added**: New files that didn't exist before
261 | - **Modified**: Existing files with changed content
262 | - **Removed**: Files that were deleted from the codebase
263 |
264 | #### 5. Incremental Updates
265 | - Only process files that have actually changed
266 | - Update vector database entries only for modified chunks
267 | - Remove entries for deleted files
268 | - Add entries for new files
269 |
270 |
271 | ## Contributing
272 |
273 | This package is part of the Claude Context monorepo. Please see:
274 | - [Main Contributing Guide](../../CONTRIBUTING.md) - General contribution guidelines
275 | - [Core Package Contributing](CONTRIBUTING.md) - Specific development guide for this package
276 |
277 | ## Related Packages
278 |
279 | - **[@claude-context/mcp](../mcp)** - MCP server that uses this core engine
280 | - **[VSCode Extension](../vscode-extension)** - VSCode extension built on this core
281 |
282 |
283 | ## License
284 |
285 | MIT - See [LICENSE](../../LICENSE) for details
```
--------------------------------------------------------------------------------
/packages/mcp/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # @zilliz/claude-context-mcp
2 |
3 | 
4 | Model Context Protocol (MCP) integration for Claude Context - A powerful MCP server that enables AI assistants and agents to index and search codebases using semantic search.
5 |
6 | [](https://www.npmjs.com/package/@zilliz/claude-context-mcp)
7 | [](https://www.npmjs.com/package/@zilliz/claude-context-mcp)
8 |
9 | > 📖 **New to Claude Context?** Check out the [main project README](../../README.md) for an overview and setup instructions.
10 |
11 | ## 🚀 Use Claude Context as MCP in Claude Code and others
12 |
13 | 
14 |
15 | Model Context Protocol (MCP) allows you to integrate Claude Context with your favorite AI coding assistants, e.g. Claude Code.
16 |
17 | ## Quick Start
18 |
19 | ### Prerequisites
20 |
21 | Before using the MCP server, make sure you have:
22 |
23 | - API key for your chosen embedding provider (OpenAI, VoyageAI, Gemini, or Ollama setup)
24 | - Milvus vector database (local or cloud)
25 |
26 | > 💡 **Setup Help:** See the [main project setup guide](../../README.md#-quick-start) for detailed installation instructions.
27 |
28 | ### Prepare Environment Variables
29 |
30 | #### Embedding Provider Configuration
31 |
32 | Claude Context MCP supports multiple embedding providers. Choose the one that best fits your needs:
33 |
34 | > 📋 **Quick Reference**: For a complete list of environment variables and their descriptions, see the [Environment Variables Guide](../../docs/getting-started/environment-variables.md).
35 |
36 | ```bash
37 | # Supported providers: OpenAI, VoyageAI, Gemini, Ollama
38 | EMBEDDING_PROVIDER=OpenAI
39 | ```
40 |
41 | <details>
42 | <summary><strong>1. OpenAI Configuration (Default)</strong></summary>
43 |
44 | OpenAI provides high-quality embeddings with excellent performance for code understanding.
45 |
46 | ```bash
47 | # Required: Your OpenAI API key
48 | OPENAI_API_KEY=sk-your-openai-api-key
49 |
50 | # Optional: Specify embedding model (default: text-embedding-3-small)
51 | EMBEDDING_MODEL=text-embedding-3-small
52 |
53 | # Optional: Custom API base URL (for Azure OpenAI or other compatible services)
54 | OPENAI_BASE_URL=https://api.openai.com/v1
55 | ```
56 |
57 | **Available Models:**
58 | See `getSupportedModels` in [`openai-embedding.ts`](https://github.com/zilliztech/claude-context/blob/master/packages/core/src/embedding/openai-embedding.ts) for the full list of supported models.
59 |
60 | **Getting API Key:**
61 |
62 | 1. Visit [OpenAI Platform](https://platform.openai.com/api-keys)
63 | 2. Sign in or create an account
64 | 3. Generate a new API key
65 | 4. Set up billing if needed
66 |
67 | </details>
68 |
69 | <details>
70 | <summary><strong>2. VoyageAI Configuration</strong></summary>
71 |
72 | VoyageAI offers specialized code embeddings optimized for programming languages.
73 |
74 | ```bash
75 | # Required: Your VoyageAI API key
76 | VOYAGEAI_API_KEY=pa-your-voyageai-api-key
77 |
78 | # Optional: Specify embedding model (default: voyage-code-3)
79 | EMBEDDING_MODEL=voyage-code-3
80 | ```
81 |
82 | **Available Models:**
83 | See `getSupportedModels` in [`voyageai-embedding.ts`](https://github.com/zilliztech/claude-context/blob/master/packages/core/src/embedding/voyageai-embedding.ts) for the full list of supported models.
84 |
85 | **Getting API Key:**
86 |
87 | 1. Visit [VoyageAI Console](https://dash.voyageai.com/)
88 | 2. Sign up for an account
89 | 3. Navigate to API Keys section
90 | 4. Create a new API key
91 |
92 | </details>
93 |
94 | <details>
95 | <summary><strong>3. Gemini Configuration</strong></summary>
96 |
97 | Google's Gemini provides competitive embeddings with good multilingual support.
98 |
99 | ```bash
100 | # Required: Your Gemini API key
101 | GEMINI_API_KEY=your-gemini-api-key
102 |
103 | # Optional: Specify embedding model (default: gemini-embedding-001)
104 | EMBEDDING_MODEL=gemini-embedding-001
105 |
106 | # Optional: Custom API base URL (for custom endpoints)
107 | GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
108 | ```
109 |
110 | **Available Models:**
111 | See `getSupportedModels` in [`gemini-embedding.ts`](https://github.com/zilliztech/claude-context/blob/master/packages/core/src/embedding/gemini-embedding.ts) for the full list of supported models.
112 |
113 | **Getting API Key:**
114 |
115 | 1. Visit [Google AI Studio](https://aistudio.google.com/)
116 | 2. Sign in with your Google account
117 | 3. Go to "Get API key" section
118 | 4. Create a new API key
119 |
120 | </details>
121 |
122 | <details>
123 | <summary><strong>4. Ollama Configuration (Local/Self-hosted)</strong></summary>
124 |
125 | Ollama allows you to run embeddings locally without sending data to external services.
126 |
127 | ```bash
128 | # Required: Specify which Ollama model to use
129 | EMBEDDING_MODEL=nomic-embed-text
130 |
131 | # Optional: Specify Ollama host (default: http://127.0.0.1:11434)
132 | OLLAMA_HOST=http://127.0.0.1:11434
133 | ```
134 |
135 | **Setup Instructions:**
136 |
137 | 1. Install Ollama from [ollama.ai](https://ollama.ai/)
138 | 2. Pull the embedding model:
139 |
140 | ```bash
141 | ollama pull nomic-embed-text
142 | ```
143 |
144 | 3. Ensure Ollama is running:
145 |
146 | ```bash
147 | ollama serve
148 | ```
149 |
150 | </details>
151 |
152 | #### Get a free vector database on Zilliz Cloud
153 |
154 | Claude Context needs a vector database. You can [sign up](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=2507-codecontext-readme) on Zilliz Cloud to get an API key.
155 |
156 | 
157 |
158 | Copy your Personal Key to replace `your-zilliz-cloud-api-key` in the configuration examples.
159 |
160 | ```bash
161 | MILVUS_TOKEN=your-zilliz-cloud-api-key
162 | ```
163 |
164 | #### Embedding Batch Size
165 |
166 | You can set the embedding batch size to optimize the performance of the MCP server, depending on your embedding model throughput. The default value is 100.
167 |
168 | ```bash
169 | EMBEDDING_BATCH_SIZE=512
170 | ```
171 |
172 | #### Custom File Processing (Optional)
173 |
174 | You can configure custom file extensions and ignore patterns globally via environment variables:
175 |
176 | ```bash
177 | # Additional file extensions to include beyond defaults
178 | CUSTOM_EXTENSIONS=.vue,.svelte,.astro,.twig
179 |
180 | # Additional ignore patterns to exclude files/directories
181 | CUSTOM_IGNORE_PATTERNS=temp/**,*.backup,private/**,uploads/**
182 | ```
183 |
184 | These settings work in combination with tool parameters - patterns from both sources will be merged together.
185 |
186 | ## Usage with MCP Clients
187 |
188 | <details>
189 | <summary><strong>Claude Code</strong></summary>
190 |
191 | Use the command line interface to add the Claude Context MCP server:
192 |
193 | ```bash
194 | # Add the Claude Context MCP server
195 | 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
196 |
197 | ```
198 |
199 | See the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for more details about MCP server management.
200 |
201 | </details>
202 |
203 | <details>
204 | <summary><strong>OpenAI Codex CLI</strong></summary>
205 |
206 | Codex CLI uses TOML configuration files:
207 |
208 | 1. Create or edit the `~/.codex/config.toml` file.
209 |
210 | 2. Add the following configuration:
211 |
212 | ```toml
213 | # IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
214 | [mcp_servers.claude-context]
215 | command = "npx"
216 | args = ["@zilliz/claude-context-mcp@latest"]
217 | env = { "OPENAI_API_KEY" = "your-openai-api-key", "MILVUS_TOKEN" = "your-zilliz-cloud-api-key" }
218 | # Optional: override the default 10s startup timeout
219 | startup_timeout_ms = 20000
220 | ```
221 |
222 | 3. Save the file and restart Codex CLI to apply the changes.
223 |
224 | </details>
225 |
226 | <details>
227 | <summary><strong>Gemini CLI</strong></summary>
228 |
229 | Gemini CLI requires manual configuration through a JSON file:
230 |
231 | 1. Create or edit the `~/.gemini/settings.json` file.
232 |
233 | 2. Add the following configuration:
234 |
235 | ```json
236 | {
237 | "mcpServers": {
238 | "claude-context": {
239 | "command": "npx",
240 | "args": ["@zilliz/claude-context-mcp@latest"],
241 | "env": {
242 | "OPENAI_API_KEY": "your-openai-api-key",
243 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
244 | }
245 | }
246 | }
247 | }
248 | ```
249 |
250 | 3. Save the file and restart Gemini CLI to apply the changes.
251 |
252 | </details>
253 |
254 | <details>
255 | <summary><strong>Qwen Code</strong></summary>
256 |
257 | Create or edit the `~/.qwen/settings.json` file and add the following configuration:
258 |
259 | ```json
260 | {
261 | "mcpServers": {
262 | "claude-context": {
263 | "command": "npx",
264 | "args": ["@zilliz/claude-context-mcp@latest"],
265 | "env": {
266 | "OPENAI_API_KEY": "your-openai-api-key",
267 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
268 | }
269 | }
270 | }
271 | }
272 | ```
273 |
274 | </details>
275 |
276 | <details>
277 | <summary><strong>Cursor</strong></summary>
278 |
279 | Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`
280 |
281 | Pasting the following configuration into your Cursor `~/.cursor/mcp.json` file is the recommended approach. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.
282 |
283 | **OpenAI Configuration (Default):**
284 |
285 | ```json
286 | {
287 | "mcpServers": {
288 | "claude-context": {
289 | "command": "npx",
290 | "args": ["-y", "@zilliz/claude-context-mcp@latest"],
291 | "env": {
292 | "EMBEDDING_PROVIDER": "OpenAI",
293 | "OPENAI_API_KEY": "your-openai-api-key",
294 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
295 | }
296 | }
297 | }
298 | }
299 | ```
300 |
301 | **VoyageAI Configuration:**
302 |
303 | ```json
304 | {
305 | "mcpServers": {
306 | "claude-context": {
307 | "command": "npx",
308 | "args": ["-y", "@zilliz/claude-context-mcp@latest"],
309 | "env": {
310 | "EMBEDDING_PROVIDER": "VoyageAI",
311 | "VOYAGEAI_API_KEY": "your-voyageai-api-key",
312 | "EMBEDDING_MODEL": "voyage-code-3",
313 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
314 | }
315 | }
316 | }
317 | }
318 | ```
319 |
320 | **Gemini Configuration:**
321 |
322 | ```json
323 | {
324 | "mcpServers": {
325 | "claude-context": {
326 | "command": "npx",
327 | "args": ["-y", "@zilliz/claude-context-mcp@latest"],
328 | "env": {
329 | "EMBEDDING_PROVIDER": "Gemini",
330 | "GEMINI_API_KEY": "your-gemini-api-key",
331 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
332 | }
333 | }
334 | }
335 | }
336 | ```
337 |
338 | **Ollama Configuration:**
339 |
340 | ```json
341 | {
342 | "mcpServers": {
343 | "claude-context": {
344 | "command": "npx",
345 | "args": ["-y", "@zilliz/claude-context-mcp@latest"],
346 | "env": {
347 | "EMBEDDING_PROVIDER": "Ollama",
348 | "EMBEDDING_MODEL": "nomic-embed-text",
349 | "OLLAMA_HOST": "http://127.0.0.1:11434",
350 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
351 | }
352 | }
353 | }
354 | }
355 | ```
356 |
357 | </details>
358 |
359 | <details>
360 | <summary><strong>Void</strong></summary>
361 |
362 | Go to: `Settings` -> `MCP` -> `Add MCP Server`
363 |
364 | Add the following configuration to your Void MCP settings:
365 |
366 | ```json
367 | {
368 | "mcpServers": {
369 | "code-context": {
370 | "command": "npx",
371 | "args": ["-y", "@zilliz/claude-context-mcp@latest"],
372 | "env": {
373 | "OPENAI_API_KEY": "your-openai-api-key",
374 | "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
375 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
376 | }
377 | }
378 | }
379 | }
380 | ```
381 |
382 | </details>
383 |
384 | <details>
385 | <summary><strong>Claude Desktop</strong></summary>
386 |
387 | Add to your Claude Desktop configuration:
388 |
389 | ```json
390 | {
391 | "mcpServers": {
392 | "claude-context": {
393 | "command": "npx",
394 | "args": ["@zilliz/claude-context-mcp@latest"],
395 | "env": {
396 | "OPENAI_API_KEY": "your-openai-api-key",
397 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
398 | }
399 | }
400 | }
401 | }
402 | ```
403 |
404 | </details>
405 |
406 | <details>
407 | <summary><strong>Windsurf</strong></summary>
408 |
409 | Windsurf supports MCP configuration through a JSON file. Add the following configuration to your Windsurf MCP settings:
410 |
411 | ```json
412 | {
413 | "mcpServers": {
414 | "claude-context": {
415 | "command": "npx",
416 | "args": ["-y", "@zilliz/claude-context-mcp@latest"],
417 | "env": {
418 | "OPENAI_API_KEY": "your-openai-api-key",
419 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
420 | }
421 | }
422 | }
423 | }
424 | ```
425 |
426 | </details>
427 |
428 | <details>
429 | <summary><strong>VS Code</strong></summary>
430 |
431 | The Claude Context MCP server can be used with VS Code through MCP-compatible extensions. Add the following configuration to your VS Code MCP settings:
432 |
433 | ```json
434 | {
435 | "mcpServers": {
436 | "claude-context": {
437 | "command": "npx",
438 | "args": ["-y", "@zilliz/claude-context-mcp@latest"],
439 | "env": {
440 | "OPENAI_API_KEY": "your-openai-api-key",
441 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
442 | }
443 | }
444 | }
445 | }
446 | ```
447 |
448 | </details>
449 |
450 | <details>
451 | <summary><strong>Cherry Studio</strong></summary>
452 |
453 | Cherry Studio allows for visual MCP server configuration through its settings interface. While it doesn't directly support manual JSON configuration, you can add a new server via the GUI:
454 |
455 | 1. Navigate to **Settings → MCP Servers → Add Server**.
456 | 2. Fill in the server details:
457 | - **Name**: `claude-context`
458 | - **Type**: `STDIO`
459 | - **Command**: `npx`
460 | - **Arguments**: `["@zilliz/claude-context-mcp@latest"]`
461 | - **Environment Variables**:
462 | - `OPENAI_API_KEY`: `your-openai-api-key`
463 | - `MILVUS_TOKEN`: `your-zilliz-cloud-api-key`
464 | 3. Save the configuration to activate the server.
465 |
466 | </details>
467 |
468 | <details>
469 | <summary><strong>Cline</strong></summary>
470 |
471 | Cline uses a JSON configuration file to manage MCP servers. To integrate the provided MCP server configuration:
472 |
473 | 1. Open Cline and click on the **MCP Servers** icon in the top navigation bar.
474 |
475 | 2. Select the **Installed** tab, then click **Advanced MCP Settings**.
476 |
477 | 3. In the `cline_mcp_settings.json` file, add the following configuration:
478 |
479 | ```json
480 | {
481 | "mcpServers": {
482 | "claude-context": {
483 | "command": "npx",
484 | "args": ["@zilliz/claude-context-mcp@latest"],
485 | "env": {
486 | "OPENAI_API_KEY": "your-openai-api-key",
487 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
488 | }
489 | }
490 | }
491 | }
492 | ```
493 |
494 | 4. Save the file.
495 |
496 | </details>
497 |
498 | <details>
499 | <summary><strong>Augment</strong></summary>
500 |
501 | To configure Claude Context MCP in Augment Code, you can use either the graphical interface or manual configuration.
502 |
503 | #### **A. Using the Augment Code UI**
504 |
505 | 1. Click the hamburger menu.
506 |
507 | 2. Select **Settings**.
508 |
509 | 3. Navigate to the **Tools** section.
510 |
511 | 4. Click the **+ Add MCP** button.
512 |
513 | 5. Enter the following command:
514 |
515 | ```
516 | npx @zilliz/claude-context-mcp@latest
517 | ```
518 |
519 | 6. Name the MCP: **Claude Context**.
520 |
521 | 7. Click the **Add** button.
522 |
523 | ------
524 |
525 | #### **B. Manual Configuration**
526 |
527 | 1. Press Cmd/Ctrl Shift P or go to the hamburger menu in the Augment panel
528 | 2. Select Edit Settings
529 | 3. Under Advanced, click Edit in settings.json
530 | 4. Add the server configuration to the `mcpServers` array in the `augment.advanced` object
531 |
532 | ```json
533 | "augment.advanced": {
534 | "mcpServers": [
535 | {
536 | "name": "claude-context",
537 | "command": "npx",
538 | "args": ["-y", "@zilliz/claude-context-mcp@latest"]
539 | }
540 | ]
541 | }
542 | ```
543 |
544 | </details>
545 |
546 | <details>
547 | <summary><strong>Roo Code</strong></summary>
548 |
549 | Roo Code utilizes a JSON configuration file for MCP servers:
550 |
551 | 1. Open Roo Code and navigate to **Settings → MCP Servers → Edit Global Config**.
552 |
553 | 2. In the `mcp_settings.json` file, add the following configuration:
554 |
555 | ```json
556 | {
557 | "mcpServers": {
558 | "claude-context": {
559 | "command": "npx",
560 | "args": ["@zilliz/claude-context-mcp@latest"],
561 | "env": {
562 | "OPENAI_API_KEY": "your-openai-api-key",
563 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
564 | }
565 | }
566 | }
567 | }
568 | ```
569 |
570 | 3. Save the file to activate the server.
571 |
572 | </details>
573 |
574 | <details>
575 | <summary><strong>Zencoder</strong></summary>
576 |
577 | Zencoder offers support for MCP tools and servers in both its JetBrains and VS Code plugin versions.
578 |
579 | 1. Go to the Zencoder menu (...)
580 | 2. From the dropdown menu, select `Tools`
581 | 3. Click on the `Add Custom MCP`
582 | 4. Add the name (i.e. `Claude Context` and server configuration from below, and make sure to hit the `Install` button
583 |
584 | ```json
585 | {
586 | "command": "npx",
587 | "args": ["@zilliz/claude-context-mcp@latest"],
588 | "env": {
589 | "OPENAI_API_KEY": "your-openai-api-key",
590 | "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
591 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
592 | }
593 | }
594 |
595 | ```
596 |
597 | 5. Save the server by hitting the `Install` button.
598 |
599 | </details>
600 |
601 | <details>
602 | <summary><strong>LangChain/LangGraph</strong></summary>
603 |
604 | For LangChain/LangGraph integration examples, see [this example](https://github.com/zilliztech/claude-context/blob/643796a0d30e706a2a0dff3d55621c9b5d831807/evaluation/retrieval/custom.py#L88).
605 |
606 | </details>
607 |
608 | <details>
609 | <summary><strong>Other MCP Clients</strong></summary>
610 |
611 | The server uses stdio transport and follows the standard MCP protocol. It can be integrated with any MCP-compatible client by running:
612 |
613 | ```bash
614 | npx @zilliz/claude-context-mcp@latest
615 | ```
616 |
617 | </details>
618 |
619 | ## Features
620 |
621 | - 🔌 **MCP Protocol Compliance**: Full compatibility with MCP-enabled AI assistants and agents
622 | - 🔍 **Hybrid Code Search**: Natural language queries using advanced hybrid search (BM25 + dense vector) to find relevant code snippets
623 | - 📁 **Codebase Indexing**: Index entire codebases for fast hybrid search across millions of lines of code
624 | - 🔄 **Incremental Indexing**: Efficiently re-index only changed files using Merkle trees for auto-sync
625 | - 🧩 **Intelligent Code Chunking**: AST-based code analysis for syntax-aware chunking with automatic fallback
626 | - 🗄️ **Scalable**: Integrates with Zilliz Cloud for scalable vector search, no matter how large your codebase is
627 | - 🛠️ **Customizable**: Configure file extensions, ignore patterns, and embedding models
628 | - ⚡ **Real-time**: Interactive indexing and searching with progress feedback
629 |
630 | ## Available Tools
631 |
632 | ### 1. `index_codebase`
633 |
634 | Index a codebase directory for hybrid search (BM25 + dense vector).
635 |
636 | **Parameters:**
637 |
638 | - `path` (required): Absolute path to the codebase directory to index
639 | - `force` (optional): Force re-indexing even if already indexed (default: false)
640 | - `splitter` (optional): Code splitter to use - 'ast' for syntax-aware splitting with automatic fallback, 'langchain' for character-based splitting (default: "ast")
641 | - `customExtensions` (optional): Additional file extensions to include beyond defaults (e.g., ['.vue', '.svelte', '.astro']). Extensions should include the dot prefix or will be automatically added (default: [])
642 | - `ignorePatterns` (optional): Additional ignore patterns to exclude specific files/directories beyond defaults (e.g., ['static/**', '*.tmp', 'private/**']) (default: [])
643 |
644 | ### 2. `search_code`
645 |
646 | Search the indexed codebase using natural language queries with hybrid search (BM25 + dense vector).
647 |
648 | **Parameters:**
649 |
650 | - `path` (required): Absolute path to the codebase directory to search in
651 | - `query` (required): Natural language query to search for in the codebase
652 | - `limit` (optional): Maximum number of results to return (default: 10, max: 50)
653 | - `extensionFilter` (optional): List of file extensions to filter results (e.g., ['.ts', '.py']) (default: [])
654 |
655 | ### 3. `clear_index`
656 |
657 | Clear the search index for a specific codebase.
658 |
659 | **Parameters:**
660 |
661 | - `path` (required): Absolute path to the codebase directory to clear index for
662 |
663 | ### 4. `get_indexing_status`
664 |
665 | Get the current indexing status of a codebase. Shows progress percentage for actively indexing codebases and completion status for indexed codebases.
666 |
667 | **Parameters:**
668 |
669 | - `path` (required): Absolute path to the codebase directory to check status for
670 |
671 | ## Contributing
672 |
673 | This package is part of the Claude Context monorepo. Please see:
674 |
675 | - [Main Contributing Guide](../../CONTRIBUTING.md) - General contribution guidelines
676 | - [MCP Package Contributing](CONTRIBUTING.md) - Specific development guide for this package
677 |
678 | ## Related Projects
679 |
680 | - **[@zilliz/claude-context-core](../core)** - Core indexing engine used by this MCP server
681 | - **[VSCode Extension](../vscode-extension)** - Alternative VSCode integration
682 | - [Model Context Protocol](https://modelcontextprotocol.io/) - Official MCP documentation
683 |
684 | ## License
685 |
686 | MIT - See [LICENSE](../../LICENSE) for details
687 |
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | 
2 |
3 | ### Your entire codebase as Claude's context
4 |
5 | [](https://opensource.org/licenses/MIT)
6 | [](https://nodejs.org/)
7 | [](docs/)
8 | [](https://marketplace.visualstudio.com/items?itemName=zilliz.semanticcodesearch)
9 | [](https://www.npmjs.com/package/@zilliz/claude-context-core)
10 | [](https://www.npmjs.com/package/@zilliz/claude-context-mcp)
11 | [](https://twitter.com/zilliz_universe)
12 | [](https://deepwiki.com/zilliztech/claude-context)
13 | <a href="https://discord.gg/mKc3R95yE5"><img height="20" src="https://img.shields.io/badge/Discord-%235865F2.svg?style=for-the-badge&logo=discord&logoColor=white" alt="discord" /></a>
14 | </div>
15 |
16 | **Claude Context** is an MCP plugin that adds semantic code search to Claude Code and other AI coding agents, giving them deep context from your entire codebase.
17 |
18 | 🧠 **Your Entire Codebase as Context**: Claude Context uses semantic search to find all relevant code from millions of lines. No multi-round discovery needed. It brings results straight into the Claude's context.
19 |
20 | 💰 **Cost-Effective for Large Codebases**: Instead of loading entire directories into Claude for every request, which can be very expensive, Claude Context efficiently stores your codebase in a vector database and only uses related code in context to keep your costs manageable.
21 |
22 | ---
23 |
24 | ## 🚀 Demo
25 |
26 | 
27 |
28 | Model Context Protocol (MCP) allows you to integrate Claude Context with your favorite AI coding assistants, e.g. Claude Code.
29 |
30 | ## Quick Start
31 |
32 | ### Prerequisites
33 |
34 | <details>
35 | <summary>Get a free vector database on Zilliz Cloud 👈</summary>
36 |
37 | Claude Context needs a vector database. You can [sign up](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=2507-codecontext-readme) on Zilliz Cloud to get an API key.
38 |
39 | 
40 |
41 | Copy your Personal Key to replace `your-zilliz-cloud-api-key` in the configuration examples.
42 | </details>
43 |
44 | <details>
45 | <summary>Get OpenAI API Key for embedding model</summary>
46 |
47 | You need an OpenAI API key for the embedding model. You can get one by signing up at [OpenAI](https://platform.openai.com/api-keys).
48 |
49 | Your API key will look like this: it always starts with `sk-`.
50 | Copy your key and use it in the configuration examples below as `your-openai-api-key`.
51 |
52 | </details>
53 |
54 | ### Configure MCP for Claude Code
55 |
56 | **System Requirements:**
57 |
58 | - Node.js >= 20.0.0 and < 24.0.0
59 |
60 | > Claude Context is not compatible with Node.js 24.0.0, you need downgrade it first if your node version is greater or equal to 24.
61 |
62 | #### Configuration
63 |
64 | Use the command line interface to add the Claude Context MCP server:
65 |
66 | ```bash
67 | claude mcp add claude-context \
68 | -e OPENAI_API_KEY=sk-your-openai-api-key \
69 | -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
70 | -- npx @zilliz/claude-context-mcp@latest
71 | ```
72 |
73 | See the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for more details about MCP server management.
74 |
75 | ### Other MCP Client Configurations
76 |
77 | <details>
78 | <summary><strong>OpenAI Codex CLI</strong></summary>
79 |
80 | Codex CLI uses TOML configuration files:
81 |
82 | 1. Create or edit the `~/.codex/config.toml` file.
83 |
84 | 2. Add the following configuration:
85 |
86 | ```toml
87 | # IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
88 | [mcp_servers.claude-context]
89 | command = "npx"
90 | args = ["@zilliz/claude-context-mcp@latest"]
91 | env = { "OPENAI_API_KEY" = "your-openai-api-key", "MILVUS_TOKEN" = "your-zilliz-cloud-api-key" }
92 | # Optional: override the default 10s startup timeout
93 | startup_timeout_ms = 20000
94 | ```
95 |
96 | 3. Save the file and restart Codex CLI to apply the changes.
97 |
98 | </details>
99 |
100 | <details>
101 | <summary><strong>Gemini CLI</strong></summary>
102 |
103 | Gemini CLI requires manual configuration through a JSON file:
104 |
105 | 1. Create or edit the `~/.gemini/settings.json` file.
106 | 2. Add the following configuration:
107 |
108 | ```json
109 | {
110 | "mcpServers": {
111 | "claude-context": {
112 | "command": "npx",
113 | "args": ["@zilliz/claude-context-mcp@latest"],
114 | "env": {
115 | "OPENAI_API_KEY": "your-openai-api-key",
116 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
117 | }
118 | }
119 | }
120 | }
121 | ```
122 |
123 | 3. Save the file and restart Gemini CLI to apply the changes.
124 |
125 | </details>
126 |
127 | <details>
128 | <summary><strong>Qwen Code</strong></summary>
129 |
130 | Create or edit the `~/.qwen/settings.json` file and add the following configuration:
131 |
132 | ```json
133 | {
134 | "mcpServers": {
135 | "claude-context": {
136 | "command": "npx",
137 | "args": ["@zilliz/claude-context-mcp@latest"],
138 | "env": {
139 | "OPENAI_API_KEY": "your-openai-api-key",
140 | "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
141 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
142 | }
143 | }
144 | }
145 | }
146 | ```
147 |
148 | </details>
149 |
150 | <details>
151 | <summary><strong>Cursor</strong></summary>
152 |
153 | <a href="https://cursor.com/install-mcp?name=claude-context&config=JTdCJTIyY29tbWFuZCUyMiUzQSUyMm5weCUyMC15JTIwJTQwemlsbGl6JTJGY29kZS1jb250ZXh0LW1jcCU0MGxhdGVzdCUyMiUyQyUyMmVudiUyMiUzQSU3QiUyMk9QRU5BSV9BUElfS0VZJTIyJTNBJTIyeW91ci1vcGVuYWktYXBpLWtleSUyMiUyQyUyMk1JTFZVU19BRERSRVNTJTIyJTNBJTIybG9jYWxob3N0JTNBMTk1MzAlMjIlN0QlN0Q%3D"><img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add claude-context MCP server to Cursor" height="32" /></a>
154 |
155 | Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`
156 |
157 | Pasting the following configuration into your Cursor `~/.cursor/mcp.json` file is the recommended approach. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.
158 |
159 | ```json
160 | {
161 | "mcpServers": {
162 | "claude-context": {
163 | "command": "npx",
164 | "args": ["-y", "@zilliz/claude-context-mcp@latest"],
165 | "env": {
166 | "OPENAI_API_KEY": "your-openai-api-key",
167 | "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
168 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
169 | }
170 | }
171 | }
172 | }
173 | ```
174 |
175 | </details>
176 |
177 | <details>
178 | <summary><strong>Void</strong></summary>
179 |
180 | Go to: `Settings` -> `MCP` -> `Add MCP Server`
181 |
182 | Add the following configuration to your Void MCP settings:
183 |
184 | ```json
185 | {
186 | "mcpServers": {
187 | "code-context": {
188 | "command": "npx",
189 | "args": ["-y", "@zilliz/claude-context-mcp@latest"],
190 | "env": {
191 | "OPENAI_API_KEY": "your-openai-api-key",
192 | "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
193 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
194 | }
195 | }
196 | }
197 | }
198 | ```
199 |
200 | </details>
201 |
202 | <details>
203 | <summary><strong>Claude Desktop</strong></summary>
204 |
205 | Add to your Claude Desktop configuration:
206 |
207 | ```json
208 | {
209 | "mcpServers": {
210 | "claude-context": {
211 | "command": "npx",
212 | "args": ["@zilliz/claude-context-mcp@latest"],
213 | "env": {
214 | "OPENAI_API_KEY": "your-openai-api-key",
215 | "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
216 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
217 | }
218 | }
219 | }
220 | }
221 | ```
222 |
223 | </details>
224 |
225 | <details>
226 | <summary><strong>Windsurf</strong></summary>
227 |
228 | Windsurf supports MCP configuration through a JSON file. Add the following configuration to your Windsurf MCP settings:
229 |
230 | ```json
231 | {
232 | "mcpServers": {
233 | "claude-context": {
234 | "command": "npx",
235 | "args": ["-y", "@zilliz/claude-context-mcp@latest"],
236 | "env": {
237 | "OPENAI_API_KEY": "your-openai-api-key",
238 | "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
239 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
240 | }
241 | }
242 | }
243 | }
244 | ```
245 |
246 | </details>
247 |
248 | <details>
249 | <summary><strong>VS Code</strong></summary>
250 |
251 | The Claude Context MCP server can be used with VS Code through MCP-compatible extensions. Add the following configuration to your VS Code MCP settings:
252 |
253 | ```json
254 | {
255 | "mcpServers": {
256 | "claude-context": {
257 | "command": "npx",
258 | "args": ["-y", "@zilliz/claude-context-mcp@latest"],
259 | "env": {
260 | "OPENAI_API_KEY": "your-openai-api-key",
261 | "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
262 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
263 | }
264 | }
265 | }
266 | }
267 | ```
268 |
269 | </details>
270 |
271 | <details>
272 | <summary><strong>Cherry Studio</strong></summary>
273 |
274 | Cherry Studio allows for visual MCP server configuration through its settings interface. While it doesn't directly support manual JSON configuration, you can add a new server via the GUI:
275 |
276 | 1. Navigate to **Settings → MCP Servers → Add Server**.
277 | 2. Fill in the server details:
278 | - **Name**: `claude-context`
279 | - **Type**: `STDIO`
280 | - **Command**: `npx`
281 | - **Arguments**: `["@zilliz/claude-context-mcp@latest"]`
282 | - **Environment Variables**:
283 | - `OPENAI_API_KEY`: `your-openai-api-key`
284 | - `MILVUS_ADDRESS`: `your-zilliz-cloud-public-endpoint`
285 | - `MILVUS_TOKEN`: `your-zilliz-cloud-api-key`
286 | 3. Save the configuration to activate the server.
287 |
288 | </details>
289 |
290 | <details>
291 | <summary><strong>Cline</strong></summary>
292 |
293 | Cline uses a JSON configuration file to manage MCP servers. To integrate the provided MCP server configuration:
294 |
295 | 1. Open Cline and click on the **MCP Servers** icon in the top navigation bar.
296 |
297 | 2. Select the **Installed** tab, then click **Advanced MCP Settings**.
298 |
299 | 3. In the `cline_mcp_settings.json` file, add the following configuration:
300 |
301 | ```json
302 | {
303 | "mcpServers": {
304 | "claude-context": {
305 | "command": "npx",
306 | "args": ["@zilliz/claude-context-mcp@latest"],
307 | "env": {
308 | "OPENAI_API_KEY": "your-openai-api-key",
309 | "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
310 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
311 | }
312 | }
313 | }
314 | }
315 | ```
316 |
317 | 4. Save the file.
318 |
319 | </details>
320 |
321 | <details>
322 | <summary><strong>Augment</strong></summary>
323 |
324 | To configure Claude Context MCP in Augment Code, you can use either the graphical interface or manual configuration.
325 |
326 | #### **A. Using the Augment Code UI**
327 |
328 | 1. Click the hamburger menu.
329 |
330 | 2. Select **Settings**.
331 |
332 | 3. Navigate to the **Tools** section.
333 |
334 | 4. Click the **+ Add MCP** button.
335 |
336 | 5. Enter the following command:
337 |
338 | ```
339 | npx @zilliz/claude-context-mcp@latest
340 | ```
341 |
342 | 6. Name the MCP: **Claude Context**.
343 |
344 | 7. Click the **Add** button.
345 |
346 | ------
347 |
348 | #### **B. Manual Configuration**
349 |
350 | 1. Press Cmd/Ctrl Shift P or go to the hamburger menu in the Augment panel
351 | 2. Select Edit Settings
352 | 3. Under Advanced, click Edit in settings.json
353 | 4. Add the server configuration to the `mcpServers` array in the `augment.advanced` object
354 |
355 | ```json
356 | "augment.advanced": {
357 | "mcpServers": [
358 | {
359 | "name": "claude-context",
360 | "command": "npx",
361 | "args": ["-y", "@zilliz/claude-context-mcp@latest"],
362 | "env": {
363 | "OPENAI_API_KEY": "your-openai-api-key",
364 | "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
365 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
366 | }
367 | }
368 | ]
369 | }
370 | ```
371 |
372 | </details>
373 |
374 | <details>
375 | <summary><strong>Roo Code</strong></summary>
376 |
377 | Roo Code utilizes a JSON configuration file for MCP servers:
378 |
379 | 1. Open Roo Code and navigate to **Settings → MCP Servers → Edit Global Config**.
380 |
381 | 2. In the `mcp_settings.json` file, add the following configuration:
382 |
383 | ```json
384 | {
385 | "mcpServers": {
386 | "claude-context": {
387 | "command": "npx",
388 | "args": ["@zilliz/claude-context-mcp@latest"],
389 | "env": {
390 | "OPENAI_API_KEY": "your-openai-api-key",
391 | "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
392 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
393 | }
394 | }
395 | }
396 | }
397 | ```
398 |
399 | 3. Save the file to activate the server.
400 |
401 | </details>
402 |
403 | <details>
404 | <summary><strong>Zencoder</strong></summary>
405 |
406 | Zencoder offers support for MCP tools and servers in both its JetBrains and VS Code plugin versions.
407 |
408 | 1. Go to the Zencoder menu (...)
409 | 2. From the dropdown menu, select `Tools`
410 | 3. Click on the `Add Custom MCP`
411 | 4. Add the name (i.e. `Claude Context` and server configuration from below, and make sure to hit the `Install` button
412 |
413 | ```json
414 | {
415 | "command": "npx",
416 | "args": ["@zilliz/claude-context-mcp@latest"],
417 | "env": {
418 | "OPENAI_API_KEY": "your-openai-api-key",
419 | "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
420 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
421 | }
422 | }
423 |
424 | ```
425 |
426 | 5. Save the server by hitting the `Install` button.
427 |
428 | </details>
429 |
430 | <details>
431 | <summary><strong>LangChain/LangGraph</strong></summary>
432 |
433 | For LangChain/LangGraph integration examples, see [this example](https://github.com/zilliztech/claude-context/blob/643796a0d30e706a2a0dff3d55621c9b5d831807/evaluation/retrieval/custom.py#L88).
434 |
435 | </details>
436 |
437 | <details>
438 | <summary><strong>Other MCP Clients</strong></summary>
439 |
440 | The server uses stdio transport and follows the standard MCP protocol. It can be integrated with any MCP-compatible client by running:
441 |
442 | ```bash
443 | npx @zilliz/claude-context-mcp@latest
444 | ```
445 |
446 | </details>
447 |
448 | ---
449 |
450 | ### Usage in Your Codebase
451 |
452 | 1. **Open Claude Code**
453 |
454 | ```
455 | cd your-project-directory
456 | claude
457 | ```
458 |
459 | 2. **Index your codebase**:
460 |
461 | ```
462 | Index this codebase
463 | ```
464 |
465 | 3. **Check indexing status**:
466 |
467 | ```
468 | Check the indexing status
469 | ```
470 |
471 | 4. **Start searching**:
472 |
473 | ```
474 | Find functions that handle user authentication
475 | ```
476 |
477 | 🎉 **That's it!** You now have semantic code search in Claude Code.
478 |
479 | ---
480 |
481 | ### Environment Variables Configuration
482 |
483 | For more detailed MCP environment variable configuration, see our [Environment Variables Guide](docs/getting-started/environment-variables.md).
484 |
485 | ### Using Different Embedding Models
486 |
487 | 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.
488 |
489 | ### File Inclusion & Exclusion Rules
490 |
491 | 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).
492 |
493 | ### Available Tools
494 |
495 | #### 1. `index_codebase`
496 |
497 | Index a codebase directory for hybrid search (BM25 + dense vector).
498 |
499 | #### 2. `search_code`
500 |
501 | Search the indexed codebase using natural language queries with hybrid search (BM25 + dense vector).
502 |
503 | #### 3. `clear_index`
504 |
505 | Clear the search index for a specific codebase.
506 |
507 | #### 4. `get_indexing_status`
508 |
509 | Get the current indexing status of a codebase. Shows progress percentage for actively indexing codebases and completion status for indexed codebases.
510 |
511 | ---
512 |
513 | ## 📊 Evaluation
514 |
515 | Our controlled evaluation demonstrates that Claude Context MCP achieves ~40% token reduction under the condition of equivalent retrieval quality. This translates to significant cost and time savings in production environments. This also means that, under the constraint of limited token context length, using Claude Context yields better retrieval and answer results.
516 |
517 | 
518 |
519 | For detailed evaluation methodology and results, see the [evaluation directory](evaluation/).
520 |
521 | ---
522 |
523 | ## 🏗️ Architecture
524 |
525 | 
526 |
527 | ### 🔧 Implementation Details
528 |
529 | - 🔍 **Hybrid Code Search**: Ask questions like *"find functions that handle user authentication"* and get relevant, context-rich code instantly using advanced hybrid search (BM25 + dense vector).
530 | - 🧠 **Context-Aware**: Discover large codebase, understand how different parts of your codebase relate, even across millions of lines of code.
531 | - ⚡ **Incremental Indexing**: Efficiently re-index only changed files using Merkle trees.
532 | - 🧩 **Intelligent Code Chunking**: Analyze code in Abstract Syntax Trees (AST) for chunking.
533 | - 🗄️ **Scalable**: Integrates with Zilliz Cloud for scalable vector search, no matter how large your codebase is.
534 | - 🛠️ **Customizable**: Configure file extensions, ignore patterns, and embedding models.
535 |
536 | ### Core Components
537 |
538 | Claude Context is a monorepo containing three main packages:
539 |
540 | - **`@zilliz/claude-context-core`**: Core indexing engine with embedding and vector database integration
541 | - **VSCode Extension**: Semantic Code Search extension for Visual Studio Code
542 | - **`@zilliz/claude-context-mcp`**: Model Context Protocol server for AI agent integration
543 |
544 | ### Supported Technologies
545 |
546 | - **Embedding Providers**: [OpenAI](https://openai.com), [VoyageAI](https://voyageai.com), [Ollama](https://ollama.ai), [Gemini](https://gemini.google.com)
547 | - **Vector Databases**: [Milvus](https://milvus.io) or [Zilliz Cloud](https://zilliz.com/cloud)(fully managed vector database as a service)
548 | - **Code Splitters**: AST-based splitter (with automatic fallback), LangChain character-based splitter
549 | - **Languages**: TypeScript, JavaScript, Python, Java, C++, C#, Go, Rust, PHP, Ruby, Swift, Kotlin, Scala, Markdown
550 | - **Development Tools**: VSCode, Model Context Protocol
551 |
552 | ---
553 |
554 | ## 📦 Other Ways to Use Claude Context
555 |
556 | While MCP is the recommended way to use Claude Context with AI assistants, you can also use it directly or through the VSCode extension.
557 |
558 | ### Build Applications with Core Package
559 |
560 | The `@zilliz/claude-context-core` package provides the fundamental functionality for code indexing and semantic search.
561 |
562 | ```typescript
563 | import { Context, MilvusVectorDatabase, OpenAIEmbedding } from '@zilliz/claude-context-core';
564 |
565 | // Initialize embedding provider
566 | const embedding = new OpenAIEmbedding({
567 | apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',
568 | model: 'text-embedding-3-small'
569 | });
570 |
571 | // Initialize vector database
572 | const vectorDatabase = new MilvusVectorDatabase({
573 | address: process.env.MILVUS_ADDRESS || 'your-zilliz-cloud-public-endpoint',
574 | token: process.env.MILVUS_TOKEN || 'your-zilliz-cloud-api-key'
575 | });
576 |
577 | // Create context instance
578 | const context = new Context({
579 | embedding,
580 | vectorDatabase
581 | });
582 |
583 | // Index your codebase with progress tracking
584 | const stats = await context.indexCodebase('./your-project', (progress) => {
585 | console.log(`${progress.phase} - ${progress.percentage}%`);
586 | });
587 | console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);
588 |
589 | // Perform semantic search
590 | const results = await context.semanticSearch('./your-project', 'vector database operations', 5);
591 | results.forEach(result => {
592 | console.log(`File: ${result.relativePath}:${result.startLine}-${result.endLine}`);
593 | console.log(`Score: ${(result.score * 100).toFixed(2)}%`);
594 | console.log(`Content: ${result.content.substring(0, 100)}...`);
595 | });
596 | ```
597 |
598 | ### VSCode Extension
599 |
600 | Integrates Claude Context directly into your IDE. Provides an intuitive interface for semantic code search and navigation.
601 |
602 | 1. **Direct Link**: [Install from VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=zilliz.semanticcodesearch)
603 | 2. **Manual Search**:
604 | - Open Extensions view in VSCode (Ctrl+Shift+X or Cmd+Shift+X on Mac)
605 | - Search for "Semantic Code Search"
606 | - Click Install
607 |
608 | 
609 | ---
610 |
611 | ## 🛠️ Development
612 |
613 | ### Setup Development Environment
614 |
615 | #### Prerequisites
616 |
617 | - Node.js 20.x or 22.x
618 | - pnpm (recommended package manager)
619 |
620 | #### Cross-Platform Setup
621 |
622 | ```bash
623 | # Clone repository
624 | git clone https://github.com/zilliztech/claude-context.git
625 | cd claude-context
626 |
627 | # Install dependencies
628 | pnpm install
629 |
630 | # Build all packages
631 | pnpm build
632 |
633 | # Start development mode
634 | pnpm dev
635 | ```
636 |
637 | #### Windows-Specific Setup
638 |
639 | On Windows, ensure you have:
640 |
641 | - **Git for Windows** with proper line ending configuration
642 | - **Node.js** installed via the official installer or package manager
643 | - **pnpm** installed globally: `npm install -g pnpm`
644 |
645 | ```powershell
646 | # Windows PowerShell/Command Prompt
647 | git clone https://github.com/zilliztech/claude-context.git
648 | cd claude-context
649 |
650 | # Configure git line endings (recommended)
651 | git config core.autocrlf false
652 |
653 | # Install dependencies
654 | pnpm install
655 |
656 | # Build all packages (uses cross-platform scripts)
657 | pnpm build
658 |
659 | # Start development mode
660 | pnpm dev
661 | ```
662 |
663 | ### Building
664 |
665 | ```bash
666 | # Build all packages (cross-platform)
667 | pnpm build
668 |
669 | # Build specific package
670 | pnpm build:core
671 | pnpm build:vscode
672 | pnpm build:mcp
673 |
674 | # Performance benchmarking
675 | pnpm benchmark
676 | ```
677 |
678 | #### Windows Build Notes
679 |
680 | - All build scripts are cross-platform compatible using rimraf
681 | - Build caching is enabled for faster subsequent builds
682 | - Use PowerShell or Command Prompt - both work equally well
683 |
684 | ### Running Examples
685 |
686 | ```bash
687 | # Development with file watching
688 | cd examples/basic-usage
689 | pnpm dev
690 | ```
691 |
692 | ---
693 |
694 | ## 📖 Examples
695 |
696 | Check the `/examples` directory for complete usage examples:
697 |
698 | - **Basic Usage**: Simple indexing and search example
699 |
700 | ---
701 |
702 | ## ❓ FAQ
703 |
704 | **Common Questions:**
705 |
706 | - **[What files does Claude Context decide to embed?](docs/troubleshooting/faq.md#q-what-files-does-claude-context-decide-to-embed)**
707 | - **[Can I use a fully local deployment setup?](docs/troubleshooting/faq.md#q-can-i-use-a-fully-local-deployment-setup)**
708 | - **[Does it support multiple projects / codebases?](docs/troubleshooting/faq.md#q-does-it-support-multiple-projects--codebases)**
709 | - **[How does Claude Context compare to other coding tools?](docs/troubleshooting/faq.md#q-how-does-claude-context-compare-to-other-coding-tools-like-serena-context7-or-deepwiki)**
710 |
711 | ❓ For detailed answers and more troubleshooting tips, see our [FAQ Guide](docs/troubleshooting/faq.md).
712 |
713 | 🔧 **Encountering issues?** Visit our [Troubleshooting Guide](docs/troubleshooting/troubleshooting-guide.md) for step-by-step solutions.
714 |
715 | 📚 **Need more help?** Check out our [complete documentation](docs/) for detailed guides and troubleshooting tips.
716 |
717 | ---
718 |
719 | ## 🤝 Contributing
720 |
721 | We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started.
722 |
723 | **Package-specific contributing guides:**
724 |
725 | - [Core Package Contributing](packages/core/CONTRIBUTING.md)
726 | - [MCP Server Contributing](packages/mcp/CONTRIBUTING.md)
727 | - [VSCode Extension Contributing](packages/vscode-extension/CONTRIBUTING.md)
728 |
729 | ---
730 |
731 | ## 🗺️ Roadmap
732 |
733 | - [x] AST-based code analysis for improved understanding
734 | - [x] Support for additional embedding providers
735 | - [ ] Agent-based interactive search mode
736 | - [x] Enhanced code chunking strategies
737 | - [ ] Search result ranking optimization
738 | - [ ] Robust Chrome Extension
739 |
740 | ---
741 |
742 | ## 📄 License
743 |
744 | This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
745 |
746 | ---
747 |
748 | ## 🔗 Links
749 |
750 | - [GitHub Repository](https://github.com/zilliztech/claude-context)
751 | - [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=zilliz.semanticcodesearch)
752 | - [Milvus Documentation](https://milvus.io/docs)
753 | - [Zilliz Cloud](https://zilliz.com/cloud)
754 |
```
--------------------------------------------------------------------------------
/packages/core/CONTRIBUTING.md:
--------------------------------------------------------------------------------
```markdown
1 | # Contributing to @zilliz/claude-context-core
2 |
3 | Thanks for your interest in contributing to the Claude Context core package!
4 |
5 | > 📖 **First time contributing?** Please read the [main contributing guide](../../CONTRIBUTING.md) first for general setup and workflow.
6 |
7 | ## Core Package Development
8 |
9 | This guide covers development specific to the core indexing engine.
10 |
11 | ## Development Workflow
12 |
13 | ### Quick Commands
14 | ```bash
15 | # Build core package
16 | pnpm build:core
17 |
18 | # Watch mode for development
19 | pnpm dev:core
20 | ```
21 |
22 | ### Making Changes
23 |
24 | 1. Create a new branch for your feature/fix
25 | 2. Make your changes in the `src/` directory
26 | 3. Follow the commit guidelines in the [main guide](../../CONTRIBUTING.md)
27 |
28 | ## Project Structure
29 |
30 | - `src/context.ts` - Main Claude Context class
31 | - `src/embedding/` - Embedding providers (OpenAI, VoyageAI, Ollama)
32 | - `src/vectordb/` - Vector database implementations (Milvus)
33 | - `src/splitter/` - Code splitting logic
34 | - `src/types.ts` - TypeScript type definitions
35 |
36 | ## Guidelines
37 |
38 | - Use TypeScript strict mode
39 | - Follow existing code style
40 | - Handle errors gracefully
41 |
42 | ## Questions?
43 |
44 | - **General questions**: See [main contributing guide](../../CONTRIBUTING.md)
45 | - **Core-specific issues**: Open an issue with the `core` label
```
--------------------------------------------------------------------------------
/packages/vscode-extension/CONTRIBUTING.md:
--------------------------------------------------------------------------------
```markdown
1 | # Contributing to VSCode Extension
2 |
3 | Thanks for your interest in contributing to the Claude Context VSCode extension!
4 |
5 | > 📖 **First time contributing?** Please read the [main contributing guide](../../CONTRIBUTING.md) first for general setup and workflow.
6 |
7 | ## VSCode Extension Development
8 |
9 | This guide covers development specific to the VSCode extension.
10 |
11 | ### Requirements
12 |
13 | - **VSCode Version**: 1.74.0 or higher
14 |
15 | ### Quick Commands
16 | ```bash
17 | # Build VSCode extension
18 | pnpm build:vscode
19 |
20 | # Watch mode for development
21 | pnpm dev:vscode
22 |
23 | # Package extension
24 | pnpm package
25 | ```
26 |
27 | ### Development Setup
28 | Press `F5` to launch Extension Development Host
29 |
30 | ## Making Changes
31 |
32 | 1. Create a new branch for your feature/fix
33 | 2. Make changes in the `src/` directory
34 | 3. Run in the Extension Development Host
35 | 4. Follow commit guidelines in the [main guide](../../CONTRIBUTING.md)
36 |
37 | ## Project Structure
38 |
39 | - `src/extension.ts` - Main extension entry point
40 | - `src/` - Extension source code
41 | - `resources/` - Icons and assets
42 | - `package.json` - Extension manifest and commands
43 | - `webpack.config.js` - Build configuration
44 |
45 | ## Development Workflow
46 |
47 | 1. Press `F5` in VSCode to open Extension Development Host
48 | 2. Try all commands and features
49 | 3. Check the Output panel for errors
50 | 4. Try with different project types
51 |
52 | ## Guidelines
53 |
54 | - Follow VSCode extension best practices
55 | - Use TypeScript for all code
56 | - Keep UI responsive and non-blocking
57 | - Provide user feedback for long operations
58 | - Handle errors gracefully with user-friendly messages
59 |
60 | ## Extension Features
61 |
62 | - Semantic code search within VSCode
63 | - Integration with Claude Context core
64 | - Progress indicators for indexing
65 | - Search results in sidebar
66 |
67 | ## Working in VSCode
68 |
69 | ### Extension Development Host
70 | - Press `F5` to open a new VSCode window with your extension loaded
71 | - Try the extension in the new window with real codebases
72 | - Check the Developer Console (`Help > Toggle Developer Tools`) for errors
73 |
74 | ### Manual Verification Checklist
75 | - [ ] Index a sample codebase successfully
76 | - [ ] Search returns relevant results
77 | - [ ] UI components display correctly
78 | - [ ] Configuration settings work properly
79 | - [ ] Commands execute without errors
80 |
81 | ## Testing with .vsix Package
82 |
83 | For a more robust pre-production test (safer than F5 development mode), you can package and install the extension locally:
84 |
85 | ```bash
86 | # Navigate to extension directory
87 | cd packages/vscode-extension
88 |
89 | # Package the extension (remove existing .vsix file if present)
90 | pnpm run package
91 |
92 | # Uninstall any existing version
93 | code --uninstall-extension semanticcodesearch-xxx.vsix
94 |
95 | # Install the packaged extension
96 | code --install-extension semanticcodesearch-xxx.vsix
97 | ```
98 |
99 | After installation, the extension will be available in VSCode just like any marketplace extension. This method:
100 | - Tests the actual packaged version
101 | - Simulates real user installation experience
102 | - Provides better isolation from development environment
103 | - **Recommended for final testing before production release**
104 |
105 | ## Publishing
106 |
107 | > **Note**: Only maintainers can publish to VS Code Marketplace
108 |
109 | ## Questions?
110 |
111 | - **General questions**: See [main contributing guide](../../CONTRIBUTING.md)
112 | - **VSCode-specific issues**: Open an issue with the `vscode` label
```
--------------------------------------------------------------------------------
/packages/mcp/CONTRIBUTING.md:
--------------------------------------------------------------------------------
```markdown
1 | # Contributing to @zilliz/claude-context-mcp
2 |
3 | Thanks for your interest in contributing to the Claude Context MCP server!
4 |
5 | > 📖 **First time contributing?** Please read the [main contributing guide](../../CONTRIBUTING.md) first for general setup and workflow.
6 |
7 | ## MCP Server Development
8 |
9 | This guide covers development specific to the MCP server.
10 |
11 | ### Quick Commands
12 | ```bash
13 | # Build MCP server
14 | pnpm build:mcp
15 |
16 | # Watch mode for development
17 | pnpm dev:mcp
18 |
19 | # Start server
20 | pnpm start
21 |
22 | # Run with environment variables
23 | pnpm start:with-env
24 | ```
25 |
26 | ### Required Environment Variables
27 | See [README.md](./README.md#prepare-environment-variables) for required environment variables.
28 |
29 | ## Running the MCP Server
30 |
31 | 1. Build the server:
32 | ```bash
33 | pnpm build
34 | ```
35 | 2. Run with MCP client or directly:
36 | ```bash
37 | pnpm start
38 | ```
39 | 3. Use the tools:
40 | - `index_codebase` - Index a sample codebase with optional custom ignore patterns
41 | - `search_code` - Search for code snippets
42 | - `clear_index` - Clear the index
43 |
44 | ## Making Changes
45 |
46 | 1. Create a new branch for your feature/fix
47 | 2. Edit `src/index.ts` - Main MCP server implementation
48 | 3. Verify with MCP clients (Claude Desktop, etc.)
49 | 4. Follow commit guidelines in the [main guide](../../CONTRIBUTING.md)
50 |
51 | ## MCP Protocol
52 |
53 | - Follow [MCP specification](https://modelcontextprotocol.io/)
54 | - Use stdio transport for compatibility
55 | - Handle errors gracefully with proper MCP responses
56 | - Redirect logs to stderr (not stdout)
57 |
58 | ## Tool Parameters
59 |
60 | ### `index_codebase`
61 | - `path` (required): Path to the codebase directory
62 | - `force` (optional): Force re-indexing even if already indexed (default: false)
63 | - `splitter` (optional): Code splitter type - 'ast' or 'langchain' (default: 'ast')
64 | - `ignorePatterns` (optional): Additional ignore patterns to add to defaults (default: [])
65 | - Examples: `["static/**", "*.tmp", "private/**", "docs/generated/**"]`
66 | - Merged with default patterns (node_modules, .git, etc.)
67 |
68 | ### `search_code`
69 | - `path` (required): Path to the indexed codebase
70 | - `query` (required): Natural language search query
71 | - `limit` (optional): Maximum number of results (default: 10, max: 50)
72 |
73 | ### `clear_index`
74 | - `path` (required): Path to the codebase to clear
75 |
76 | ## Guidelines
77 |
78 | - Keep tool interfaces simple and intuitive
79 | - Provide clear error messages
80 | - Validate all user inputs
81 | - Use TypeScript for type safety
82 |
83 | ## Working with MCP Clients
84 |
85 | ### Cursor/Claude Desktop Development Mode Configuration
86 | You can use the following configuration to configure the MCP server with a development mode.
87 | ```json
88 | {
89 | "mcpServers": {
90 | "claude-context-local": {
91 | "command": "node",
92 | "args": ["PATH_TO_CLAUDECONTEXT/packages/mcp/dist/index.js"],
93 | "env": {
94 | "OPENAI_API_KEY": "sk-your-openai-api-key",
95 | "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
96 | }
97 | }
98 | }
99 | }
100 | ```
101 |
102 | ### Claude Code Development Mode Configuration
103 | ```bash
104 | claude mcp add claude-context -e OPENAI_API_KEY=sk-your-openai-api-key -e MILVUS_TOKEN=your-zilliz-cloud-api-key -- node PATH_TO_CLAUDECONTEXT/packages/mcp/dist/index.js
105 | ```
106 | And then you can start Claude Code with `claude --debug` to see the MCP server logs.
107 |
108 | ### Manual Usage
109 | Use all three MCP tools:
110 | - `index_codebase` - Index sample repositories with optional custom ignore patterns
111 | Example with ignore patterns: `{"path": "/repo/path", "ignorePatterns": ["static/**", "*.tmp"]}`
112 | - `search_code` - Search with various queries
113 | - `clear_index` - Clear and re-index
114 |
115 | ## Questions?
116 |
117 | - **General questions**: See [main contributing guide](../../CONTRIBUTING.md)
118 | - **MCP-specific issues**: Open an issue with the `mcp` label
```
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
```markdown
1 | # Contributing to Claude Context
2 |
3 | Thank you for your interest in contributing to Claude Context! This guide will help you get started.
4 |
5 | ## 🚀 Getting Started
6 |
7 | ### Prerequisites
8 |
9 | - Node.js >= 20.0.0 and < 24.0.0
10 | - pnpm >= 10.0.0
11 | - Git
12 |
13 | ### Development Setup
14 |
15 | 1. **Fork and Clone**
16 |
17 | ```bash
18 | git clone https://github.com/your-username/claude-context.git
19 | cd claude-context
20 | ```
21 |
22 | 2. **Platform-Specific Setup**
23 |
24 | **Windows Users:**
25 |
26 | ```powershell
27 | # Configure git line endings (recommended)
28 | git config core.autocrlf false
29 |
30 | # Ensure pnpm is installed
31 | npm install -g pnpm
32 | ```
33 |
34 | **Linux/macOS Users:**
35 |
36 | ```bash
37 | # Standard setup - no additional configuration needed
38 | ```
39 |
40 | 3. **Install Dependencies**
41 |
42 | ```bash
43 | pnpm install
44 | ```
45 |
46 | 4. **Build All Packages**
47 |
48 | ```bash
49 | pnpm build
50 | ```
51 |
52 | 5. **Start Development Mode**
53 |
54 | ```bash
55 | pnpm dev
56 | ```
57 |
58 | ## 📁 Project Structure
59 |
60 | ```
61 | claude-context/
62 | ├── packages/
63 | │ ├── core/ # Core indexing engine
64 | │ ├── vscode-extension/ # VSCode extension
65 | │ └── mcp/ # Model Context Protocol server
66 | ├── examples/
67 | │ └── basic-usage/ # Basic usage example
68 | ```
69 |
70 | ### Package-Specific Development
71 |
72 | Each package has its own development guide with specific instructions:
73 |
74 | - **[Core Package](packages/core/CONTRIBUTING.md)** - Develop the core indexing engine
75 | - **[VSCode Extension](packages/vscode-extension/CONTRIBUTING.md)** - Develop the VSCode extension
76 | - **[MCP Server](packages/mcp/CONTRIBUTING.md)** - Develop the MCP protocol server
77 |
78 | ## 🛠️ Development Workflow
79 |
80 | ### Building All Packages
81 |
82 | ```bash
83 | # Build all packages
84 | pnpm build
85 |
86 | # Clean and rebuild
87 | pnpm clean && pnpm build
88 |
89 | # Development mode (watch all packages)
90 | pnpm dev
91 | ```
92 |
93 | ### Package-Specific Development
94 |
95 | For detailed development instructions for each package, see:
96 |
97 | - [Core Package Development](packages/core/CONTRIBUTING.md)
98 | - [VSCode Extension Development](packages/vscode-extension/CONTRIBUTING.md)
99 | - [MCP Server Development](packages/mcp/CONTRIBUTING.md)
100 |
101 | ## 📝 Making Changes
102 |
103 | ### Commit Guidelines
104 |
105 | We follow conventional commit format:
106 |
107 | ```
108 | type(scope): description
109 |
110 | feat(core): add new embedding provider
111 | fix(vscode): resolve search result display issue
112 | docs(readme): update installation instructions
113 | refactor(mcp): improve error handling
114 | ```
115 |
116 | **Types**: `feat`, `fix`, `docs`, `refactor`, `perf`, `chore`
117 |
118 | **Scopes**: `core`, `vscode`, `mcp`, `examples`, `docs`
119 |
120 | ### Pull Request Process
121 |
122 | 1. **Create Feature Branch**
123 |
124 | ```bash
125 | git checkout -b feature/your-feature-name
126 | ```
127 |
128 | 2. **Make Your Changes**
129 | - Keep changes focused and atomic
130 | - Update documentation if needed
131 |
132 | 3. **Build and Verify**
133 |
134 | ```bash
135 | pnpm build
136 | ```
137 |
138 | 4. **Commit Your Changes**
139 |
140 | ```bash
141 | git add .
142 | git commit -m "feat(core): add your feature description"
143 | ```
144 |
145 | 5. **Push and Create PR**
146 |
147 | ```bash
148 | git push origin feature/your-feature-name
149 | ```
150 |
151 | ## 🎯 Contribution Areas
152 |
153 | ### Priority Areas
154 |
155 | - **Core Engine**: Improve indexing performance and accuracy
156 | - **Embedding Providers**: Add support for more embedding services
157 | - **Vector Databases**: Extend database integration options
158 | - **Documentation**: Improve examples and guides
159 | - **Bug Fixes**: Fix reported issues
160 |
161 | ### Ideas for Contribution
162 |
163 | - Add support for new programming languages
164 | - Improve code chunking strategies
165 | - Enhance search result ranking
166 | - Add configuration options
167 | - Create more usage examples
168 |
169 | ## 📋 Reporting Issues
170 |
171 | When reporting bugs or requesting features:
172 |
173 | 1. **Check Existing Issues**: Search for similar issues first
174 | 2. **Use Templates**: Follow the issue templates when available
175 | 3. **Provide Context**: Include relevant details about your environment
176 | 4. **Steps to Reproduce**: Clear steps for reproducing bugs
177 |
178 | ## 💬 Getting Help
179 |
180 | - **GitHub Issues**: For bugs and feature requests
181 | - **GitHub Discussions**: For questions and general discussion
182 |
183 | ## 📄 License
184 |
185 | By contributing to Claude Context, you agree that your contributions will be licensed under the MIT License.
186 |
187 | ---
188 |
189 | Thank you for contributing to Claude Context! 🎉
190 |
```
--------------------------------------------------------------------------------
/packages/chrome-extension/CONTRIBUTING.md:
--------------------------------------------------------------------------------
```markdown
1 | # Contributing to Chrome Extension
2 |
3 | Thanks for your interest in contributing to the Claude Context Chrome extension!
4 |
5 | > 📖 **First time contributing?** Please read the [main contributing guide](../../CONTRIBUTING.md) first for general setup and workflow.
6 |
7 | ## Chrome Extension Development
8 |
9 | This guide covers development specific to the Chrome extension.
10 |
11 | ### Quick Commands
12 |
13 | ```bash
14 | # Build Chrome extension
15 | pnpm build:chrome
16 |
17 | # Watch mode for development
18 | pnpm dev:chrome
19 |
20 | # Clean build artifacts
21 | pnpm clean
22 |
23 | # Lint code
24 | pnpm lint
25 |
26 | # Type checking
27 | pnpm typecheck
28 |
29 | # Generate icons
30 | pnpm prebuild
31 | ```
32 |
33 | ### Development Setup
34 |
35 | 1. **Install Dependencies**:
36 |
37 | ```bash
38 | cd packages/chrome-extension
39 | pnpm install
40 | ```
41 |
42 | 2. **Build Extension**:
43 |
44 | ```bash
45 | pnpm build
46 | ```
47 |
48 | 3. **Load in Chrome**:
49 | - Open Chrome and go to `chrome://extensions/`
50 | - Enable "Developer mode"
51 | - Click "Load unpacked" and select the `dist` folder
52 |
53 | 4. **Development Mode**:
54 |
55 | ```bash
56 | pnpm dev # Watch mode for automatic rebuilds
57 | ```
58 |
59 | ## Making Changes
60 |
61 | 1. Create a new branch for your feature/fix
62 | 2. Make changes in the `src/` directory
63 | 3. Test in Chrome with "Reload extension" after changes
64 | 4. Follow commit guidelines in the [main guide](../../CONTRIBUTING.md)
65 |
66 | ## Project Structure
67 |
68 | ```
69 | src/
70 | ├── content.ts # Content script for GitHub integration
71 | ├── background.ts # Background service worker
72 | ├── options.ts # Options/settings page
73 | ├── options.html # Options page HTML
74 | ├── styles.css # Extension styles
75 | ├── manifest.json # Extension manifest
76 | ├── config/
77 | │ └── milvusConfig.ts # Milvus configuration
78 | ├── milvus/
79 | │ └── chromeMilvusAdapter.ts # Browser Milvus adapter
80 | ├── storage/
81 | │ └── indexedRepoManager.ts # Repository management
82 | ├── stubs/ # Browser compatibility stubs
83 | └── icons/ # Extension icons
84 | ```
85 |
86 | ## Development Workflow
87 |
88 | ### 1. Content Script Development
89 |
90 | - Modify `src/content.ts` for GitHub UI integration
91 | - Test on various GitHub repository pages
92 | - Ensure UI doesn't conflict with GitHub's interface
93 |
94 | ### 2. Background Service Worker
95 |
96 | - Edit `src/background.ts` for extension lifecycle management
97 | - Handle cross-tab communication and data persistence
98 | - Test extension startup and shutdown scenarios
99 |
100 | ### 3. Options Page
101 |
102 | - Update `src/options.ts` and `src/options.html` for settings
103 | - Test configuration persistence and validation
104 | - Ensure user-friendly error messages
105 |
106 | ### 4. Testing Workflow
107 |
108 | 1. Make changes to source files
109 | 2. Run `pnpm build` or use `pnpm dev` for watch mode
110 | 3. Go to `chrome://extensions/` and click "Reload" on the extension
111 | 4. Test functionality on GitHub repositories
112 | 5. Check Chrome DevTools console for errors
113 |
114 | ## Browser Compatibility
115 |
116 | ### WebPack Configuration
117 |
118 | - `webpack.config.js` handles Node.js polyfills for browser environment
119 | - Modules like `crypto`, `fs`, `path` are replaced with browser-compatible versions
120 |
121 | ### Key Polyfills
122 |
123 | - `crypto-browserify` - Cryptographic functions
124 | - `buffer` - Node.js Buffer API
125 | - `process` - Process environment variables
126 | - `path-browserify` - Path manipulation
127 | - `vm-browserify` - Virtual machine context
128 |
129 | ### Testing Browser Compatibility
130 |
131 | ```bash
132 | # Build and test in different browsers
133 | pnpm build
134 | # Load extension in Chrome, Edge, Brave, etc.
135 | ```
136 |
137 | ## Extension-Specific Guidelines
138 |
139 | ### Manifest V3 Compliance
140 |
141 | - Use service workers instead of background pages
142 | - Follow content security policy restrictions
143 | - Handle permissions properly
144 |
145 | ### Performance Considerations
146 |
147 | - Minimize content script impact on GitHub page load
148 | - Use efficient DOM manipulation
149 | - Lazy load heavy components
150 |
151 | ### Security Best Practices
152 |
153 | - Validate all user inputs
154 | - Sanitize HTML content
155 | - Use secure communication between scripts
156 | - Handle API keys securely
157 |
158 | ### UI/UX Guidelines
159 |
160 | - Match GitHub's design language
161 | - Provide loading states for async operations
162 | - Show clear error messages
163 | - Ensure accessibility compliance
164 |
165 | ## Chrome Extension Features
166 |
167 | ### Core Functionality
168 |
169 | - **Repository Indexing**: Parse GitHub repositories and create vector embeddings
170 | - **Semantic Search**: Natural language code search within repositories
171 | - **UI Integration**: Seamless GitHub interface enhancement
172 | - **Configuration Management**: User settings and API key management
173 |
174 | ### Advanced Features
175 |
176 | - **Cross-Repository Search**: Search across multiple indexed repositories
177 | - **Context-Aware Search**: Search similar code from selected snippets
178 | - **Progress Tracking**: Real-time indexing progress indicators
179 | - **Offline Support**: Local caching of indexed repositories
180 |
181 | ## Testing Checklist
182 |
183 | ### Manual Testing
184 |
185 | - [ ] Extension loads without errors
186 | - [ ] UI appears correctly on GitHub repository pages
187 | - [ ] Indexing works for public repositories
188 | - [ ] Search returns relevant results
189 | - [ ] Options page saves configuration correctly
190 | - [ ] Extension works across different GitHub page types
191 | - [ ] No conflicts with GitHub's native functionality
192 |
193 | ### Cross-Browser Testing
194 |
195 | - [ ] Chrome (latest)
196 | - [ ] Edge (Chromium-based)
197 | - [ ] Brave Browser
198 | - [ ] Other Chromium-based browsers
199 |
200 | ### GitHub Integration Testing
201 |
202 | - [ ] Repository home pages
203 | - [ ] File browser pages
204 | - [ ] Code view pages
205 | - [ ] Pull request pages
206 | - [ ] Different repository sizes
207 | - [ ] Private repositories (with token)
208 |
209 | ## Debugging
210 |
211 | ### Chrome DevTools
212 |
213 | 1. Right-click extension icon → "Inspect popup"
214 | 2. Go to GitHub page → F12 → check console for content script errors
215 | 3. `chrome://extensions/` → click "service worker" link for background script debugging
216 |
217 | ### Common Issues
218 |
219 | - **Permission errors**: Check manifest.json permissions
220 | - **CSP violations**: Verify content security policy compliance
221 | - **Module not found**: Check webpack polyfill configuration
222 | - **API errors**: Validate API keys and network connectivity
223 |
224 | ### Debug Commands
225 |
226 | ```bash
227 | # Check build output (Unix/macOS)
228 | ls -la dist/
229 |
230 | # Check build output (Windows PowerShell)
231 | Get-ChildItem dist/ | Format-Table -AutoSize
232 |
233 | # Validate manifest (Unix/macOS)
234 | cat dist/manifest.json | jq
235 |
236 | # Validate manifest (Windows PowerShell)
237 | Get-Content dist/manifest.json | ConvertFrom-Json | ConvertTo-Json -Depth 10
238 |
239 | # Check for TypeScript errors (cross-platform)
240 | pnpm typecheck
241 | ```
242 |
243 | ## Publishing Preparation
244 |
245 | ### Pre-Publishing Checklist
246 |
247 | - [ ] All tests pass
248 | - [ ] No console errors
249 | - [ ] Icons generated correctly
250 | - [ ] Manifest version updated
251 | - [ ] README updated with new features
252 | - [ ] Screenshots prepared for store listing
253 |
254 | ### Build for Production
255 |
256 | ```bash
257 | # Clean build
258 | pnpm clean
259 | pnpm build
260 |
261 | # Verify bundle size (Unix/macOS)
262 | ls -lh dist/
263 |
264 | # Verify bundle size (Windows PowerShell)
265 | Get-ChildItem dist/ | Select-Object Name, @{Name="Size";Expression={[math]::Round($_.Length/1KB,2)}} | Format-Table -AutoSize
266 | ```
267 |
268 | > **Note**: Only maintainers can publish to Chrome Web Store
269 |
270 | ## Questions?
271 |
272 | - **General questions**: See [main contributing guide](../../CONTRIBUTING.md)
273 | - **Chrome extension specific issues**: Open an issue with the `chrome-extension` label
274 | - **Browser compatibility**: Test across different Chromium browsers
275 | - **GitHub integration**: Ensure changes work across all GitHub page types
276 |
```
--------------------------------------------------------------------------------
/evaluation/retrieval/__init__.py:
--------------------------------------------------------------------------------
```python
1 |
```
--------------------------------------------------------------------------------
/evaluation/servers/__init__.py:
--------------------------------------------------------------------------------
```python
1 |
```
--------------------------------------------------------------------------------
/evaluation/utils/__init__.py:
--------------------------------------------------------------------------------
```python
1 |
```
--------------------------------------------------------------------------------
/packages/core/src/utils/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | export { EnvManager, envManager } from './env-manager';
```
--------------------------------------------------------------------------------
/pnpm-workspace.yaml:
--------------------------------------------------------------------------------
```yaml
1 | packages:
2 | - packages/*
3 | - examples/*
4 |
5 | ignoredBuiltDependencies:
6 | - faiss-node
7 |
```
--------------------------------------------------------------------------------
/packages/chrome-extension/src/vm-stub.js:
--------------------------------------------------------------------------------
```javascript
1 | // This file is intentionally left blank to act as a stub for the 'vm' module in the browser environment.
```
--------------------------------------------------------------------------------
/evaluation/utils/constant.py:
--------------------------------------------------------------------------------
```python
1 | from pathlib import Path
2 |
3 | evaluation_path = Path(__file__).parent.parent.absolute() # evaluation/
4 | project_path = evaluation_path.parent.absolute() # claude-context/
5 |
```
--------------------------------------------------------------------------------
/packages/core/src/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | export * from './splitter';
2 | export * from './embedding';
3 | export * from './vectordb';
4 | export * from './types';
5 | export * from './context';
6 | export * from './sync/synchronizer';
7 | export * from './utils';
```
--------------------------------------------------------------------------------
/packages/core/src/embedding/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | // Export base classes and interfaces
2 | export * from './base-embedding';
3 |
4 | // Implementation class exports
5 | export * from './openai-embedding';
6 | export * from './voyageai-embedding';
7 | export * from './ollama-embedding';
8 | export * from './gemini-embedding';
```
--------------------------------------------------------------------------------
/.vscode/extensions.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | // See http://go.microsoft.com/fwlink/?LinkId=827846
3 | // for the documentation about the extensions.json format
4 | "recommendations": [
5 | "dbaeumer.vscode-eslint",
6 | "ms-vscode.extension-test-runner",
7 | "ms-vscode.vscode-typescript-next",
8 | "ms-vscode.vscode-json"
9 | ]
10 | }
```
--------------------------------------------------------------------------------
/packages/chrome-extension/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "extends": "../../tsconfig.json",
3 | "compilerOptions": {
4 | "lib": ["ES2021", "DOM", "DOM.Iterable"],
5 | "types": ["chrome"],
6 | "noImplicitAny": false,
7 | "outDir": "dist"
8 | },
9 | "include": [
10 | "src/**/*.ts"
11 | ],
12 | "exclude": [
13 | "node_modules",
14 | "dist"
15 | ]
16 | }
```
--------------------------------------------------------------------------------
/packages/core/src/types.ts:
--------------------------------------------------------------------------------
```typescript
1 | export interface SearchQuery {
2 | term: string;
3 | includeContent?: boolean;
4 | limit?: number;
5 | }
6 |
7 | export interface SemanticSearchResult {
8 | content: string;
9 | relativePath: string;
10 | startLine: number;
11 | endLine: number;
12 | language: string;
13 | score: number;
14 | }
15 |
```
--------------------------------------------------------------------------------
/packages/vscode-extension/src/stubs/milvus-vectordb-stub.js:
--------------------------------------------------------------------------------
```javascript
1 | // Stub implementation for MilvusVectorDatabase to avoid gRPC dependencies in VSCode extension
2 | // This file replaces the actual milvus-vectordb.ts when bundling for VSCode
3 |
4 | class MilvusVectorDatabase {
5 | constructor(config) {
6 | throw new Error('MilvusVectorDatabase (gRPC) is not available in VSCode extension. Use MilvusRestfulVectorDatabase instead.');
7 | }
8 | }
9 |
10 | module.exports = {
11 | MilvusVectorDatabase
12 | };
```
--------------------------------------------------------------------------------
/packages/vscode-extension/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "extends": "../../tsconfig.json",
3 | "compilerOptions": {
4 | "module": "commonjs",
5 | "outDir": "./dist",
6 | "rootDir": "./src",
7 | "composite": true,
8 | "lib": [
9 | "ES2020"
10 | ],
11 | "skipLibCheck": true,
12 | "moduleResolution": "node"
13 | },
14 | "include": [
15 | "src/**/*"
16 | ],
17 | "exclude": [
18 | "dist",
19 | "node_modules"
20 | ],
21 | "references": [
22 | {
23 | "path": "../core"
24 | }
25 | ]
26 | }
```
--------------------------------------------------------------------------------
/evaluation/case_study/django_14170/both_result.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "instance_id": "django__django-14170",
3 | "hits": [
4 | "django/db/models/lookups.py"
5 | ],
6 | "oracles": [
7 | "django/db/models/lookups.py",
8 | "django/db/backends/base/operations.py"
9 | ],
10 | "token_usage": {
11 | "input_tokens": 8582,
12 | "output_tokens": 454,
13 | "total_tokens": 9036,
14 | "max_single_turn_tokens": 3829
15 | },
16 | "tool_stats": {
17 | "tool_call_counts": {
18 | "search_code": 1,
19 | "edit": 2
20 | },
21 | "total_tool_calls": 3
22 | },
23 | "retrieval_types": [
24 | "cc",
25 | "grep"
26 | ]
27 | }
```
--------------------------------------------------------------------------------
/evaluation/case_study/pydata_xarray_6938/both_result.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "instance_id": "pydata__xarray-6938",
3 | "hits": [
4 | "xarray/core/dataset.py",
5 | "xarray/core/dataarray.py"
6 | ],
7 | "oracles": [
8 | "xarray/core/variable.py",
9 | "xarray/core/dataset.py"
10 | ],
11 | "token_usage": {
12 | "input_tokens": 15428,
13 | "output_tokens": 398,
14 | "total_tokens": 15826,
15 | "max_single_turn_tokens": 6971
16 | },
17 | "tool_stats": {
18 | "tool_call_counts": {
19 | "search_code": 1,
20 | "edit": 2
21 | },
22 | "total_tool_calls": 3
23 | },
24 | "retrieval_types": [
25 | "cc",
26 | "grep"
27 | ]
28 | }
```
--------------------------------------------------------------------------------
/evaluation/pyproject.toml:
--------------------------------------------------------------------------------
```toml
1 | [project]
2 | name = "evaluation"
3 | version = "0.1.0"
4 | description = ""
5 | readme = "README.md"
6 | requires-python = ">=3.10"
7 | dependencies = [
8 | "langchain-mcp-adapters>=0.1.9",
9 | "langgraph>=0.6.4",
10 | "mcp>=1.12.4",
11 | "langchain>=0.1.0",
12 | "langchain-core>=0.1.0",
13 | "langchain-anthropic>=0.1.0",
14 | "langchain-openai>=0.3.29",
15 | "langchain-ollama>=0.3.6",
16 | "datasets>=4.0.0",
17 | "gitpython>=3.1.45",
18 | "matplotlib>=3.10.5",
19 | "seaborn>=0.13.2",
20 | "pandas>=2.3.1",
21 | "numpy>=2.2.6",
22 | "plotly>=6.3.0",
23 | "kaleido>=1.0.0",
24 | ]
25 |
```
--------------------------------------------------------------------------------
/evaluation/case_study/pydata_xarray_6938/grep_result.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "instance_id": "pydata__xarray-6938",
3 | "hits": [
4 | "xarray/core/dataarray.py",
5 | "xarray/core/dataset.py",
6 | "/data2/zha...ims",
7 | "xarray/core/common.py"
8 | ],
9 | "oracles": [
10 | "xarray/core/variable.py",
11 | "xarray/core/dataset.py"
12 | ],
13 | "token_usage": {
14 | "input_tokens": 40898,
15 | "output_tokens": 1101,
16 | "total_tokens": 41999,
17 | "max_single_turn_tokens": 8156
18 | },
19 | "tool_stats": {
20 | "tool_call_counts": {
21 | "list_directory": 3,
22 | "search_text": 1,
23 | "read_file": 3,
24 | "edit": 4
25 | },
26 | "total_tool_calls": 11
27 | }
28 | }
```
--------------------------------------------------------------------------------
/evaluation/case_study/django_14170/grep_result.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "instance_id": "django__django-14170",
3 | "hits": [
4 | "django/db/models/functions/datetime.py",
5 | "tests/db_functions/datetime/test_extract_trunc.py"
6 | ],
7 | "oracles": [
8 | "django/db/backends/base/operations.py",
9 | "django/db/models/lookups.py"
10 | ],
11 | "token_usage": {
12 | "input_tokens": 130064,
13 | "output_tokens": 755,
14 | "total_tokens": 130819,
15 | "max_single_turn_tokens": 26750
16 | },
17 | "tool_stats": {
18 | "tool_call_counts": {
19 | "directory_tree": 1,
20 | "search_text": 1,
21 | "edit": 6
22 | },
23 | "total_tool_calls": 8
24 | },
25 | "retrieval_types": [
26 | "grep"
27 | ]
28 | }
```
--------------------------------------------------------------------------------
/examples/basic-usage/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "claude-context-basic-example",
3 | "version": "0.1.3",
4 | "description": "Basic usage example for Claude Context",
5 | "main": "index.ts",
6 | "scripts": {
7 | "start": "tsx index.ts",
8 | "build": "tsc index.ts --outDir dist --target es2020 --module commonjs --moduleResolution node --esModuleInterop true",
9 | "dev": "tsx --watch index.ts"
10 | },
11 | "dependencies": {
12 | "@zilliz/claude-context-core": "workspace:*"
13 | },
14 | "devDependencies": {
15 | "tsx": "^4.0.0",
16 | "typescript": "^5.0.0",
17 | "@types/node": "^20.0.0",
18 | "dotenv": "^16.0.0"
19 | },
20 | "private": true
21 | }
```
--------------------------------------------------------------------------------
/packages/mcp/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "compilerOptions": {
3 | "target": "ES2020",
4 | "module": "ES2020",
5 | "lib": [
6 | "ES2020"
7 | ],
8 | "declaration": true,
9 | "declarationMap": true,
10 | "sourceMap": true,
11 | "outDir": "./dist",
12 | "rootDir": "./src",
13 | "strict": true,
14 | "esModuleInterop": true,
15 | "skipLibCheck": true,
16 | "forceConsistentCasingInFileNames": true,
17 | "moduleResolution": "node",
18 | "composite": true
19 | },
20 | "include": [
21 | "src/**/*"
22 | ],
23 | "exclude": [
24 | "dist",
25 | "node_modules"
26 | ],
27 | "references": [
28 | {
29 | "path": "../core"
30 | }
31 | ]
32 | }
```
--------------------------------------------------------------------------------
/.vscode/settings.json:
--------------------------------------------------------------------------------
```json
1 | // Place your settings in this file to overwrite default and user settings.
2 | {
3 | "files.exclude": {
4 | "**/node_modules": true,
5 | "**/dist": false,
6 | "**/out": false
7 | },
8 | "search.exclude": {
9 | "**/node_modules": true,
10 | "**/dist": true,
11 | "**/out": true
12 | },
13 | // Turn off tsc task auto detection since we have the necessary tasks as npm scripts
14 | "typescript.tsc.autoDetect": "off",
15 | "typescript.preferences.includePackageJsonAutoImports": "on",
16 | // ESLint settings
17 | "eslint.workingDirectories": [
18 | "packages/vscode-extension",
19 | "packages/core"
20 | ],
21 | // Format on save
22 | "editor.formatOnSave": true,
23 | "editor.codeActionsOnSave": {
24 | "source.fixAll.eslint": "explicit"
25 | }
26 | }
```
--------------------------------------------------------------------------------
/packages/core/src/vectordb/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | // Re-export types and interfaces
2 | export {
3 | VectorDocument,
4 | SearchOptions,
5 | VectorSearchResult,
6 | VectorDatabase,
7 | HybridSearchRequest,
8 | HybridSearchOptions,
9 | HybridSearchResult,
10 | RerankStrategy,
11 | COLLECTION_LIMIT_MESSAGE
12 | } from './types';
13 |
14 | // Implementation class exports
15 | export { MilvusRestfulVectorDatabase, MilvusRestfulConfig } from './milvus-restful-vectordb';
16 | export { MilvusVectorDatabase, MilvusConfig } from './milvus-vectordb';
17 | export {
18 | ClusterManager,
19 | ZillizConfig,
20 | Project,
21 | Cluster,
22 | CreateFreeClusterRequest,
23 | CreateFreeClusterResponse,
24 | CreateFreeClusterWithDetailsResponse,
25 | DescribeClusterResponse
26 | } from './zilliz-utils';
```
--------------------------------------------------------------------------------
/.vscode/tasks.json:
--------------------------------------------------------------------------------
```json
1 | // See https://go.microsoft.com/fwlink/?LinkId=733558
2 | // for the documentation about the tasks.json format
3 | {
4 | "version": "2.0.0",
5 | "tasks": [
6 | {
7 | "type": "npm",
8 | "script": "webpack:dev",
9 | "path": "packages/vscode-extension/",
10 | "problemMatcher": "$tsc-watch",
11 | "isBackground": true,
12 | "presentation": {
13 | "reveal": "never"
14 | },
15 | "group": {
16 | "kind": "build",
17 | "isDefault": true
18 | }
19 | },
20 | {
21 | "type": "npm",
22 | "script": "webpack",
23 | "path": "packages/vscode-extension/",
24 | "group": "build",
25 | "presentation": {
26 | "echo": true,
27 | "reveal": "silent",
28 | "focus": false,
29 | "panel": "shared",
30 | "showReuseMessage": true,
31 | "clear": false
32 | },
33 | "problemMatcher": "$tsc"
34 | }
35 | ]
36 | }
```
--------------------------------------------------------------------------------
/evaluation/utils/llm_factory.py:
--------------------------------------------------------------------------------
```python
1 | from langchain_openai import ChatOpenAI
2 | from langchain_ollama import ChatOllama
3 | from langchain_anthropic import ChatAnthropic
4 | import os
5 |
6 |
7 | def llm_factory(llm_type: str, llm_model: str):
8 | if llm_type == "openai":
9 | return ChatOpenAI(model=llm_model)
10 | elif llm_type == "ollama":
11 | return ChatOllama(model=llm_model)
12 | elif llm_type == "moonshot":
13 | return ChatOpenAI(
14 | model=llm_model,
15 | base_url="https://api.moonshot.cn/v1",
16 | api_key=os.getenv("MOONSHOT_API_KEY"),
17 | )
18 | elif llm_type == "anthropic":
19 | return ChatAnthropic(model=llm_model, api_key=os.getenv("ANTHROPIC_API_KEY"))
20 | else:
21 | raise ValueError(f"Unsupported LLM type: {llm_type}")
22 |
```
--------------------------------------------------------------------------------
/packages/core/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "compilerOptions": {
3 | "target": "ES2020",
4 | "module": "commonjs",
5 | "lib": [
6 | "ES2020"
7 | ],
8 | "declaration": true,
9 | "declarationMap": true,
10 | "sourceMap": true,
11 | "outDir": "./dist",
12 | "rootDir": "./src",
13 | "strict": true,
14 | "esModuleInterop": true,
15 | "skipLibCheck": true,
16 | "forceConsistentCasingInFileNames": true,
17 | "moduleResolution": "node",
18 | "composite": true,
19 | "allowSyntheticDefaultImports": true,
20 | "downlevelIteration": true,
21 | "incremental": true,
22 | "tsBuildInfoFile": "./dist/.tsbuildinfo"
23 | },
24 | "include": [
25 | "src/**/*"
26 | ],
27 | "exclude": [
28 | "dist",
29 | "node_modules"
30 | ]
31 | }
```
--------------------------------------------------------------------------------
/packages/mcp/src/utils.ts:
--------------------------------------------------------------------------------
```typescript
1 | import * as path from "path";
2 |
3 | /**
4 | * Truncate content to specified length
5 | */
6 | export function truncateContent(content: string, maxLength: number): string {
7 | if (content.length <= maxLength) {
8 | return content;
9 | }
10 | return content.substring(0, maxLength) + '...';
11 | }
12 |
13 | /**
14 | * Ensure path is absolute. If relative path is provided, resolve it properly.
15 | */
16 | export function ensureAbsolutePath(inputPath: string): string {
17 | // If already absolute, return as is
18 | if (path.isAbsolute(inputPath)) {
19 | return inputPath;
20 | }
21 |
22 | // For relative paths, resolve to absolute path
23 | const resolved = path.resolve(inputPath);
24 | return resolved;
25 | }
26 |
27 | export function trackCodebasePath(codebasePath: string): void {
28 | const absolutePath = ensureAbsolutePath(codebasePath);
29 | console.log(`[TRACKING] Tracked codebase path: ${absolutePath} (not marked as indexed)`);
30 | }
```
--------------------------------------------------------------------------------
/build-benchmark.json:
--------------------------------------------------------------------------------
```json
1 | [
2 | {
3 | "timestamp": "2025-08-25T19:04:13.664Z",
4 | "platform": "win32",
5 | "nodeVersion": "v22.15.1",
6 | "results": [
7 | {
8 | "success": true,
9 | "duration": 1849,
10 | "command": "pnpm clean",
11 | "description": "Clean all packages"
12 | },
13 | {
14 | "success": true,
15 | "duration": 6754,
16 | "command": "pnpm build:core",
17 | "description": "Build core package"
18 | },
19 | {
20 | "success": true,
21 | "duration": 9782,
22 | "command": "pnpm build:mcp",
23 | "description": "Build MCP package"
24 | },
25 | {
26 | "success": true,
27 | "duration": 6821,
28 | "command": "pnpm build:vscode",
29 | "description": "Build VSCode extension"
30 | },
31 | {
32 | "success": true,
33 | "duration": 14526,
34 | "command": "pnpm -r --filter=\"./packages/chrome-extension\" build",
35 | "description": "Build Chrome extension"
36 | }
37 | ]
38 | }
39 | ]
```
--------------------------------------------------------------------------------
/.github/workflows/release.yml:
--------------------------------------------------------------------------------
```yaml
1 | name: Release
2 |
3 | on:
4 | push:
5 | tags:
6 | - 'v*'
7 | - 'c*'
8 |
9 | jobs:
10 | release:
11 | runs-on: ubuntu-latest
12 |
13 | steps:
14 | - name: Checkout code
15 | uses: actions/checkout@v4
16 |
17 | - name: Install pnpm
18 | uses: pnpm/action-setup@v4
19 | with:
20 | version: 10
21 |
22 | - name: Setup Node.js
23 | uses: actions/setup-node@v4
24 | with:
25 | node-version: '20.x'
26 | cache: 'pnpm'
27 |
28 | - name: Install dependencies
29 | run: pnpm install --frozen-lockfile
30 |
31 | - name: Setup npm auth
32 | run: |
33 | echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc
34 |
35 | - name: Build packages
36 | run: pnpm build
37 |
38 | - name: Publish core package to npm
39 | run: pnpm --filter @zilliz/claude-context-core publish --access public --no-git-checks
40 |
41 | - name: Publish mcp package to npm
42 | run: pnpm --filter @zilliz/claude-context-mcp publish --access public --no-git-checks
43 |
44 | - name: Publish vscode extension
45 | run: pnpm release:vscode
46 | env:
47 | VSCE_PAT: ${{ secrets.VSCE_PAT }}
48 |
49 |
```
--------------------------------------------------------------------------------
/.vscode/launch.json:
--------------------------------------------------------------------------------
```json
1 | // A launch configuration that compiles the extension and then opens it inside a new window
2 | // Use IntelliSense to learn about possible attributes.
3 | // Hover to view descriptions of existing attributes.
4 | // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
5 | {
6 | "version": "0.2.0",
7 | "configurations": [
8 | {
9 | "name": "Run Extension",
10 | "type": "extensionHost",
11 | "request": "launch",
12 | "args": [
13 | "--extensionDevelopmentPath=${workspaceFolder}/packages/vscode-extension"
14 | ],
15 | "outFiles": [
16 | "${workspaceFolder}/packages/vscode-extension/dist/**/*.js"
17 | ],
18 | "preLaunchTask": "npm: webpack:dev - packages/vscode-extension"
19 | },
20 | {
21 | "name": "Extension Tests",
22 | "type": "extensionHost",
23 | "request": "launch",
24 | "args": [
25 | "--extensionDevelopmentPath=${workspaceFolder}/packages/vscode-extension",
26 | "--extensionTestsPath=${workspaceFolder}/packages/vscode-extension/dist/test/suite/index"
27 | ],
28 | "outFiles": [
29 | "${workspaceFolder}/packages/vscode-extension/dist/test/**/*.js"
30 | ],
31 | "preLaunchTask": "npm: webpack:dev - packages/vscode-extension"
32 | }
33 | ]
34 | }
```
--------------------------------------------------------------------------------
/packages/core/src/splitter/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | // Interface definitions
2 | export interface CodeChunk {
3 | content: string;
4 | metadata: {
5 | startLine: number;
6 | endLine: number;
7 | language?: string;
8 | filePath?: string;
9 | };
10 | }
11 |
12 | // Splitter type enumeration
13 | export enum SplitterType {
14 | LANGCHAIN = 'langchain',
15 | AST = 'ast'
16 | }
17 |
18 | // Splitter configuration interface
19 | export interface SplitterConfig {
20 | type?: SplitterType;
21 | chunkSize?: number;
22 | chunkOverlap?: number;
23 | }
24 |
25 | export interface Splitter {
26 | /**
27 | * Split code into code chunks
28 | * @param code Code content
29 | * @param language Programming language
30 | * @param filePath File path
31 | * @returns Array of code chunks
32 | */
33 | split(code: string, language: string, filePath?: string): Promise<CodeChunk[]>;
34 |
35 | /**
36 | * Set chunk size
37 | * @param chunkSize Chunk size
38 | */
39 | setChunkSize(chunkSize: number): void;
40 |
41 | /**
42 | * Set chunk overlap size
43 | * @param chunkOverlap Chunk overlap size
44 | */
45 | setChunkOverlap(chunkOverlap: number): void;
46 | }
47 |
48 | // Implementation class exports
49 | export * from './langchain-splitter';
50 | export * from './ast-splitter';
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "compilerOptions": {
3 | "target": "ES2020",
4 | "module": "commonjs",
5 | "lib": [
6 | "ES2020"
7 | ],
8 | "declaration": true,
9 | "declarationMap": true,
10 | "sourceMap": true,
11 | "strict": true,
12 | "esModuleInterop": true,
13 | "skipLibCheck": true,
14 | "forceConsistentCasingInFileNames": true,
15 | "moduleResolution": "node",
16 | "composite": true,
17 | "resolveJsonModule": true,
18 | "allowSyntheticDefaultImports": true,
19 | "baseUrl": ".",
20 | "downlevelIteration": true,
21 | "incremental": true,
22 | "tsBuildInfoFile": ".tsbuildinfo",
23 | "paths": {
24 | "@zilliz/claude-context-core": [
25 | "./packages/core/src"
26 | ],
27 | "@zilliz/claude-context-core/*": [
28 | "./packages/core/src/*"
29 | ]
30 | }
31 | },
32 | "references": [
33 | {
34 | "path": "./packages/core"
35 | },
36 | {
37 | "path": "./packages/vscode-extension"
38 | },
39 | {
40 | "path": "./packages/chrome-extension"
41 | },
42 | {
43 | "path": "./packages/mcp"
44 | }
45 | ],
46 | "files": []
47 | }
```
--------------------------------------------------------------------------------
/packages/chrome-extension/src/manifest.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "manifest_version": 3,
3 | "name": "GitHub Code Vector Search",
4 | "version": "1.0",
5 | "description": "Index GitHub repository code and perform vector search.",
6 | "content_security_policy": {
7 | "extension_pages": "script-src 'self' 'wasm-unsafe-eval'"
8 | },
9 | "action": {
10 | "default_icon": {
11 | "16": "icons/icon16.png",
12 | "32": "icons/icon32.png",
13 | "48": "icons/icon48.png",
14 | "128": "icons/icon128.png"
15 | }
16 | },
17 | "permissions": [
18 | "storage",
19 | "scripting",
20 | "unlimitedStorage"
21 | ],
22 | "host_permissions": [
23 | "https://github.com/*",
24 | "https://api.openai.com/*",
25 | "http://*/*",
26 | "https://*/*"
27 | ],
28 | "background": {
29 | "service_worker": "background.js"
30 | },
31 | "content_scripts": [
32 | {
33 | "matches": [
34 | "https://github.com/*/*"
35 | ],
36 | "js": [
37 | "content.js"
38 | ],
39 | "css": [
40 | "styles.css"
41 | ]
42 | }
43 | ],
44 | "options_ui": {
45 | "page": "options.html",
46 | "open_in_tab": true
47 | },
48 | "web_accessible_resources": [
49 | {
50 | "resources": [
51 | "ort-wasm-simd-threaded.wasm",
52 | "options.html",
53 | "options.js"
54 | ],
55 | "matches": [
56 | "<all_urls>"
57 | ]
58 | }
59 | ]
60 | }
```
--------------------------------------------------------------------------------
/evaluation/servers/edit_server.py:
--------------------------------------------------------------------------------
```python
1 | #!/usr/bin/env python3
2 | """
3 | An edit server using MCP (Model Context Protocol).
4 | This server provides file editing functionality for modifying files.
5 | """
6 |
7 | import os
8 | from mcp.server.fastmcp import FastMCP
9 |
10 | # Create the MCP server
11 | mcp = FastMCP("Edit Server")
12 |
13 |
14 | @mcp.tool()
15 | def edit(file_path: str, old_string: str, new_string: str) -> str:
16 | """Edits the specified file with the given modifications.
17 |
18 | This tool marks files that need to be edited with the specified changes.
19 |
20 | Args:
21 | file_path: The absolute path to the file to modify.
22 | old_string: The exact literal text to replace. Must uniquely identify the single
23 | instance to change. Should include at least 3 lines of context before
24 | and after the target text, matching whitespace and indentation precisely.
25 | If old_string is empty, the tool attempts to create a new file at
26 | file_path with new_string as content.
27 | new_string: The exact literal text to replace old_string with.
28 |
29 | Returns:
30 | A string indicating the file has been successfully modified.
31 | """
32 | # Mock the edit operation
33 | return f"Successfully modified file: {file_path}"
34 |
35 |
36 | if __name__ == "__main__":
37 | # Run the server with stdio transport
38 | mcp.run(transport="stdio")
39 |
```
--------------------------------------------------------------------------------
/packages/mcp/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "@zilliz/claude-context-mcp",
3 | "version": "0.1.3",
4 | "description": "Model Context Protocol integration for Claude Context",
5 | "type": "module",
6 | "main": "dist/index.js",
7 | "types": "dist/index.d.ts",
8 | "bin": "dist/index.js",
9 | "scripts": {
10 | "build": "pnpm clean && tsc --build --force",
11 | "dev": "tsx --watch src/index.ts",
12 | "clean": "rimraf dist",
13 | "lint": "eslint src --ext .ts",
14 | "lint:fix": "eslint src --ext .ts --fix",
15 | "typecheck": "tsc --noEmit",
16 | "start": "tsx src/index.ts",
17 | "start:with-env": "OPENAI_API_KEY=${OPENAI_API_KEY:your-api-key-here} MILVUS_ADDRESS=${MILVUS_ADDRESS:localhost:19530} tsx src/index.ts",
18 | "prepublishOnly": "pnpm build"
19 | },
20 | "dependencies": {
21 | "@zilliz/claude-context-core": "workspace:*",
22 | "@modelcontextprotocol/sdk": "^1.12.1",
23 | "zod": "^3.25.55"
24 | },
25 | "devDependencies": {
26 | "@types/node": "^20.0.0",
27 | "tsx": "^4.19.4",
28 | "typescript": "^5.0.0"
29 | },
30 | "files": [
31 | "dist",
32 | "README.md"
33 | ],
34 | "repository": {
35 | "type": "git",
36 | "url": "https://github.com/zilliztech/claude-context.git",
37 | "directory": "packages/mcp"
38 | },
39 | "license": "MIT",
40 | "publishConfig": {
41 | "access": "public"
42 | }
43 | }
```
--------------------------------------------------------------------------------
/packages/core/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "@zilliz/claude-context-core",
3 | "version": "0.1.3",
4 | "description": "Core indexing engine for Claude Context",
5 | "main": "dist/index.js",
6 | "types": "dist/index.d.ts",
7 | "scripts": {
8 | "build": "pnpm clean && tsc --build --force",
9 | "dev": "tsc --watch",
10 | "clean": "rimraf dist",
11 | "lint": "eslint src --ext .ts",
12 | "lint:fix": "eslint src --ext .ts --fix",
13 | "typecheck": "tsc --noEmit"
14 | },
15 | "dependencies": {
16 | "@google/genai": "^1.9.0",
17 | "@zilliz/milvus2-sdk-node": "^2.5.10",
18 | "faiss-node": "^0.5.1",
19 | "fs-extra": "^11.0.0",
20 | "glob": "^10.0.0",
21 | "langchain": "^0.3.27",
22 | "ollama": "^0.5.16",
23 | "openai": "^5.1.1",
24 | "tree-sitter": "^0.21.1",
25 | "tree-sitter-cpp": "^0.22.0",
26 | "tree-sitter-go": "^0.21.0",
27 | "tree-sitter-java": "^0.21.0",
28 | "tree-sitter-javascript": "^0.21.0",
29 | "tree-sitter-python": "^0.21.0",
30 | "tree-sitter-c-sharp": "^0.21.0",
31 | "tree-sitter-rust": "^0.21.0",
32 | "tree-sitter-typescript": "^0.21.0",
33 | "tree-sitter-scala": "^0.24.0",
34 | "typescript": "^5.0.0",
35 | "voyageai": "^0.0.4"
36 | },
37 | "devDependencies": {
38 | "@types/fs-extra": "^11.0.0",
39 | "@types/jest": "^30.0.0",
40 | "@types/mock-fs": "^4.13.4",
41 | "jest": "^30.0.0",
42 | "mock-fs": "^5.5.0",
43 | "ts-jest": "^29.4.0"
44 | },
45 | "files": [
46 | "dist",
47 | "README.md"
48 | ],
49 | "repository": {
50 | "type": "git",
51 | "url": "https://github.com/zilliztech/claude-context.git",
52 | "directory": "packages/core"
53 | },
54 | "license": "MIT",
55 | "publishConfig": {
56 | "access": "public"
57 | }
58 | }
```