DevContext

DevContext is a powerful, context middleware engine running entirely on the Model Context Protocol (MCP) standard over standard I/O (stdio) transport. It fundamentally bridges the gap between advanced LLM clients (like Claude Desktop and Cursor) and deep local software repositories by giving AI immediate, high-fidelity awareness of your codebase.

Instead of relying on blind flat-text line slicing, DevContext natively understands your code structurally and chronologically. By replacing naive text chunks with syntax-tree definitions and history-aware structural blocks, it delivers highly accurate, context-dense retrieval payloads that exponentially improve the reliability of LLM code generation and analysis.

---

System Architecture Layout

+-------------------------------------------------------------+
|               MCP Client Host (Claude / Cursor)             |
+------------------------------+------------------------------+
                               |
                               v
+------------------------------+------------------------------+
|                   FastMCP Protocol Interface                |
|                    (stdio transport layer)                  |
+------------------------------+------------------------------+
                               |
           +-------------------+-------------------+
           |                   |                   |
           v                   v                   v
+--------------------+ +--------------------+ +--------------------+
|     AST-Parser     | |  Lexical Indexer   | |   Git Historian    |
|   (tree-sitter)    | |    (rank-bm25)     | |    (gitpython)     |
+--------------------+ +--------------------+ +--------------------+
           |                   |                   |
           +-------------------+-------------------+
                               |
                               v
+------------------------------+------------------------------+
|                Weighted Hybrid Ranking Core                 |
|       (50% Semantic | 35% Lexical | 15% Recency Decay)      |
+------------------------------+------------------------------+
                               |
                               v
+------------------------------+------------------------------+
|                   Unified Context Payload                   |
|         (Structured blocks returned to MCP Client)          |
+-------------------------------------------------------------+

---

Deep-Dive Feature Breakdown

AST-Aware Structural Ingestion

DevContext completely eliminates disjointed, fragmented retrieval context. It leverages tree-sitter and tree-sitter-python to parse code into live concrete syntax trees. By surgically targeting function_definition and class_definition nodes and extracting them alongside their precise 1-based editor line coordinates, the LLM receives unbroken logical blocks of code. For flat data text documents (like .md or .json), the system gracefully defaults to a smart, overlapping windowed character-fallback layer.

3-Signal Hybrid Retrieval Optimization

When querying the workspace, the retriever fuses three distinct scoring signals to return hyper-relevant results:

• Signal 1 (Dense Semantic Vectors - 50% weight): Powered by local ChromaDB and Sentence-Transformers (all-MiniLM-L6-v2), it calculates semantic distance representations mapped tightly via a normalized cosine approximation scaled at 1.0 - (L2_Distance / 2.0).
• Signal 2 (Sparse Lexical Keywords - 35% weight): Exact term overlapping powered by BM25Okapi. The token frequencies are normalized against the maximum score array to prevent generic keyword flooding.
• Signal 3 (Temporal Git Recency Decay - 15% weight): Employs gitpython log delta tracking to ascertain code volatility. Applying categorical priority boosts based on the modification history age (≤ 7 days = 1.0 boost, ≤ 30 days = 0.5 boost), DevContext ensures the AI pays the most attention to code actively being worked on.

Workspace Dependency Graph Resource

Exposes the fundamental routing layout of your application dynamically. DevContext sniffs top-level import_statement and import_from_statement syntax nodes using tree-sitter and serializes the topological relationships into a clean, read-only JSON mapping available directly as an MCP Resource.

---

Complete Protocol Matrix Interface

Type	Name	Protocol URI / Signature	Functional Responsibility
Tool	search_files	search_files(query: str, workspace_path: str)	Hybrid semantic, BM25, and git recency decay search across all workspace files.
Tool	find_definition	find_definition(symbol: str, workspace_path: str)	Locate specific function or class definitions across the AST-indexed workspace.
Tool	git_blame	git_blame(filepath: str, line_number: int, workspace_path: str)	Retrieve exact chronological telemetry (Author, Date, Commit Message) for any code line.
Resource	workspace://dependency-graph	workspace://dependency-graph	Expose a complete JSON-serialized import graph mapping structural file relationships.

---

Full Tech Stack Glossary

• Python (Asynchronous core): Delivers high-performance backend logic handling concurrent multi-process file indexing.
• FastMCP (Protocol wrapper): A highly efficient bridge facilitating rapid tool and resource orchestration over the MCP stdio standard.
• ChromaDB (Local vector storage): Zero-latency embedded vector storage operating entirely locally.
• Sentence-Transformers (API-key-free execution embeddings): Runs all-MiniLM-L6-v2 locally on your CPU for completely air-gapped security and rapid dense embedding calculations.
• tree-sitter (Concrete syntax tree structures): Provides robust, fault-tolerant C-based syntax parsers for deeply structural code extraction.
• rank-bm25 (Statistical term filtering): Filters keyword densities efficiently to heavily anchor semantic queries to precise variables and terminology.
• gitpython (Chronological git telemetry parsing): Harvests local repository history, commits, and blames to measure code age and activity.

---

Installation, Integration & Quickstart Verification

Quickstart

Clone the repository and spin up the environment:

git clone https://github.com/YOUR_USERNAME/devcontext-mcp
cd devcontext-mcp
pip install -r requirements.txt
python server.py

Cursor Editor Integration

DevContext provides out-of-the-box support for the Cursor IDE. A .cursor/mcp.json file is already baked into the repository footprint. Simply open the devcontext-mcp folder inside Cursor and restart the IDE. DevContext will dynamically appear inside Cursor's MCP tools panel.

Claude Desktop App Integration

Open your Claude Desktop configuration JSON file and append the following block within the mcpServers object. Be sure to supply the absolute path to your local server.py file:

{
  "mcpServers": {
    "devcontext": {
      "command": "python",
      "args": ["YOUR_ABSOLUTE_PATH_TO/devcontext-mcp/server.py"]
    }
  }
}

Restart Claude Desktop to finalize the connection.

Test Suite Verification

Ensure your local sandbox operates perfectly. Run the fully isolated, 4-layer sandboxed regression sequence:

python tests/test_suite.py

You should expect 4/4 tests passed. validating your local DB write locks, tree-sitter parsing bindings, and FastMCP integrations.

---

Real-World Developer Use Cases

Unleash the LLM in your prompt window with requests like:

1. "Query DevContext and search the codebase for our user authentication and JWT validation logic."
2. "Invoke the find_definition tool and show me the exact parameters required by the DatabaseConnectionPool class."
3. "There is a bug on line 42 of server.py. Fetch the git_blame history for that line and tell me what the developer was trying to achieve."
4. "Fetch the workspace://dependency-graph resource. Write a short report detailing exactly which files import the os and sys modules."
5. "Using DevContext, find the core retrieval function, read its dependencies, and write unit tests covering its edge cases."