MSCodebase Intelligence

AI-powered semantic code search for Zed IDE — deep code analysis MCP server

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

Last updated: 2026-07-12

🎯 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         │  │
│  │  · 59 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	❌	✅

LSP: Hybrid Rename Only

MSCodeBase uses LSP only for rename_symbol — the LSP client (src/core/lsp_client.py) spawns pyright-langserver for precise cross-file rename, with graceful fallback to SymbolIndex (Tree-sitter) on timeout. All other functionality is implemented through 59 MCP tools.

The standalone LSP server (src/lsp_main.py) was experimental and does not work in Zed — see LSP_WONTFIX.md.

Platforms

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

Languages

Language	Parsing	Call Graph	Data Flow (ASSIGNED_FROM)
Python	✅	✅	✅
TypeScript	✅	✅	✅
TSX	✅	✅	✅
Rust	✅	✅	✅
Go	✅	✅	✅
JavaScript	✅	✅	✅
Java	✅	✅	✅
C#	✅	✅	✅
Ruby	✅	✅	✅
PHP	✅	✅	✅
Kotlin	✅	✅	✅
Swift	✅	✅	✅
C	✅	✅	✅
C++	✅	✅	✅
Scala	✅	✅	✅
Dart	✅	✅	✅

✨ Features

Feature	Description
🔍 Unified Search	`search_code(query, mode, intent_hint)` — single tool: fast/quality/deep/context/ask/auto
🧠 Intelligence Layer	14 high-level `intel_*` tools: self-diagnostics, topology, memory, 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 answer generation via 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), 59 tools (41 class-based + 15 intel + 3 diag), 494+ tests
🪟 Multi-Window	`ProjectIndexerRegistry` — isolated Indexer per project, LRU 5, ResourceMonitor throttle
✏️ Write Tools	6 write tools + 1 graph query (`query_graph`) with Cypher engine
⚡ Meta-Patching	LanceDB `move_chunks_metadata` — file_path rename without re-embedding (50ms vs 5s)
🔗 Data Flow Graph	`ASSIGNED_FROM` edges track variable assignments. Unified Walker + Conditional Flow (if/for/while/try). 3,337 edges on MSCodeBase (81% conditional).
⚙️ SYSTEM_PROFILE	`light` (sync) / `server` (async with phi-4)

🚀 Quick Start

Install the mscodebase-intelligence extension in Zed, then:

cd D:\Project\MSCodeBase
python install.py

# Restart Zed (File → Quit → reopen)
# Verify: intel_get_runtime_status()

install.py does:

Copies 39+ source files to the extension directory
Installs Python dependencies
Downloads llama-server.exe + GGUF models (E5-base embed + reranker)
Configures MCP in Zed's settings.json

See also: AI_INSTALLATION_PROMPT.md, docs/en/INSTALL.md

Providers

MCP auto-selects the best available provider:

llama.cpp GGUF (GPU) → ONNX Runtime (CPU) → LM Studio (if running) → BM25 only
   ~1.0 GB RAM           ~1.7 GB RAM          ~6 GB RAM             no embeddings
   2× llama-server       in-process ONNX       external API

Benchmarks: docs/research/2026-07-10-final-benchmark.md

📚 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	5 levels of graceful degradation (llama.cpp → ONNX → BM25)	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	🇬🇧

| docs/KNOWN_ISSUES.md | Known issues & technical debt registry | All | 🇬🇧 |

All documents are cross-referenced. Available in 3 languages: English, Русский, 中文.

🔧 MCP Tools (59 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, indexing, health
`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)
`predict_eta(operation)`	Predict operation duration based on history
`run_health_check()`	Full project health check (tests + git + index)

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`
`query_graph(query)` (new v3.2)	Cypher-like graph queries: `MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name`
`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`

Write Tools (7)

Tool	When to Use
`rename_symbol(old, new, apply)`	Rename symbol across all files (preview/apply, collision check)
`move_symbol(symbol, to_file, apply)`	Move symbol to another file (preview/apply, import updates)
`safe_delete(symbol, force, apply)`	Safe delete with reference check (force mode)
`replace_symbol(symbol, new_code, apply)`	Replace function/class body (preview/apply)
`insert_before_symbol(anchor, new_code, apply)`	Insert code before anchor symbol (preview/apply)
`insert_after_symbol(anchor, new_code, apply)`	Insert code after anchor's body (preview/apply)
`ack_impact(file_path)`	Acknowledge impact for modification guard

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_explain_project_state(root)`	Human-readable project state diagnosis
`intel_get_project_context(root)`	Single snapshot: state, index, health, memory

Diagnostic Tools (3)

Tool	What it does
`debug_runtime_passport()`	Process passport: RUN_ID, PID, build info
`get_runtime_counters()`	Runtime counters: calls, blocks, warnings
`intel_execution_timeline(limit)`	Recent action timeline with durations

🏗️ Architecture

Clean Architecture with DI Container

┌──────────────────────────────────────────────────────────────────┐
│                   MCP Server (~220 lines)                        │
│            src/mcp/server.py — registration only                │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              DI Container (15 services)                   │   │
│  │  src/core/di_container.py — ServiceCollection              │   │
│  │                                                           │   │
│  │  ┌──────────┐  ┌────────────┐  ┌──────────────────────┐  │   │
│  │  │ Indexer  │  │  Searcher  │  │  DebounceBatch       │  │   │
│  │  │ Embedder │  │  SymbolIdx │  │  CircuitBreaker      │  │   │
│  │  │ Parser   │  │  FileGuard │  │  RateLimiter         │  │   │
│  │  └──────────┘  └────────────┘  └──────────────────────┘  │   │
│  └──────────────────────────────────────────────────────────┘   │
│                           │                                       │
│              ┌────────────┴────────────┐                         │
│              ▼                          ▼                         │
│  ┌────────────────────┐  ┌────────────────────────────────────┐  │
│  41 Tool Classes   │  │  14 intel_* tools + 3 diag      │
│  │  src/mcp/tools/*.py │  │  src/core/intelligence_layer.py    │  │
│  │  One class per tool  │  │  error_boundary decorator          │
│  │  Constructor Inj.   │  │  JSON status/message/detail        │  │
│  │  Constructor Inj.   │  │  asyncio.wait_for(timeout)        │  │
│  └────────────────────┘  └────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐     ┌───────────────────┐
│  RemoteEmbedder  │     │  LanceDB v2       │
│  (LM Studio /    │     │  (Vector DB)       │
│   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`	Logging verbosity level
`ZED_WINDOWS_QUIRKS.md`	(see file)	Windows-specific instructions

🔧 Troubleshooting

MCP Server Not Responding

Symptoms: tools timeout, no response.

Checklist:

File → Quit → reopen the project
Run python install.py to reconfigure
Check logs: %LOCALAPPDATA%\Zed\extensions\mscodebase-intelligence\.codebase_indices\logs\

Index Empty (0 chunks)

Run in Agent Panel:

intel_trigger_reindex()

Then verify: get_index_status()

LM Studio Connection Issues

# Verify the server responds:
python -c "import urllib.request; print(urllib.request.urlopen('http://localhost:1234/v1/health').read())"

Expected: {"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
│   │   ├── write_tools.py        # rename/move/delete/replace/insert symbols
│   └── tools/                 # 11 files, 41 class-based tools
│   │       ├── 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
│   │   ├── lsp_client.py          # Thin LSP client (pyright JSON-RPC 2.0)
│   │   ├── modification_guard.py  # @modification_guard decorator (ack + TTL)
│   │   └── ...
│   └── 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/                        # 494 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 463 Commits
.agents		.agents
.github/workflows		.github/workflows
docs		docs
locales		locales
logo		logo
scripts		scripts
src		src
telemetry		telemetry
tests		tests
tools		tools
.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
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
SECURITY.md		SECURITY.md
_temp_get_events.ps1		_temp_get_events.ps1
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

MSCodebase Intelligence

🎯 Positioning

What you get

LSP: Hybrid Rename Only

Platforms

Languages

✨ Features

🚀 Quick Start

Providers

📚 Documentation Map

🔧 MCP Tools (59 total)

Core Search

Index Management

System & Diagnostics

Analytics

Git & History

Lifecycle & Verification

Write Tools (7)

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

Diagnostic Tools (3)

🏗️ Architecture

Clean Architecture with DI Container

⚡ Performance

Environment Variables

🔧 Troubleshooting

MCP Server Not Responding

Index Empty (0 chunks)

LM Studio Connection Issues

📁 Project Structure

🛠️ Development

Quick Start for Devs

📄 License

🙏 Acknowledgments

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages