MSCodebase Intelligence

AI-powered semantic code search for Zed IDE — MCP-сервер глубинного анализа кода

Features • Quick Start • Tools • Documentation • Installation • Architecture • Contributing • Security

Last updated: 2026-07-09

🎯 Positioning

MSCodeBase Intelligence is an MCP server for Zed IDE that gives AI assistants deep understanding of the entire codebase: semantic search, call graph, project memory, diagnostics.

This is not an LSP server or a replacement for the editor's built-in autocomplete. It's a "code intelligence" layer on top of the editor:

┌─────────────────────────────────────────────────────┐
│                      Zed IDE                         │
│  ┌───────────────────────────────────────────────┐  │
│  │        LSP (built-in autocomplete,           │  │
│  │        inline hints, diagnostics)            │  │
│  └───────────────────────────────────────────────┘  │
│                        │                              │
│                        ▼                              │
│  ┌───────────────────────────────────────────────┐  │
│  │  MSCodeBase (MCP server)                     │  │
│  │  · Semantic search across the codebase       │  │
│  │  · Call graph & impact analysis              │  │
│  │  · Project memory (ADR, tech debt)           │  │
│  │  · Self-diagnostics and self-healing         │  │
│  │  · 50 tools for AI assistant                 │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

What you get

Feature	MSCodeBase	Standard LSP (pyright/pylsp)
🔍 Semantic search (BM25 + Vector + Reranker)	✅	❌
🧠 Call graph + impact analysis	✅	❌
🗃️ Project memory (ADR, known issues)	✅	❌
🏥 Self-diagnosis + self-healing	✅	❌
🔎 Cross-repo search	✅	❌
🤖 RAG answer generation (mode=ask)	✅	❌
✏️ Inline autocomplete	❌	✅
🏷️ Inlay hints	❌	✅

Why not LSP

MSCodeBase does not use LSP. The LSP server (src/lsp_main.py) was an experimental part of the project and does not work in Zed due to architectural limitations of the editor itself (see LSP_WONTFIX.md).

Instead, all functionality is implemented through 50 MCP tools available in Zed via the MCP protocol.

Platforms

Designed and tested on Windows. macOS and Linux should work but have not been validated officially.

✨ Features

Feature	Description
🔍 Unified Search	`search_code(query, mode, intent_hint)` — single tool: fast/quality/deep/context/ask/auto
🧠 Intelligence Layer	10 high-level `intel_*` tools: self-diagnostics, topology, error prediction
🗃️ Project Memory	ADR, known issues, tech debt — automatically persisted between sessions
🌐 Cross-repo Search	Search across multiple projects with `@mention` syntax
🌳 Call Graph	Full call graph: definition + callers + callees + impact analysis
🏗 Structural Search	13 AST patterns (class_inheritance, async_function, decorator, etc.)
🔎 Context Search	Find similar code — paste a fragment, get semantic duplicates
🪣 Multi-Bucket RAG	Code/docs buckets, soft weighting, intent_hint (code/docs/auto)
🤖 mode=ask	RAG-генерация ответа через phi-4 (server profile)
💾 LanceDB v2	Vector DB with per-project isolation (incremental BM25 reindex)
🛡 Rate Limiting	DebounceBatch + CircuitBreaker — protection against VFS loops
🏥 Self-Diagnosis	`get_health_report` + `index_health` — full check and recovery
│ 🧪 Clean Architecture	DI Container (15 services), 50 tools (34 class-based + 14 intel + 2 diag), 391+ tests
🪟 Multi-Window	`ProjectIndexerRegistry` — isolated Indexer per project, LRU 5, ResourceMonitor throttle
⚙️ SYSTEM_PROFILE	`light` (sync) / `server` (async with phi-4)

🚀 Quick Start

Выбери один из трёх способов установки:

Способ	Кому подходит	Время	Сложность
🤖 One-Prompt	Всем. Копируешь текст → Агент Zed всё делает сам	5-10 мин	🟢 Автоматически
🖥️ Install.py	Кто любит TUI-установщики	5-10 мин	🟢 Просто
🛠️ Вручную	Кто хочет полный контроль	15-20 мин	🟡 Средне

Примечание: На Windows 11 Insider Preview (build ≥ 26220) llama-server.exe несовместим (отсутствует api-ms-win-crt-heap API Set). Установщик автоматически переключится на ONNX. На стабильных Windows/macOS/Linux — llama.cpp (в 3x быстрее и в 2x легче).

🤖 Способ 1: One-Prompt (рекомендуется)

Для кого: Для всех. Агент Zed сам определит твою платформу, CPU, скачает нужные бинарники и настроит MCP.

Что делать:

Открой Agent Panel в Zed: Ctrl+Shift+P → Agent Panel: Toggle
Скопируй весь текст из AI_INSTALLATION_PROMPT.md
Вставь в чат Агента и нажми Enter
✅ Готово через 5-10 минут

Что произойдёт:
  ├─ Диагностика: Windows/macOS/Linux, AVX2/AVX512/ARM
  ├─ Клонирование репозитория
  ├─ Виртуальное окружение + pip install
  ├─ Скачивание llama-server.exe (под твою архитектуру CPU)
  ├─ Скачивание GGUF моделей bge-m3 + reranker (Q4_K_M)
  ├─ Настройка MCP в Zed (с сохранением // комментариев!)
  └─ Если нет интернета / Windows Insider / ошибка → ONNX fallback
  └─ Авто-детекция: стабильный Windows → llama.cpp, Insider → ONNX
  └─ ~750 MB с llama.cpp / ~1.9 GB с ONNX

🖥️ Способ 2: Install.py (TUI-установщик)

Для кого: Кто предпочитает классические установщики.

git clone https://github.com/ManSio/mscodebase-intelligence.git
cd mscodebase-intelligence
python install.py

Что делает:

✅ Создаёт виртуальное окружение + pip install
✅ Скачивает llama.cpp + GGUF модели (bge-m3 + reranker)
✅ Или скачивает ONNX модели (bge-m3 + reranker) — fallback
✅ Настраивает MCP-сервер в Zed
✅ Создаёт деинсталлятор

После установки → File → Quit → reopen project → жди индексацию.

Verify: в Agent Panel выполни:

get_index_status()

🛠️ Способ 3: Вручную (полный контроль)

Для кого: Кто хочет понять каждый шаг или у кого нестандартная конфигурация.

Клонируй:

git clone https://github.com/ManSio/mscodebase-intelligence.git
cd mscodebase-intelligence

Создай venv и установи зависимости:

python -m venv .venv
# Windows:
.venv\Scripts\python.exe -m pip install -r requirements.txt
# macOS/Linux:
.venv/bin/python -m pip install -r requirements.txt

Скачай llama.cpp (опционально, но сильно быстрее):

# Windows — скачай с GitHub:
curl -LO https://github.com/ggml-org/llama.cpp/releases/download/b9940/llama-b9940-bin-win-cpu-x64.zip
# Распакуй в папку llama/

# macOS ARM:
curl -LO https://github.com/ggml-org/llama.cpp/releases/download/b9940/llama-b9940-bin-macos-arm64.tar.gz

# Linux:
curl -LO https://github.com/ggml-org/llama.cpp/releases/download/b9940/llama-b9940-bin-ubuntu-x64.tar.gz

Скачай GGUF модели:

pip install huggingface_hub
python -c "
from huggingface_hub import hf_hub_download
import shutil
for repo, file in [
    ('lm-kit/bge-m3-gguf', 'bge-m3-Q4_K_M.gguf'),
    ('lm-kit/bge-m3-reranker-v2-gguf', 'Bge-M3-568M-Q4_K_M.gguf'),
]:
    path = hf_hub_download(repo_id=repo, filename=file)
    shutil.copy2(path, f'models/{file}')
"

Настрой MCP в Zed: Добавь в %APPDATA%/Zed/settings.json (Windows) или ~/.config/zed/settings.json (macOS/Linux):

{
  "context_servers": {
    "mscodebase-intelligence": {
      "command": ".venv/Scripts/python.exe",
      "args": ["-u", "-m", "src.main"],
      "env": {
        "PYTHONPATH": ".",
        "PROJECT_PATH": "$ZED_WORKTREE_ROOT"
      }
    }
  },
  "context_servers_to_query": ["mscodebase-intelligence"]
}

Запусти и проверь:

.venv/Scripts/python.exe -u -m src.main &
# В Agent Panel: get_index_status()

⚡ Провайдеры (автовыбор)

После установки MCP сам выберет лучший доступный провайдер:

LM Studio (GPU)  →  llama.cpp (CPU GGUF)  →  ONNX server (CPU)  →  local ONNX (fallback)
   fastest             ~523 MB RAM               ~1.7 GB RAM           медленно
   ~100ms embed        ~764ms embed              ~988ms embed          +544 MB в MCP

Подробные бенчмарки: docs/research/2026-07-09-provider-benchmark.md

📌 Важные заметки

Сценарий	Инструкция
Windows	Read docs/en/ZED_WINDOWS_QUIRKS.md
Установка через Агента	Copy AI_INSTALLATION_PROMPT.md into chat
LM Studio	Install, run on port 1234 — MCP connects automatically
llama.cpp	Auto-downloaded by install.py. CPU detected automatically
Уже установлено	`python install.py` безопасен — no-op если всё уже настроено

📚 Documentation Map

Document	Description	Audience	Languages
docs/en/INSTALL.md	Installation, setup, uninstall	Users	🇬🇧 🇷🇺 🇨🇳
docs/en/ARCHITECTURE.md	Clean Architecture, Layers, DI	Developers	🇬🇧 🇷🇺 🇨🇳
docs/en/ARCHITECTURE_DEEP.md	Deep architecture: pipeline, lifecycle, comparison	Architects	🇬🇧 🇷🇺 🇨🇳
docs/en/SEARCH_PIPELINE.md	Search pipeline: BM25 → RRF → Reranker	Developers	🇬🇧
docs/en/GRACEFUL_DEGRADATION.md	4 levels of graceful degradation	DevOps	🇬🇧
docs/en/ARCHITECTURE_LAYERS.md	10 runtime layers	Architects	🇬🇧 🇷🇺 🇨🇳
docs/en/FAQ.md	Frequently Asked Questions	All	🇬🇧 🇷🇺 🇨🇳
docs/en/TELEMETRY.md	Metrics, ETA, data collection	DevOps	🇬🇧 🇷🇺 🇨🇳
docs/en/investigations/ONNX_SESSION_REPORT.md	Full ONNX migration, 7 fixes, benchmarks	Support	🇬🇧
docs/en/investigations/LSP_WONTFIX.md	LSP on Windows investigation (WONTFIX)	Support	🇬🇧 🇨🇳
docs/en/ZED_WINDOWS_QUIRKS.md	Windows specifics, Restricted Mode	Windows users	🇬🇧 🇷🇺 🇨🇳
docs/en/CHANGELOG.md	Version history	All	🇬🇧 🇷🇺 🇨🇳
docs/en/CONTRIBUTING.md	How to contribute, PRs	Contributors	🇬🇧 🇷🇺 🇨🇳
docs/en/SECURITY.md	Security policy, vulnerabilities	Security	🇬🇧 🇷🇺 🇨🇳
AGENTS.md	AI Agent system rules	AI Agent	🇬🇧
SECURITY.md	Security policy, reporting vulnerabilities	Security	🇬🇧
CODE_OF_CONDUCT.md	Community standards	Contributors	🇬🇧

All documents are cross-referenced.

🔧 MCP Tools (50 total)

Core Search

Tool	When to Use
`search_code(query, mode, filter_layer, intent_hint)`	Main search tool. `mode="auto"` / `"fast"` / `"quality"` / `"deep"` / `"context"` / `"ask"`. `intent_hint="code"` / `"docs"` / `"auto"` — soft bucket weighting. `filter_layer="core"` — search within specific architecture layer
`structural_search(pattern)`	AST search: `class_inheritance`, `async_function`, `function_with_decorator` and more
`cross_repo_search(query @repo)`	Search across multiple projects (mono-repo)
`cross_project_deps(action)`	Cross-project dependency graph: `graph` / `deps` / `cycles` / `impact`
`get_symbol_info(query)`	Call Graph: callers, callees, impact files
`impact_analysis(symbol)`	Symbol change impact analysis (risk score, depth)

Index Management

Tool	When to Use
`get_index_status()`	Index status: chunks, files, symbols
`get_index_progress()`	Indexing progress (phase, percent)
`index_project_dir(path)`	Start full project indexing
`get_index_timeline()`	Indexing history by date
`index_health(project_root)`	Index diagnostics and self-recovery
`notify_change(file_path)`	Force index update for a file (via DebounceBatch)
`generate_chunk_summaries(root)`	LLM-generated descriptions for code chunks
`scan_changes(project_root)`	Architectural diff — analyze changes since last baseline

System & Diagnostics

Tool	When to Use
`get_health_report()`	Full self-diagnosis: index, embedder, logs, synchronization
`watcher_status()`	Component status: embedder mode (LM Studio / Ollama / ONNX)
`get_logs(project_root)`	Latest errors and warnings from project logs
`get_repo_map(project_root)`	Project map: file tree + key symbols
`read_live_file(path)`	Read file from LSP memory (including unsaved changes)

Analytics

Tool	When to Use
`get_hotspots(project_root)`	Hotspots — files with high bug rate
`get_repo_rank(project_root, top_k)`	Symbol importance ranking (PageRank on call graph)
`get_bug_correlation(project_root)`	Bug-change correlation analysis
`get_related_files(project_root, path)`	Files related via co-change / bug correlation
`graph_query(query_type, target)`	Knowledge graph queries: `impact` / `feature` / `deps` / `tests`
`find_similar_bugs(error)`	Find similar bugs from history by error text

Git & History

Tool	When to Use
`get_commit_history(root, limit)`	Semantic commit history
`get_file_history(root, path)`	Change history for a specific file
`get_branch_info(project_root)`	Branch info + index status

Lifecycle & Verification

Tool	When to Use
`submit_background_task(type, root)`	Run long tasks: `bug_correlation` / `build_knowledge_graph` / `full_analysis`
`get_task_status(task_id)`	Background task status
`verify_action(action_type)`	Verification: `file_write` / `git_commit` / `git_push` / `index_sync`
`predict_eta(operation)`	Operation time prediction
`run_health_check()`	Full project health check (tests + git)

Intelligence Layer (intel_*) — 14 High-Level Tools

Tool	What it does
`intel_get_runtime_status()`	Aggregated health status: embedder, index, resource usage
`intel_trigger_reindex()`	Fire-and-forget reindexing (does not block Zed)
`intel_get_job_status(job_id)`	Background task progress
`intel_code_topology(symbol)`	Call graph + module topology (< 2 sec)
`intel_get_project_memory()`	Project memory map: ADR, known_issues, tech_debt
`intel_log_incident(...)`	Log an incident to project history
`intel_analyze_incident(error)`	Find similar incidents + ready-made solutions
`intel_add_memory_node(section, data)`	Add a record to project memory
`intel_get_hotspots()`	Top-5 files with highest bug load
`intel_predict_root_cause(error)`	Predict root cause from logs + history
`intel_get_telemetry(days)`	Per-tool telemetry, resource usage, LLM stats
`intel_tool_health()`	Tool success rates, latency, confidence
`intel_execution_timeline(limit)`	Recent action timeline
`intel_explain_project_state(root)`	Human-readable project state diagnosis

🏗️ Architecture

Clean Architecture with DI Container

┌──────────────────────────────────────────────────────────────────┐
│                   MCP Server (~220 lines)                        │
│            src/mcp/server.py — только регистрация                 │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              DI Container (15 services)                   │   │
│  │  src/core/di_container.py — ServiceCollection              │   │
│  │                                                           │   │
│  │  ┌──────────┐  ┌────────────┐  ┌──────────────────────┐  │   │
│  │  │ Indexer  │  │  Searcher  │  │  DebounceBatch       │  │   │
│  │  │ Embedder │  │  SymbolIdx │  │  CircuitBreaker      │  │   │
│  │  │ Parser   │  │  FileGuard │  │  RateLimiter         │  │   │
│  │  └──────────┘  └────────────┘  └──────────────────────┘  │   │
│  └──────────────────────────────────────────────────────────┘   │
│                           │                                       │
│              ┌────────────┴────────────┐                         │
│              ▼                          ▼                         │
│  ┌────────────────────┐  ┌────────────────────────────────────┐  │
│  │  34 Tool Classes   │  │  14 intel_* tools + 2 diag      │  │
│  │  src/mcp/tools/*.py │  │  src/core/intelligence_layer.py    │  │
│  │  Каждый инструмент  │  │  error_boundary decorator          │  │
│  │  — отдельный класс │  │  JSON status/message/detail        │  │
│  │  Constructor Inj.   │  │  asyncio.wait_for(timeout)        │  │
│  └────────────────────┘  └────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐     ┌───────────────────┐
│  RemoteEmbedder  │     │  LanceDB v2       │
│  (LM Studio /    │     │  (Векторная БД)    │
│   Ollama / ONNX) │     │  BM25 + Vector    │
└─────────────────┘     └───────────────────┘

⚡ Performance

Mode	Latency	Best For
`search_code(query, mode="fast")`	~300ms	Simple keyword / exact name
`search_code(query, mode="quality")`	~1200ms	Semantic search with reranker
`search_code(query, mode="deep")`	~2-5s	Complex research across modules
`search_code(query, mode="context")`	~500ms	Find similar code by fragment
`cross_repo_search(query @repo)`	~500ms-2s	Cross-project search

Environment Variables

Variable	Default	Description
`LM_STUDIO_URL`	`http://localhost:1234/v1`	LM Studio API endpoint
`LM_STUDIO_PORT`	`1234`	LM Studio port
`OLLAMA_URL`	`http://localhost:11434`	Ollama API endpoint
`LOG_LEVEL`	`INFO`	Уровень логирования
`ZED_WINDOWS_QUIRKS.md`	(см. файл)	Инструкции для Windows

🔧 Troubleshooting

MCP Server Not Responding

Symptoms: инструменты не отвечают, таймаут.

Checklist:

File → Quit → открой проект заново
Запустите python install.py для перенастройки
Проверьте логи: %LOCALAPPDATA%\Zed\extensions\mscodebase-intelligence\.codebase_indices\logs\

Index Empty (0 chunks)

В Agent Panel выполните:

intel_trigger_reindex()

После проверьте: get_index_status()

LM Studio Connection Issues

# Проверьте, что сервер отвечает:
python -c "import urllib.request; print(urllib.request.urlopen('http://localhost:1234/v1/health').read())"

Должен быть ответ {"status":"ok"}.

📁 Project Structure

mscodebase-intelligence/
├── src/
│   ├── main.py                   # MCP server entry point (~220 lines)
│   ├── lsp_main.py               # LSP server (DI-based, for didSave indexing)
│   ├── mcp/
│   │   ├── server.py             # DI routing — only imports + registration
│   │   └── tools/                 # 10 files, 33 class-based + 10 intel = 43 total
│   │       ├── search_tools.py   # search_code, get_symbol_info, impact_analysis
│   │       ├── indexing_tools.py # notify_change, index_project_dir, index_health
│   │       ├── git_tools.py      # get_branch_info, get_commit_history
│   │       ├── system_tools.py   # get_index_status, watcher_status, read_live_file
│   │       ├── analysis_tools.py # structural_search, get_repo_map, scan_changes
│   │       ├── graph_tools.py    # cross_repo_search, graph_query, get_related_files
│   │       ├── investigation_tools.py  # get_bug_correlation, get_hotspots
│   │       └── lifecycle_tools.py      # submit_background_task, verify_action
│   ├── core/
│   │   ├── di_container.py       # ★ DI Container (15 services, ServiceCollection)
│   │   ├── error_handler.py      # ★ error_boundary + ToolError
│   │   ├── rate_limiter.py       # ★ SlidingWindowRateLimiter + DebounceBatch + CircuitBreaker
│   │   ├── indexer.py            # LanceDB vector storage
│   │   ├── searcher.py           # Hybrid search (BM25 + Dense + RRF)
│   │   ├── symbol_index.py       # Call Graph (BFS, impact analysis)
│   │   ├── intelligence_layer.py # intel_* tools (14 high-level)
│   │   ├── llama_runner.py       # llama.cpp lifecycle manager ★
│   │   ├── remote_embedder.py    # LM Studio / Ollama / llama.cpp / ONNX client
│   │   ├── reranker.py           # Multi-Provider Reranker (HTTP to providers)
│   │   ├── parser.py             # Tree-sitter AST
│   │   ├── health_report.py      # Self-diagnosis engine
│   │   └── ...
│   └── utils/
│       ├── paths.py              # SafePathManager, to_win_long_path
│       └── zed_config.py         # Auto-configure Zed settings
├── docs/
│   ├── en/               # English docs
│   ├── ru/               # Russian docs
│   └── zh/               # Chinese docs
├── tests/                        # 396 tests (pytest)
├── .agents/skills/               # Skills for AI agent
├── install.py                    # Installer
└── README.md

🛠️ Development

See docs/en/CONTRIBUTING.md for:

How to add new MCP tools
Test structure and CI pipeline
Commit message conventions

Quick Start for Devs

# Setup
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# Run MCP server directly (test)
python -m src.main

# Run tests
pytest tests/ -m "not integration and not benchmark"

📄 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

Zed IDE — code editor
LM Studio — local LLM inference
LanceDB — vector database
Model Context Protocol — MCP standard

Name		Name	Last commit message	Last commit date
Latest commit History 379 Commits
.agents		.agents
.github/workflows		.github/workflows
.mscodebase		.mscodebase
docs		docs
locales		locales
logo		logo
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.zed.settings.json.example		.zed.settings.json.example
AGENTS.md		AGENTS.md
AGENT_DIARY.md		AGENT_DIARY.md
AI_INSTALLATION_PROMPT.md		AI_INSTALLATION_PROMPT.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
SECURITY.md		SECURITY.md
extension.toml		extension.toml
install.bat		install.bat
install.py		install.py
install.sh		install.sh
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation