# mikerecognex/mcp-codebase-index architecture

> Architecture diagram of the GitHub repository mikerecognex/mcp-codebase-index, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mikerecognex/mcp-codebase-index
- Repository: https://github.com/mikerecognex/mcp-codebase-index

## Overview

mcp-codebase-index indexes a selected project and exposes structural navigation through an MCP server. Its main workflow is MCP client request → server initialization or change check → project indexing and language-specific annotation → query functions over the index → results to the client. The graph preserves the documented language parsers, incremental Git updates, and persistent cache. Source excerpts support the main dispatch and orchestration links; some finer query and cache behavior is documented only in the README.

Main entry points: [`src/mcp_codebase_index/models.py`](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/models.py) (Index Models), [`src/mcp_codebase_index/annotator.py`](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/annotator.py) (Annotator Dispatch), [`src/mcp_codebase_index/server.py`](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/server.py) (MCP Server), [`src/mcp_codebase_index/project_indexer.py`](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/project_indexer.py) (Project Indexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP Runtime"]
  node_server["MCP Server<br/>[server.py]"]
  node_queries["Query API<br/>[query_api.py]"]
end

subgraph group_indexing["Project Indexing"]
  node_tracker["Git Tracker<br/>[git_tracker.py]"]
  node_indexer["Project Indexer<br/>[project_indexer.py]"]
end

subgraph group_parsing["Language Annotation"]
  node_dispatcher["Annotator Dispatch<br/>[annotator.py]"]
  node_python["Python Parser"]
  node_typescript["TypeScript Parser"]
  node_go["Go Parser<br/>[go_annotator.py]"]
  node_rust["Rust Parser<br/>[rust_annotator.py]"]
  node_csharp["C&#35; Parser"]
  node_text["Text Parser<br/>[text_annotator.py]"]
  node_json["JSON Parser<br/>[json_annotator.py]"]
  node_generic["Fallback Parser"]
end

subgraph group_data["Index Data"]
  node_models["Index Models<br/>[models.py]"]
  node_cache[("Disk Cache<br/>[server.py]")]
end

node_client(("MCP Client"))

node_client -->|"sends tool requests"| node_server
node_server -->|"builds index"| node_indexer
node_server -->|"creates query functions"| node_queries
node_server -->|"checks Git state"| node_tracker
node_server -->|"loads and saves"| node_cache
node_server -->|"returns query results"| node_client
node_indexer -->|"annotates files"| node_dispatcher
node_dispatcher -->|"dispatches Python"| node_python
node_dispatcher -->|"dispatches JS/TS"| node_typescript
node_dispatcher -->|"dispatches Go"| node_go
node_dispatcher -->|"dispatches Rust"| node_rust
node_dispatcher -->|"dispatches C&#35;"| node_csharp
node_dispatcher -->|"dispatches text"| node_text
node_dispatcher -->|"dispatches JSON"| node_json
node_dispatcher -->|"dispatches fallback"| node_generic
node_python -->|"produces metadata"| node_models
node_typescript -->|"produces metadata"| node_models
node_go -->|"produces metadata"| node_models
node_rust -->|"produces metadata"| node_models
node_csharp -->|"produces metadata"| node_models
node_text -->|"produces metadata"| node_models
node_json -->|"produces metadata"| node_models
node_generic -->|"produces metadata"| node_models
node_indexer -->|"builds project index"| node_models
node_queries -->|"queries index data"| node_models
node_indexer -.->|"updates changed files"| node_tracker
node_cache -->|"persists index"| node_models

click node_server "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/server.py"
click node_queries "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/query_api.py"
click node_tracker "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/git_tracker.py"
click node_indexer "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/project_indexer.py"
click node_dispatcher "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/annotator.py"
click node_python "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/python_annotator.py"
click node_typescript "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/typescript_annotator.py"
click node_go "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/go_annotator.py"
click node_rust "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/rust_annotator.py"
click node_csharp "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/csharp_annotator.py"
click node_text "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/text_annotator.py"
click node_json "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/json_annotator.py"
click node_generic "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/generic_annotator.py"
click node_models "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/models.py"
click node_cache "https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_queries,node_client toneBlue
class node_tracker,node_indexer toneAmber
class node_dispatcher,node_python,node_typescript,node_go,node_rust,node_csharp,node_text,node_json,node_generic toneMint
class node_models,node_cache toneRose
```

## Components

### MCP Runtime

- [MCP Server](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/server.py): `src/mcp_codebase_index/server.py`
- [Query API](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/query_api.py): `src/mcp_codebase_index/query_api.py`

### Project Indexing

- [Git Tracker](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/git_tracker.py): `src/mcp_codebase_index/git_tracker.py`
- [Project Indexer](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/project_indexer.py): `src/mcp_codebase_index/project_indexer.py`

### Language Annotation

- [Annotator Dispatch](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/annotator.py): `src/mcp_codebase_index/annotator.py`
- [Python Parser](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/python_annotator.py): `src/mcp_codebase_index/python_annotator.py`
- [TypeScript Parser](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/typescript_annotator.py): `src/mcp_codebase_index/typescript_annotator.py`
- [Go Parser](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/go_annotator.py): `src/mcp_codebase_index/go_annotator.py`
- [Rust Parser](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/rust_annotator.py): `src/mcp_codebase_index/rust_annotator.py`
- [C# Parser](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/csharp_annotator.py): `src/mcp_codebase_index/csharp_annotator.py`
- [Text Parser](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/text_annotator.py): `src/mcp_codebase_index/text_annotator.py`
- [JSON Parser](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/json_annotator.py): `src/mcp_codebase_index/json_annotator.py`
- [Fallback Parser](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/generic_annotator.py): `src/mcp_codebase_index/generic_annotator.py`

### Index Data

- [Index Models](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/models.py): `src/mcp_codebase_index/models.py`
- [Disk Cache](https://github.com/mikerecognex/mcp-codebase-index/blob/main/src/mcp_codebase_index/server.py): `src/mcp_codebase_index/server.py`

### Other components

- **MCP Client**

## Connections

- MCP Client → MCP Server: sends tool requests (evidence: `README.md`)
- MCP Server → Project Indexer: builds index (evidence: `src/mcp_codebase_index/server.py`)
- MCP Server → Query API: creates query functions (evidence: `src/mcp_codebase_index/server.py`)
- MCP Server → Git Tracker: checks Git state (evidence: `src/mcp_codebase_index/server.py`)
- MCP Server → Disk Cache: loads and saves (evidence: `src/mcp_codebase_index/server.py`)
- MCP Server → MCP Client: returns query results (evidence: `README.md`)
- Project Indexer → Annotator Dispatch: annotates files (evidence: `src/mcp_codebase_index/project_indexer.py`)
- Annotator Dispatch → Python Parser: dispatches Python (evidence: `src/mcp_codebase_index/annotator.py`)
- Annotator Dispatch → TypeScript Parser: dispatches JS/TS (evidence: `src/mcp_codebase_index/annotator.py`)
- Annotator Dispatch → Go Parser: dispatches Go (evidence: `src/mcp_codebase_index/annotator.py`)
- Annotator Dispatch → Rust Parser: dispatches Rust (evidence: `src/mcp_codebase_index/annotator.py`)
- Annotator Dispatch → C# Parser: dispatches C# (evidence: `src/mcp_codebase_index/annotator.py`)
- Annotator Dispatch → Text Parser: dispatches text (evidence: `src/mcp_codebase_index/annotator.py`)
- Annotator Dispatch → JSON Parser: dispatches JSON (evidence: `src/mcp_codebase_index/annotator.py`)
- Annotator Dispatch → Fallback Parser: dispatches fallback (evidence: `src/mcp_codebase_index/annotator.py`)
- Python Parser → Index Models: produces metadata (evidence: `src/mcp_codebase_index/python_annotator.py`)
- TypeScript Parser → Index Models: produces metadata (evidence: `src/mcp_codebase_index/typescript_annotator.py`)
- Go Parser → Index Models: produces metadata (evidence: `src/mcp_codebase_index/go_annotator.py`)
- Rust Parser → Index Models: produces metadata (evidence: `src/mcp_codebase_index/rust_annotator.py`)
- C# Parser → Index Models: produces metadata (evidence: `src/mcp_codebase_index/csharp_annotator.py`)
- Text Parser → Index Models: produces metadata (evidence: `src/mcp_codebase_index/text_annotator.py`)
- JSON Parser → Index Models: produces metadata (evidence: `src/mcp_codebase_index/json_annotator.py`)
- Fallback Parser → Index Models: produces metadata (evidence: `src/mcp_codebase_index/generic_annotator.py`)
- Project Indexer → Index Models: builds project index (evidence: `src/mcp_codebase_index/project_indexer.py`)
- Query API → Index Models: queries index data (evidence: `src/mcp_codebase_index/query_api.py`)
- Project Indexer → Git Tracker: updates changed files
- Disk Cache → Index Models: persists index (evidence: `src/mcp_codebase_index/server.py`)
