Code Index MCP

MCP开发工具

提供方 ViperJuice

开发工具 stdio · 本地进程 无需鉴权 社区 / 第三方 ClaudeCursorVS Code
查看接入方式

Code indexing MCP server to provide context to coding agents.

一句话选型结论

按资料字段整理

Code Index MCP 属于开发工具类 MCP 服务器,stdio · 本地进程,无需鉴权,可直接接入 Claude、Cursor、VS Code,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式stdio · 本地进程 鉴权无需鉴权 部署方式本地部署
GitHub 星标 52 仓库热度,无公开仓库时显示未标注
工具数 4 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量4暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

developer-toolscode-indexerlocal-firstAI-assistant代码索引Python本地部署本地优先

安装与配置

stdio · 本地进程 无需鉴权
客户端在本机拉起子进程,数据不出本机
docker run -it -v $(pwd):/workspace ghcr.io/viperjuice/code-index-mcp:v1.2.0

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Docker,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 4 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 4 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude、Cursor、VS Code,换客户端不用重新研究配置。
  • 资料标注无需鉴权,装好就能连。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 已经在用 Claude、Cursor 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Code Index MCP当前 4 stdio · 本地进程 本地部署 有 2026-05-18
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方ViperJuice上游标注的维护方 ViperJuice
分类开发工具本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式无需鉴权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Docker本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-18上游最后核验时间

详细介绍

52.9 KB
来自项目仓库与上游目录的原文,未做删改

Code-Index-MCP

Give your AI coding assistant instant, precise search across your whole codebase — so it finds the exact code it needs in milliseconds instead of burning time and tokens reading whole files.

Code-Index-MCP is a fast, local-first search index for your code. It plugs into Claude Code and other AI assistants (through the Model Context Protocol, "MCP") and lets them look up any symbol or search any text in your repository almost instantly — without your code ever leaving your machine.

> New to Code-Index-MCP? Start with the Getting Started Guide.
>
> Status: v1.4.1 stable surface prepared — MCP tools (search_code, symbol_lookup) are the primary interface; a FastAPI admin gateway is available for diagnostics.

> Stable-surface prep status: This guide targets the 1.4.1 prepared candidate.
> Published 1.4.0 (2026-07-19) does not include these v13 repairs.
> MCP STDIO is primary; FastAPI is secondary admin only.
> See release preparation and acceptance.
> Publication and fleet rollout remain separate acceptance gates.

Project Status

Version: 1.4.1 (prepared candidate; publication tracked separately)
Python distribution: index-it-mcp
Container image: ghcr.io/consiliency/code-index-mcp
Primary surface: MCP tools (search_code, symbol_lookup) via the STDIO runner when repository readiness is ready
Secondary surface: FastAPI admin REST gateway for diagnostics and scripting — see "Admin REST Interface (secondary)" below
Core features: local indexing, symbol/text search, registry-based language coverage; see docs/SUPPORT_MATRIX.md
Optional features: semantic search (requires Voyage AI or a local vLLM endpoint), GitHub Artifacts index sync
Performance: sub-100ms symbol lookup and sub-500ms search on indexed repos (benchmarked on this codebase; results vary by repo size and language mix)
GA decision: see docs/validation/ga-final-decision.md; the current product decision is ship GA, while install-surface claims remain bounded by docs/status/public-package-identity.md.
GA readiness contract: see docs/validation/ga-readiness-checklist.md for the frozen release boundary, support-tier labels, evidence ownership, and rollback expectations that apply before dispatch.
Release dispatch: the historical governance record names this boundary GADISP; the current workflow implements it as a separate publish mode restricted to protected main.
Repository model: one server can serve many unrelated repositories, with one registered worktree per git common directory. Only the tracked/default branch is indexed automatically. Indexed MCP results are authoritative only when readiness is ready; unavailable indexes return index_unavailable with safe_fallback: "native_search".

MCP_CLIENT_SECRET is a local STDIO handshake guard for mcp-index stdio.
The FastAPI gateway uses separate admin/debug bearer token authentication, and
no remote MCP authorization is implemented while remote MCP transport remains
deferred.

Why it exists

When an AI assistant works in a large codebase, it often reads big chunks of files just to find what it needs. That's slow, and every file it reads costs tokens (money). Code-Index-MCP builds a local index so the assistant can jump straight to the right function, class, or line — cutting token cost and making answers faster and more accurate.

Who it's for

Developers and teams using AI coding assistants on real, sizable codebases who want faster, cheaper, more accurate results — and who want their code to stay private, on their own machine.

What you get

  • ⚡ Instant lookups — sub-100ms symbol lookup, sub-500ms search on indexed repos.
  • 🔒 Local-first & private — indexing runs on your machine; your code isn't shipped to a cloud.
  • 💸 Lower token cost — the assistant searches instead of reading whole files (see the charts below).
  • 🧠 Semantic search (optional) — natural-language code search via embeddings.
  • 🌐 Many languages, many repos — one server can index multiple repositories with mixed languages.
  • 🔌 Plugin-based & extensible — add language support without touching the core.

See it in action

Benchmarks in this repository show large token/cost reductions when an assistant searches with Code-Index-MCP instead of reading files directly:

(Charts generated from the benchmarks in reports/; numbers vary by repo size and language mix.)

🎯 Key Features

  • 🚀 Local-First Architecture: All indexing happens locally for speed and privacy
  • 📂 Local Index Storage: All indexes stored at .indexes/ (relative to MCP server)
  • 🔌 Plugin-Based Design: Easily extensible with language-specific plugins
  • 🔍 Language support: Tiered language/runtime support is documented in docs/SUPPORT_MATRIX.md
  • ⚡ Real-Time Updates: File system monitoring for instant index updates
  • 🧠 Semantic Search: AI-powered code search with Voyage AI embeddings
  • 📊 Rich Code Intelligence: Symbol resolution, type inference, dependency tracking
  • 🚀 Enhanced Performance: Sub-100ms queries with timeout protection and BM25 bypass
  • 🔄 Git Synchronization: Automatic index updates tracking repository changes
  • 📦 Portable Index Management: Zero-cost index sharing via GitHub Artifacts
  • 🔄 Automatic Index Sync: Pull indexes on clone, push on changes
  • 🎯 Smart Result Reranking: Multi-strategy reranking for improved relevance
  • 🎯 Query-Intent Routing: Symbol-pattern queries (class Foo, def bar, CamelCase) bypass BM25 and hit the symbols table directly for sub-5ms lookups
  • 🔒 Security-Aware Export: Automatic filtering of sensitive files from shared indexes
  • 🔍 Hybrid Search: BM25 + semantic search with configurable fusion
  • 🔐 Filtered Local Indexes: Default secret-file exclusions apply to lexical and semantic indexing
  • 🚫 Ignore Rules: .gitignore and .mcp-index-ignore filter indexing and export; patterns are not a secret scanner

🏗️ Architecture

The Code-Index-MCP follows a modular, plugin-based architecture designed for extensibility and performance:

System Layers

  1. 🌐 System Context (Level 1)
    - Developer interacts with Claude Code or other LLMs
    - MCP protocol provides standardized tool interface
    - Local-first processing with optional cloud features
    - Performance SLAs: <100ms symbol lookup, <500ms search

  2. 📦 Container Architecture (Level 2)┌─────────────────┐ ┌──────────────┐ ┌─────────────┐ │ API Gateway │────▶│ Dispatcher │────▶│ Plugins │ │ (FastAPI) │ │ │ │ (Language) │ └─────────────────┘ └──────────────┘ └─────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌──────────────┐ ┌─────────────┐ │ Local Index │ │ File Watcher │ │ Embedding │ │ (SQLite+FTS5) │ │ (Watchdog) │ │ Service │ └─────────────────┘ └──────────────┘ └─────────────┘

  3. 🔧 Component Details (Level 3)
    - Gateway Controller: RESTful API endpoints
    - Dispatcher Core: Plugin routing and lifecycle
    - Plugin Base: Standard interface for all plugins
    - Language Plugins: Specialized parsers and analyzers
    - Index Manager: SQLite with FTS5 for fast searches
    - Watcher Service: Real-time file monitoring

🔐 Security

Code-Index-MCP implements defense-in-depth security hardening (Phase 15):

  • Plugin Sandboxing: Plugins execute in isolated worker processes with capability-based restrictions. See docs/security/sandbox.md.
  • Artifact Attestation: Enforced publication requires GitHub-signed custom metadata digest attestations, verified at download. These are not SLSA build provenance. See docs/security/attestation.md.
  • Path Traversal Guard: Search results are validated to prevent escaping configured repository roots. See docs/security/path-guard.md.
  • Token Validation: GitHub tokens are validated for required scopes at startup (contents:read, metadata:read, actions:read, actions:write, attestations:write). See docs/security/token-scopes.md.
  • Metrics Authentication: The /metrics endpoint requires bearer token authentication.

MCP_CLIENT_SECRET is a local STDIO handshake guard only. It is not the
gateway's admin/debug bearer token authentication, and no remote MCP
authorization is implemented while the repository continues to defer remote
MCP transport.

For a comprehensive operator runbook, see docs/operations/user-action-runbook.md.

📁 Project Structure

The project follows a clean, organized structure. See docs/PROJECT_STRUCTURE.md for detailed layout.

Key directories:
- mcp_server/ - Core MCP server implementation
- scripts/ - Development and utility scripts
- tests/ - Comprehensive test suite with fixtures
- docs/ - Documentation and guides
- architecture/ - System design and diagrams
- docker/ - Docker configurations and compose files
- mcp-index-kit/ - Shared MCP indexing toolkit and examples
- docs/status/ - Durable evidence notes kept under version control

🛠️ Language Support

The current stable-surface support contract is centralized in docs/SUPPORT_MATRIX.md.
It distinguishes specialized plugins, generic Tree-sitter registry coverage,
default sandbox support, optional extras, semantic/rerank setup, and known
alpha limitations. Do not assume every registry language has the same symbol
quality or default sandbox behavior.

🚀 Quick Start

Supported install paths are the digest-pinned container image published with
the v1.4.1 GitHub release, native Python/STDIO with uv sync --locked, and a
locally built index-it-mcp wheel. Use the registry image only after protected-main publication and delivered
artifact acceptance; until then use the candidate source or local wheel. The
ghcr.io/consiliency/code-index-mcp:local-smoke image remains an optional dev
path built from this checkout with make release-smoke-container.
Language coverage is bounded by docs/SUPPORT_MATRIX.md,
GA-hardening evidence ownership is frozen in
docs/validation/ga-readiness-checklist.md,
and rollback procedures live in
docs/operations/deployment-runbook.md.
Do not treat this prepared surface as a universal language support
claim; row-level support tiers still live in the support matrix.

🎯 Automatic Setup for Claude Code/Desktop (Recommended)```bash

Auto-configures MCP for your environment

./scripts/setup-mcp-json.sh

Or interactive mode

./scripts/setup-mcp-json.sh --interactive


This automatically detects your environment and creates the appropriate `.mcp.json` configuration.

### 🐳 Docker Setup

The installer targets `v1.4.1` and resolves its `image-reference.txt` release
asset to a signed GHCR digest. Version and `latest` image tags are not updated;
the installer&#x27;s `latest` option selects the latest GitHub release, then pins
that release&#x27;s digest. A missing release asset is an error, never a tag fallback.
Before that gate, the `local-smoke` tag is an optional dev image you can
build from this checkout with `make release-smoke-container`.

#### Option 1: Basic Search (No API Keys) - 2 Minutes```bash
# After release acceptance, start STDIO with the published image reference
export MCP_IMAGE_REF=$(curl -fsSL https://github.com/Consiliency/Code-Index-MCP/releases/download/v1.4.1/image-reference.txt)
[[ &quot;$MCP_IMAGE_REF&quot; =~ ^ghcr\.io/consiliency/code-index-mcp@sha256:[0-9a-f]{64}$ ]] || exit 1
docker run -i --rm -v &quot;$(pwd):/workspace&quot; &quot;$MCP_IMAGE_REF&quot; index-it-mcp stdio

Option 2: AI-Powered Search```bash

Set your API key (get one at https://www.voyageai.com — free tier available)

export VOYAGE_API_KEY=your-key

Run with semantic search enabled explicitly

docker run -i --rm -v "$(pwd):/workspace" -e SEMANTIC_SEARCH_ENABLED=true -e VOYAGE_API_KEY "$MCP_IMAGE_REF" index-it-mcp stdio


### 💻 Environment-Specific Setup

#### 🪟 Windows (Native)```powershell
# PowerShell
.\scripts\setup-mcp-json.ps1

# Or use the digest-pinning Docker installer after publication
.\scripts\install-mcp-docker.ps1

🍎 macOS```bash

Install Docker Desktop or use Homebrew

brew install --cask docker

Run setup

./scripts/setup-mcp-json.sh


#### 🐧 Linux```bash
# Install Docker (no Desktop needed)
curl -fsSL https://get.docker.com | sh

# Run setup
./scripts/setup-mcp-json.sh

🔄 WSL2 (Windows Subsystem for Linux)```bash

With Docker Desktop integration

./scripts/setup-mcp-json.sh # Auto-detects WSL+Docker

Without Docker Desktop

cp .mcp.json.templates/native.json .mcp.json
uv sync --locked


#### 📦 Nested Containers (Dev Containers)```bash
# For VS Code/Cursor dev containers
# Option 1: Use native Python (already in container)
cp .mcp.json.templates/native.json .mcp.json

# Option 2: Use Docker sidecar (avoids dependency conflicts)
docker-compose -f docker/compose/development/docker-compose.mcp-sidecar.yml up -d
cp .mcp.json.templates/docker-sidecar.json .mcp.json

Windows Path-Length Fallback

Tracked repository paths are kept at or below the 160-character tracked-path
limit, and the REPOCLEAN audit also checks wheel-content path depth for
installed site-packages members. If a Windows checkout still hits a
path-length edge because of a deeply nested clone location or third-party
tooling, use git config --global core.longpaths true as a fallback rather
than as the primary mitigation.

📋 MCP.json Configuration Examples

The setup script creates the appropriate .mcp.json for your environment. Manual examples:

Native Python (Dev Container/Local)```json

{
"mcpServers": {
"code-index-native": {
"command": "python",
"args": ["-m", "mcp_server.cli.stdio_runner"],
"cwd": "${workspace}"
}
}
}


#### Docker (Windows/Mac/Linux)
Replace the digest placeholder with the full `image-reference.txt` release asset,
or use the installer&#x27;s generated configuration, which already pins that value.```json
{
  &quot;mcpServers&quot;: {
    &quot;code-index-docker&quot;: {
      &quot;command&quot;: &quot;docker&quot;,
      &quot;args&quot;: [
        &quot;run&quot;, &quot;-i&quot;, &quot;--rm&quot;,
        &quot;-v&quot;, &quot;${workspace}:/workspace&quot;,
        &quot;ghcr.io/consiliency/code-index-mcp@sha256:&lt;published-digest&gt;&quot;,
        &quot;index-it-mcp&quot;, &quot;stdio&quot;
      ]
    }
  }
}

Release Smoke```bash

make release-smoke
make release-smoke-container


## Using Against Many Repos

Index many unrelated repositories from a single running server instance.

**Prerequisites**: set `MCP_ALLOWED_ROOTS` to an OS-path-separator-separated list of absolute directory paths (`:` on Unix, `;` on Windows) that the server is allowed to index before starting the server:```bash
export MCP_ALLOWED_ROOTS=/abs/a:/abs/b

Start the server (with secrets via op run or plain mcp-index stdio):```bash
op run --env-file=.mcp.env -- mcp-index stdio


**Register each repo** — register one worktree per git common directory. The
stable `repo_id` comes from Tier 1 `git rev-parse --git-common-dir`, so sibling
worktrees of the same repository share identity and are not independently
indexed in v3:```bash
mcp-index repository register /abs/a
mcp-index repository register /abs/b

Scope queries per repo — pass repository= (registered name or path) to search_code / symbol_lookup:```
search_code(query="def parse", repository="my-repo")
symbol_lookup(symbol="Parser", repository="my-repo")


**Python client (beta local API)**: for local scripts and applications on the
same machine as the registered repo, use `mcp_server.client` instead of
starting STDIO or calling FastAPI. MCP tools remain the preferred LLM surface.```python
from mcp_server.client import open_client
from mcp_server.client_types import ClientSearchOptions

with open_client(workspace_root=&quot;/path/to/repo&quot;) as client:
    result = client.search_code(
        ClientSearchOptions(
            query=&quot;TODO&quot;,
            source_type=&quot;friction&quot;,
            friction_categories=(&quot;todo&quot;,),
            include_source_metadata=True,
        )
    )
    if result.index_unavailable:
        print(result.index_unavailable.safe_fallback)
    else:
        print(result.results[0].file)

The supported Python client surface is local-only: search_code,
symbol_lookup, reindex, and get_status share the same readiness-aware
service as the MCP search_code tool. It is a local programmatic API, not a
remote service client.

Friction pattern metadata is available as an additive filter on search_code.
Use source_type=&quot;friction&quot; with optional friction_categories=[&quot;todo&quot;, &quot;fixme&quot;, &quot;hack&quot;, &quot;workaround&quot;, &quot;wish&quot;, &quot;extraction_hint&quot;]. Set
include_source_metadata=true to attach the stored
search_source_metadata.v1 envelope to returned results. Ordinary unfiltered
lexical calls keep the legacy result shape; invalid friction categories return
a metadata-only validation error instead of a silent empty result.

Historical GitHub issue context uses the same metadata envelope and search
surface. Run mcp-index history ingest --repo owner/repo to ingest
metadata-only issue documents, then filter them with source_type=&quot;history&quot;
plus optional history_labels=[&quot;reflection&quot;] or
history_repos=[&quot;owner/repo&quot;]. The HISTORY contract is fixture-backed in
tests, requires no live GitHub credentials, and does not persist raw issue
bodies by default.

Index tracking: each repo's tracked/default branch is followed by
MultiRepositoryWatcher (RefPoller every 30 s). Same-repo multiple worktrees
and non-default branch queries are unsupported in v3 routing: they return
index_unavailable with safe_fallback: &quot;native_search&quot; and readiness
remediation instead of reusing another checkout's index. Check get_status or
mcp-index repository list -v and trust indexed MCP results only when readiness
is ready.

Path sandbox: tools search_code, symbol_lookup, summarize_sample, and reindex reject paths outside MCP_ALLOWED_ROOTS with error code path_outside_allowed_roots. Registered repo names bypass the check.

Options:
- Set MCP_AUTO_INDEX=false in the server environment to skip background auto-indexing and call the reindex MCP tool manually (recommended for very large repos).
- Add {&quot;enabled&quot;: false} to .mcp-index.json in the target repo to disable indexing for that repo entirely.
- After a full reindex or code changes, call the reindex MCP tool to rebuild the index on demand.

Semantic profiles: BM25 search requires no extra config. For semantic (vector) search, the server automatically loads code-index-mcp.profiles.yaml from its own installation directory — no need to copy it to each repo. To override with a custom profile file, set MCP_PROFILES_PATH=/abs/path/to/your-profiles.yaml in the server environment. To override individual endpoint URLs without editing the YAML, use the env vars referenced in the file (e.g. VLLM_EMBEDDING_BASE_URL, VLLM_SUMMARIZATION_BASE_URL).

⚡ Enable Semantic Search

BM25 keyword search works with zero configuration. To add vector (semantic) search, choose one path:

Option A — Voyage AI (recommended):```bash
export VOYAGE_API_KEY=your-key # free tier available at voyageai.com

The `commercial_high` profile activates automatically. Restart the MCP server — the startup log will confirm semantic search is active.

**Option B — Local OSS (Qwen3-Embedding-8B via vLLM, no API key needed):**```bash
export VLLM_EMBEDDING_BASE_URL=http://localhost:8000/v1
# Start vLLM (requires ~20GB VRAM or shared CPU with --dtype float32):
docker run -p 8000:8000 vllm/vllm-openai --model Qwen/Qwen3-Embedding-8B

Both profiles and their collection names are defined in code-index-mcp.profiles.yaml and can be customized.

code-index-mcp.profiles.yaml is a repo-shipped profile filename, not a pip
install target.

Costs & Optional Features

The documented container package is ghcr.io/consiliency/code-index-mcp.
BM25 code search works without provider credentials. Semantic search, reranking,
artifact sync, and monitoring depend on extras, environment variables, and
service configuration. See docs/SUPPORT_MATRIX.md
for language/runtime support details.

🚀 Quickstart (Python)

Prerequisites

  • Python 3.12+
  • Git

Installation

Option 1: Use the repo-owned source install (Recommended)```bash

Clone the repository

git clone https://github.com/ViperJuice/Code-Index-MCP.git
cd Code-Index-MCP

Install locked project dependencies

uv sync --locked

Verify the canonical CLI entrypoint

uv run mcp-index --version


#### Option 2: Build the local wheel```bash
# From the repo root
uv run --extra dev python -m build --wheel
python -m pip install dist/index_it_mcp-1.4.1-py3-none-any.whl
index-it-mcp --version

The canonical Python distribution remains index-it-mcp. The commands above
install this prepared candidate, not the older published release. Use
pip install index-it-mcp==1.4.1 only after the protected-main publication and
independent delivered-package checks recorded in the release receipt.

Quick Start After Installation```bash

Authenticate GitHub artifact access once

gh auth login

Check repo/artifact readiness before starting work

mcp-index preflight

Pull the latest published index baseline for this repo

mcp-index artifact pull --latest

Reconcile only your local drift after restore

mcp-index artifact sync

The restored files live locally for MCP runtime use:

- code_index.db

- .index_metadata.json

- vector_index.qdrant/

Check index status

mcp-index index status

Start the MCP STDIO runner (primary surface used by LLMs via .mcp.json)

mcp-index stdio

Or start the FastAPI admin REST gateway (secondary, for diagnostics only;

this is not the repo's MCP Streamable HTTP transport)

mcp-index serve
mcp-index serve --port 9123 # alternate port


From an LLM (Claude Code, Cursor, …) register the STDIO runner in
`.mcp.json` and invoke the indexer as MCP tool calls. The two primary tools
are `search_code` (pattern / keyword / semantic search, &lt;500 ms) and
`symbol_lookup` (exact class/function lookup, &lt;100 ms). Call `get_status` to
confirm repository readiness is `ready`, or handle a query response with
`code: &quot;index_unavailable&quot;` and `safe_fallback: &quot;native_search&quot;` by using native
search while following the returned remediation, such as `reindex`:```json
{
  &quot;tool&quot;: &quot;search_code&quot;,
  &quot;arguments&quot;: {
    &quot;query&quot;: &quot;def parse&quot;,
    &quot;limit&quot;: 20,
    &quot;semantic&quot;: false
  }
}
``````json
{
  &quot;tool&quot;: &quot;symbol_lookup&quot;,
  &quot;arguments&quot;: {
    &quot;symbol&quot;: &quot;parse_file&quot;
  }
}

Both tools accept an optional &quot;repository&quot; argument (registered repo name or
an absolute path inside MCP_ALLOWED_ROOTS) for multi-repo scoping. See the
"Using Against Many Repos" section above. A ready index with no matches returns
ordinary no-match payloads (results: [] for search_code or
result: &quot;not_found&quot; for symbol_lookup) with readiness metadata; unavailable
indexes return index_unavailable instead.

The STDIO tools/list surface is deterministic and now advertises richer MCP
metadata for every public tool: stable title values, explicit JSON Schema
input contracts (required, defaults, and additionalProperties posture),
annotations for read-only versus mutating behavior, and implementation-owned
outputSchema drafts. The STDIO tools/call surface now returns SDK-native
CallToolResult objects with object-shaped structuredContent, preserved JSON
text fallback content in content for older clients, and isError on refusal
and error branches. Legacy array-like payloads such as plain lexical search
hits are wrapped under structuredContent.results, while readiness failures
still carry index_unavailable with safe_fallback: &quot;native_search&quot; where
that contract already applied.

reindex and write_summaries also support task-augmented execution through
the SDK-native MCP tasks surface. Both tools advertise
execution.taskSupport = &quot;optional&quot;, so clients can either keep the current
synchronous path or include a task object in tools/call and then use
tasks/get, tasks/list, tasks/result, and tasks/cancel for progress,
terminal payload retrieval, and best-effort cancellation. Readiness refusals,
path sandbox failures, conflicting scope errors, and
summarizer-unavailable preflights still fail synchronously before any task is created.
Whole-repository generation rebuilds, including readiness recovery, require the
synchronous path. A task request for that scope returns task_scope_unsupported
without mutation; it never silently runs a long synchronous rebuild instead.

Current verified MCP client posture is summarized in the
MCP compatibility matrix. The
phase-owned direct smoke is the official Python SDK over STDIO; Claude Code and
other STDIO launchers are documented against that same server contract, while
remote Streamable HTTP MCP remains deferred.

🔧 Configuration

Create a .env file for configuration:```env

Semantic profile setup — set VOYAGE_API_KEY (free tier at voyageai.com) to enable vector search

VOYAGE_API_KEY=your_api_key_here

Use 127.0.0.1 for local inference, or a Tailscale/SSH tunnel IP for remote GPUs

OPENAI_API_BASE=http://127.0.0.1:8001/v1
QDRANT_PATH=vector_index.qdrant

Server-mode Qdrant: QDRANT_URL, plus QDRANT_API_KEY when the server sets

QDRANT__SERVICE__API_KEY (leave unset for an unauthenticated server)

QDRANT_URL=http://localhost:6333

QDRANT_API_KEY=your_qdrant_api_key

Server settings

MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8000
MCP_LOG_LEVEL=INFO

Workspace settings

MCP_WORKSPACE_ROOT=.
MCP_MAX_FILE_SIZE=10485760 # 10MB

GitHub Artifact Sync (privacy settings)

MCP_ARTIFACT_SYNC=false # Set to true to enable
AUTO_UPLOAD=false # Auto-upload on changes
AUTO_DOWNLOAD=true # Auto-download on clone


Published artifacts now carry the full lexical baseline plus two semantic
profiles:

- `commercial_high` using `voyage-code-3`
- `oss_high` using `Qwen/Qwen3-Embedding-8B`

Those profiles are stored in separate Qdrant collections inside the artifact so
consumers can pull one baseline and use either profile locally.

**Pro Tip: Remote Inference for the Open-Source Profile**
If your local machine lacks the GPU power to run the `oss_high` embedding model locally (e.g., via vLLM or Ollama), you can run inference on a remote machine and point the MCP server to it:
- **Tailscale/VPN:** Set `OPENAI_API_BASE=http://:8001/v1`
- **SSH Tunnel:** Run `ssh -L 8001:localhost:8001 user@remote-gpu-machine`, and the default `127.0.0.1:8001` configuration will tunnel directly to your inference server.

The generated index files are not meant to live in git history. The repo tracks
the code, workflow, and configuration needed to build/publish them; GitHub
artifacts distribute the actual runtime baseline that MCP restores locally.

### Local Workspace Management```bash
# Inspect all registered repositories and their readiness
mcp-index repository list -v

# Check all registered repos and their local artifact/runtime readiness
mcp-index artifact workspace-status

# Refresh readiness after restoring or rebuilding local indexes
mcp-index artifact reconcile-workspace

# Prepare per-repo local artifact payloads without requiring remote publication
mcp-index artifact publish-workspace

MRREADY freezes the rollout-facing interpretation of those commands:

  • mcp-index repository list -v, mcp-index repository status, and
    mcp-index artifact workspace-status now surface one rollout status per
    repository: ready, local_only, publish_failed, wrong_branch,
    stale_commit, missing_index, or partial_index_failure.
  • Query tools remain a separate fail-closed surface. If readiness is not
    ready, MCP search returns index_unavailable with
    safe_fallback: &quot;native_search&quot; instead of treating a status row as a query
    success.
  • The current multi-repo verdict remains controlled rollout only while the
    multi-repo and STDIO surfaces are still beta.

🔐 Privacy & GitHub Artifact Sync

Control how your code index is shared:```json
// .mcp-index.json
{
"github_artifacts": {
"enabled": false, // Disable sync entirely
"auto_upload": false, // Manual upload only
"auto_download": true, // Still get team indexes
"exclude_patterns": [ // Additional exclusions
"internal/",
"proprietary/
"
]
}
}


**Privacy Features:**
- Indexes filtered by .gitignore automatically
- Additional patterns via .mcp-index-ignore
- Audit logs show what was excluded
- Sync disabled by default in Docker minimal version

## 🆕 Advanced Features

### Search Result Reranking

Three rerankers are available, configured via the `RERANKER_TYPE` environment variable:

| Value | Reranker | Notes |
|---|---|---|
| `flashrank` | FlashRank | OSS, local, fast (~1–5 ms overhead) |
| `cross-encoder` | Cross-Encoder | OSS, local, highest quality |
| `voyage` | Voyage Reranker | Cloud API, requires `VOYAGE_API_KEY` |
| `none` | Disabled | Default |
```bash
export RERANKER_TYPE=flashrank   # or cross-encoder, voyage, none

Reranking applies only to the semantic retrieval path. BM25/FTS results are not reranked.
Implementation: mcp_server/dispatcher/reranker.py.

LLM Chunk Summarization

Semantic chunks can be augmented with LLM-generated summaries before embedding, improving
retrieval of intent-based queries. Configured per-profile in code-index-mcp.profiles.yaml:yaml summarization: enabled: true mode: lazy # lazy (on first query) | comprehensive (at index time) provider: openai_compatible model_name: gpt-4o-mini base_url: &quot;https://api.openai.com/v1&quot; api_key_env: OPENAI_API_KEY prompt_template: &quot;Describe this code chunk&#x27;s inputs, outputs, and purpose in 2 concise sentences.&quot;

…(正文过长,页面只展示前面部分,完整内容见仓库)

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Code Index MCP 怎么安装?

在客户端按下面的安装命令接入:docker run -it -v $(pwd):/workspace ghcr.io/viperjuice/code-index-mcp:v1.2.0。装完在客户端配置里引用同一个包或端点。

Code Index MCP 怎么在 Claude、Cursor、VS Code 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Code Index MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Code Index MCP 需要 API Key 吗?

资料标注为无需认证,装好就能连;如果实际调用时报鉴权错误,按官方文档补上凭据。

Code Index MCP 支持哪些客户端?

资料标注支持 Claude、Cursor、VS Code;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Code Index MCP 能提供哪些能力?

资料显示约 4 个工具;能力标签包括 代码索引、本地优先、Python、Claude、模块化设计。具体工具清单以官方文档为准。

Code Index MCP 需要什么运行环境?

运行时为 Docker;属于本地进程,需要在本机装好运行环境。

Code Index MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-18。