Content
# Tool List
**CodeIndex** is a **local MCP server** that indexes source code (.cs / .h / .cpp) and returns relevant code chunks for natural language queries. It is compatible with AI clients that support MCP, such as VS Code, Visual Studio 2022, and Claude Desktop.
## Features
- **Project-based filtering** — Index and search multiple projects simultaneously, with the ability to limit the search scope to a specific project.
- **Automatic installation and management of Qdrant vector DB (https://qdrant.tech/)** — Automatically downloads and manages the Qdrant binary on the first run, and manages it as a subprocess.
- **Automatic detection of GPU and installation of CUDA wheel** — Automatically installs the appropriate PyTorch CUDA version when an NVIDIA GPU is detected.
- **Incremental indexing based on SHA-256** — Reprocesses only changed files for fast updates, even in large codebases.
- **Content_hash embedding caching** — Caches embedding vectors of identical code chunks in SQLite to improve re-indexing speed.
- **Tree-sitter AST parsing** — Analyzes C++/C/C# source code as an Abstract Syntax Tree (AST) for precise identification of functions, classes, methods, and namespaces.
- **Dense (HNSW) + BM25 hybrid search + RRF score combination** — Combines semantic vector search and keyword-based BM25 to improve accuracy.
- **Ranking reordering** — Reorders search results using a cross-encoder model to improve accuracy (`use_reranker: true`).
- **MCP server support** — Supports two transmission methods: stdio and HTTP (streamable-http).
## Requirements
- Python 3.11+
- NVIDIA GPU recommended (CPU operation possible, but with slower speed)
- NVIDIA GPU users need to install CUDA 11.8+ or 12.x drivers (https://developer.nvidia.com/cuda-downloads)
## Installation and Integration with MCP Server Editor
1. **Clone and install** — Clone the repository and package it as a Python package.
```powershell
git clone https://github.com/ChoiIngon/CodeIndex.git
cd CodeIndex
pip install -e .
```
- `pip install -e .` registers the `code_index` command in the system. Afterward, it can be executed from any directory using `python -m code_index` or `code_index`.
- **Modules with dependencies are automatically installed on the first run.** If a GPU is detected, the appropriate PyTorch version is automatically selected.
- **Note**: In a GPU environment, a stable PyTorch version compatible with CUDA 11.8+ or 12.x is automatically installed. If no GPU is detected, the CPU version is used.
2. **Personalized settings** — Add project-specific indexing settings to `config/settings.json` (see [Settings](#settings) for details).
Copy `config/settings.json.template` and modify it to use `config/settings.json`.
**2-1. Set indexing target project paths**
```json
{
"indexer": {
"GameClient": {
"source_paths": ["C:/MyProject/Client/Assets"], // Use absolute paths
"extensions": [".cs"]
},
"GameServer": {
"source_paths": ["C:/MyProject/Server/src1"],
"extensions": [".cpp", ".h", ".c"]
}
}
}
```
**2-2. Set indexing data storage location**
```json
{
"vector_store": {
"data_dir": "C:/MyProject/CodeIndex/data"
}
}
```
3. **Run MCP server and integrate with editor**
**3-1. HTTP mode** (recommended)
Run the MCP server first, then register the URL in each editor.
```powershell
python -m code_index --http-port 6380
```
**VS Code / Visual Studio 2022** — mcp.json
```json
{
"servers": {
"CodeIndex": {
"type": "http",
"url": "http://127.0.0.1:6380/mcp"
}
}
}
```
**Claude Desktop** — claude_desktop_config.json
```json
{
"mcpServers": {
"CodeIndex": {
"type": "http",
"url": "http://127.0.0.1:6380/mcp"
}
}
}
```
**3-2. stdio mode** (not recommended)
In stdio mode, there is no need to run the MCP server process separately; the editor directly starts the process.
> For large projects, loading times can be long, and the editor may timeout when creating a child process.
**VS Code / Visual Studio 2022** — mcp.json
```json
{
"servers": {
"CodeIndex": {
"type": "stdio",
"command": "python",
"args": [ "-m", "code_index" ],
"env": {
"PYTHONPATH": "E:\\work\\CodeIndex"
}
}
}
}
```
**Claude Desktop** — claude_desktop_config.json
```json
{
"mcpServers": {
"CodeIndex": {
"command": "python",
"args": ["-m", "code_index"],
"cwd": "E:/work/CodeIndex"
}
}
}
```
**3-3. MCP setting file path**
| Editor | Priority | Path | Scope |
|----------|----------|------|------|
| VSCode| 1 | <workspace_folder>/.vscode/mcp.json | Workspace unit |
| | 2 | %USERPROFILE%/.vscode/mcp.json | Global (user-wide) |
| Visual Studio 2022| 1 | <solution_folder>/.vs/mcp.json | Solution unit (VS-specific) |
| | 2 | <solution_folder>/.vscode/mcp.json | Solution unit (shared with VS Code) |
| | 3 | %USERPROFILE%/.mcp.json | Global (user-wide) |
| Claude Desktop | 1 | %APPDATA%\Claude\claude_desktop_config.json | Global (user-wide) |
> Note: Claude Desktop only supports a single global configuration file and does not support separate paths for workspaces or projects.
## Settings
Manage project-specific indexing settings in the `config/settings.json` file.
```json
{
"indexer": {
"chunk_min_lines": 5,
"chunk_max_lines": 80,
"chunk_overlap_lines": 10,
"chunk_workers": 0,
"GameServer": {
"source_paths": ["C:/MyProject/Server"],
"extensions": [".cpp", ".h", ".c"],
"exclude_patterns": ["*/build/*", "*/.git/*", "*/Utility/*"]
},
"GameClient": {
"source_paths": ["C:/MyProject/Client/Assets"],
"extensions": [".cs"],
"exclude_patterns": ["*/Library/*", "*/Packages/*"]
}
},
"models": {
"cache_dir": "",
"embed": "BAAI/bge-m3",
"rerank": "cross-encoder/ms-marco-MiniLM-L-12-v2"
},
"embedding": {
"vector_size": 1024,
"batch_size": 64,
"n_gpu_layers": -1
},
"vector_store": {
"mode": "server",
"host": "localhost",
"port": 6333,
"data_dir": "./data"
},
"search": {
"top_k": 20,
"rerank_top_k": 8,
"min_score": 0.0,
"alpha": 0.5,
"use_reranker": false
},
"debug": false
}
```
### indexer
**Structure**: `"indexer": { "chunk_settings...", "ProjectName": { ... }, "AnotherProject": { ... } }`
#### Shared chunking settings (applies to all projects)
| Item | Description | Default |
|---|---|---|
| `chunk_min_lines` | Symbols with fewer lines than this value are excluded from chunks | `5` |
| `chunk_max_lines` | Maximum lines in a chunk. If exceeded, split while maintaining overlap | `80` |
| `chunk_overlap_lines` | Overlapping lines between divided chunks. Maintains context continuity | `10` |
| `chunk_workers` | Number of chunking parallel processes. `0` = Automatically uses half of CPU cores | `0` |
#### Project-specific settings
Each project can have independent settings:
| Item | Description | Default |
|---|---|---|
| `source_paths` | List of source paths for indexing in the project. Absolute/relative paths | `[]` |
| `extensions` | List of file extensions for indexing in the project | `[".cpp", ".h", ".c", ".cs"]` |
| `exclude_patterns` | Path patterns (glob) to exclude for the project | `["*/build/*", "*/.git/*", "*/generated/*"]` |
**Example**:
- `GameServer`: Only C++ files, excluding Utility folder
- `Middleware`: Only C# files, excluding Unity-related folders
**Project-based filtering usage cases**:
- Packet compatibility verification: Comparing `serialize` in GameServer and `deserialize` in Middleware
- Language-specific coding pattern analysis: Identifying differences in implementation between C++ and C#
- Inter-project API consistency check: Verifying interface implementations in common modules
### models
| Item | Description | Default |
|---|---|---|
| `cache_dir` | Model download cache path. If empty, uses `.cache/` in the project root | `""` |
| `embed` | HuggingFace ID for the embedding model. Changing requires updating `vector_size` and re-indexing | `"BAAI/bge-m3"` |
| `rerank` | HuggingFace ID for the reranker model. Loaded only when `search.use_reranker: true` | `"cross-encoder/ms-marco-MiniLM-L-12-v2"` |
### embedding
| Item | Description | Default |
|---|---|---|
| `vector_size` | Embedding vector dimensions. Must match the output dimensions of the `models.embed` model | `1024` |
| `batch_size` | Embedding batch size. Adjust according to GPU VRAM (RTX 3060: 64, RTX 4090: 128+) | `64` |
| `n_gpu_layers` | (Reserved) Number of GPU layers. Currently unused | `-1` |
### vector_store
| Item | Description | Default |
|---|---|---|
| `mode` | `"server"`: Use a separate Qdrant process (recommended), `"embedded"`: Use an embedded mode within the Python process | `"server"` |
| `host` | Qdrant server host. Used when `mode: "server"` | `"localhost"` |
| `port` | Qdrant HTTP port. gRPC uses `port + 1` automatically | `6333` |
| `data_dir` | Root path for data storage. Subdirectories `qdrant/`, `metadata.db`, and `embed_cache.db` are created under this path | `"./data"` or `"C:\data` |
> **Server mode**: On the first run, it automatically downloads `.cache/qdrant/qdrant.exe` from GitHub Releases and starts it as a background process. It terminates when `code_index` exits.
### search
| Item | Description | Default |
|---|---|---|
| `top_k` | Number of search results returned. If using a reranker, this number of candidates is selected and then compressed by `rerank_top_k` | `20` |
| `rerank_top_k` | Final number of results returned by the reranker. Applied only when `use_reranker: true` | `8` |
| `min_score` | Minimum score filter. Results below this value are excluded (`0.0` = no filter) | `0.0` |
| `alpha` | Dense/BM25 weight. `1.0` = Dense only, `0.0` = BM25 only, `0.5` = Equal mix | `0.5` |
| `use_reranker` | If `true`, results are reordered using the `models.rerank` model to improve accuracy. Slightly decreases speed | `false` |
### Debugging
| Item | Description | Default |
|---|---|---|
| `debug` | If `true`, MCP requests/responses are recorded in `log.txt` | `false` |
## Execution
* Perform indexing only
```powershell
python -m code_index --index-only
```
* Run MCP server in stdio mode (single editor)
```powershell
python -m code_index
```
* Run MCP server in HTTP mode (multiple editors)
```powershell
python -m code_index --http-port 6380
```
* Check indexing status
```powershell
python -m code_index --status
```
* CLI search (direct query without MCP)
```powershell
# Natural language search
python -m code_index --search-code "damage calculation logic"
# Filter options
python -m code_index --search-code "CalculateDamage" --top-k 10 --language cpp --symbol-type function
# Project-specific search (search only in GameServer project)
python -m code_index --search-code "QA_Login serialize" --project "GameServer" --top-k 5
# Inter-project comparison analysis example
python -m code_index --search-code "QA_Login serialize" --project "GameServer" --top-k 3
python -m code_index --search-code "QA_Login deserialize" --project "Middleware" --top-k 3
# File symbol list
python -m code_index --get-file-outline "combat.cpp"
# Retrieve code by chunk ID
python -m code_index --get-chunk "fc617902-35bc-5155-b9d1-b94837fd181d"
```
## Tool List
AI clients can call the following tools.
| Tool | Description | Main Parameters |
|---|---|---|
| `search_code` | Search code chunks by natural language/symbol name | `query`, `top_k`, `language`, `symbol_type`, `project` |
| `get_file_outline` | Return symbol list (classes/functions/methods) of a file | `file_path` |
| `get_chunk` | Retrieve code contents by chunk ID | `chunk_id` |
---
## Data Storage Locations
| File/Directory | Contents |
|---|---|
| `./data/metadata.db` | File/chunk metadata + FTS5 BM25 index (SQLite) |
| `./data/embed_cache.db` | Content hash → embedding vector cache (SQLite) |
| `./data/qdrant/` | HNSW vector index (Qdrant data) |
| `./.cache/qdrant/qdrant.exe` | Auto-downloaded Qdrant executable |
| `./.cache/` | HuggingFace model cache (if `models.cache_dir` is not set) |
| `./log.txt` | MCP request/response log (if `debug: true`) |
To fully initialize the index:
```powershell
python -m code_index --remove
python -m code_index --index-only
```
---
## Architecture
```
Indexing Pipeline
Source Code → File Scanner (change detection) → Tree-sitter Parsing
→ Chunking → Embedding (GPU) → Qdrant + SQLite FTS5
Search Pipeline
Query → Query Embedding
├─ Dense Search (HNSW)
└─ BM25 Search (FTS5)
└─ RRF Score Combination → [Re-ranking (optional)] → Result Return
```
## Project Structure
```
CodeIndex/
├── code_index/
│ ├── __main__.py # Entry point, CLI option handling
│ ├── config.py # Load settings and defaults
│ ├── constants.py # Global constants and settings
│ ├── indexer/
│ │ ├── scanner.py # File scanning and change detection
│ │ ├── parser.py # Tree-sitter AST parsing
│ │ ├── chunker.py # Symbol-level chunking
│ │ ├── embedder.py # Embedding generation
│ │ └── pipeline.py # Indexing pipeline orchestration
│ ├── options/ # CLI option handling modules
│ ├── store/
│ │ ├── vector_store.py # Qdrant HNSW vector store
│ │ ├── metadata_store.py # SQLite metadata + FTS5
│ │ ├── qdrant_server.py # Qdrant binary auto-download and server management
│ │ └── cache.py # Embedding cache
│ ├── retriever/
│ │ ├── hybrid_search.py # Dense + BM25 + RRF
│ │ └── reranker.py # Re-ranking (optional)
│ ├── mcp/
│ │ ├── server.py # FastMCP server (tool definitions)
│ │ └── debug_logger.py # Request/response logger
│ └── models/
│ └── model_manager.py # HuggingFace model path management
├── config/
│ └── settings.json.template # Settings template
├── test/
│ ├── run_test.py # Accuracy test execution
│ ├── code_index.py # CodeIndex child process management
│ ├── utility.py # Test utilities
│ ├── project1/ # C++/C# test sample source code
│ ├── project2_1/ # C++/C# test sample source code
│ ├── project2_2/ # C++/TypeScript test sample source code
│ └── test_suite/ # Automated test suite
└── data/ # Index data (gitignore)
```
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available