# DevContext — Workspace-Aware MCP Intelligence Server

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

```ascii
+-------------------------------------------------------------+
|               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:
```bash
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:
```json
{
  "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:
```bash
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."