ContextTree MCP 🌳

Deep semantic code search for AI assistants — powered by AST parsing and local embeddings. 100% offline.

ContextTree MCP is a local Model Context Protocol server that gives your AI coding assistant structural understanding of a codebase. It combines two worlds:

• tree-sitter parses source files into an AST and extracts logical blocks — functions, methods, class signatures with docstrings.

• sentence-transformers (all-MiniLM-L6-v2) embeds each block — enriched with file path, class name, method name and docstring — into a local ChromaDB vector store.

The result: your assistant finds code by meaning, not by keywords, and every search hit comes back with exact file path and line numbers.

🔒 Privacy first. Everything runs on your machine: parsing, embedding model, vector index. No cloud calls, no telemetry, no code ever leaves the disk it lives on.

Why not plain text search?

grep and full-text search match strings. They fail exactly where developers need help most:

Related MCP server: CodeGrok MCP

Features

• 🌲 AST-aware chunking — indexes functions, methods and class signatures via tree-sitter, not arbitrary text windows.

• 🧩 Context-Enriched Logical Blocks — every indexed document embeds its file path, owning class, method name, docstring and body, so queries like "payment retry logic" hit the right method.

• ⚡ Incremental indexing — SHA-256 content hashes per file; only changed/new/deleted files are reprocessed.

• 🔍 Semantic search — natural-language query → ranked code fragments with exact line ranges.

• 📞 AST usage lookup — find real call sites of any symbol (function or class), filtered from false positives like string literals or comments.

• 🗄️ Persistent local index — ChromaDB stored in .chroma/, survives restarts, never committed to Git.

• 🔌 Stdio MCP transport — plugs into Claude Desktop, OpenCode, Cursor, Cline, or any MCP-compatible client.

Tech stack

Installation

Requires Python 3.12+. uv is recommended as a fast, modern package manager:

git clone https://github.com/<your-org>/mcp-context-tree.git
cd mcp-context-tree

# Option A — uv (recommended): resolves dependencies from pyproject.toml, locks uv.lock
uv sync

# Option B — classic pip + venv
python -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

💡 First run downloads the embedding model (~90 MB). PyTorch is installed as a dependency of sentence-transformers; CPU build is sufficient — no GPU required.

Registering with an MCP client

Example configuration (Claude Desktop / any client supporting stdio servers):

{
  "mcpServers": {
    "context-tree": {
      "command": "<path-to-venv>/bin/python",
      "args": ["-m", "context_tree"],
      "env": {}
    }
  }
}

(On Windows use <path-to-venv>\Scripts\python.exe.)

Tools exposed to the assistant

Typical workflow:

1. index_workspace("D:/projects/my-app")
2. semantic_search("where do we handle payment retries", limit=8)
3. find_ast_usages("PaymentGateway.retry")

Supported languages

Documentation

• 🏛️ ARCHITECTURE.md — project layout, ChromaDB data schema, AST extraction logic, incremental indexing design.

• 🇷🇺 README.ru.md — документация на русском языке.

Roadmap

• Watch mode — automatic re-indexing on file change (fs watcher)

• More languages via tree-sitter bindings

• Hybrid search (BM25 + vectors rerank)

• Call-graph aware ranking ("who calls this?")

• PyPI release (context-tree-mcp)

Contributing

Issues and PRs are welcome. Please keep changes consistent with ARCHITECTURE.md.

License

MIT — see LICENSE.