# raghurammrsd/code_graph_mcp architecture

> Architecture diagram of the GitHub repository raghurammrsd/code_graph_mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raghurammrsd/code_graph_mcp
- Repository: https://github.com/raghurammrsd/code_graph_mcp

## Overview

CodeGraph MCP is a local repository-intelligence engine for AI coding agents. Its main workflow is an agent request through the MCP server, which compiles a task into bounded, evidence-backed context from indexed code, search, and graph relationships. The product also exposes database and framework intelligence, runtime observations, Git freshness and impact analysis, and refactoring tools. The map follows README descriptions and SOURCE INDEX references; unsampled subsystems are included where documented, but their internal call paths are not guessed.

Main entry points: [`src/codegraph/indexing/indexer.py`](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/indexing/indexer.py) (Incremental indexer), [`src/codegraph/context.py`](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/context.py) (Context compiler), [`src/codegraph/mcp/server.py`](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/mcp/server.py) (MCP tools), [`src/codegraph/refactor/renamer.py`](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/refactor/renamer.py) (Safe refactoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Agent interfaces"]
  node_mcp["MCP tools<br/>[server.py]"]
  node_web["Web dashboard<br/>[server.py]"]
  node_vscode["VS Code extension<br/>[extension.ts]"]
end

subgraph group_intelligence["Repository intelligence"]
  node_context["Context compiler<br/>[context.py]"]
  node_task["Task specification<br/>[task.py]"]
  node_indexer["Incremental indexer<br/>[indexer.py]"]
  node_parser["AST parsers<br/>[parser.py]"]
  node_indexmodels["Index models<br/>[models.py]"]
  node_classifier["File classifier<br/>[classifier.py]"]
  node_search["Hybrid search<br/>[hybrid.py]"]
  node_graph["Graph traversal<br/>[traversal.py]"]
  node_resolver["Target resolver<br/>[target_resolver.py]"]
end

subgraph group_evidence["Evidence and state"]
  node_evidence["Evidence contracts"]
  node_freshness["Index freshness<br/>[freshness.py]"]
  node_security["Path and secret safety<br/>[paths.py]"]
end

subgraph group_extensions["Domain intelligence"]
  node_frameworks["Framework routes<br/>[frameworks.py]"]
  node_db["Database intelligence<br/>[extractor.py]"]
  node_schema["Schema drift<br/>[schema_drift.py]"]
  node_runtime["Runtime observation<br/>[ingestor.py]"]
  node_monorepo["Workspace boundaries<br/>[monorepo.py]"]
end

subgraph group_operations["Runtime and changes"]
  node_impact["Change impact<br/>[change_impact.py]"]
  node_refactor["Safe refactoring<br/>[renamer.py]"]
  node_refmodels["Refactor models<br/>[models.py]"]
  node_git["Git intelligence<br/>[git.py]"]
end

node_agent(("AI coding agent"))

node_agent -->|"queries via MCP"| node_mcp
node_mcp -->|"requests context"| node_context
node_context -->|"normalizes task"| node_task
node_context -->|"resolves targets"| node_resolver
node_context -->|"retrieves matches"| node_search
node_context -->|"retrieves relationships"| node_graph
node_context -.->|"grounds results"| node_evidence
node_indexer -->|"parses source"| node_parser
node_indexer -->|"classifies files"| node_classifier
node_indexer -->|"stores parsed records"| node_indexmodels
node_indexer -->|"analyzes frameworks"| node_frameworks
node_indexer -->|"checks evidence"| node_evidence
node_indexer -->|"redacts indexed data"| node_security
node_indexer -->|"tracks index state"| node_freshness
node_mcp -->|"serves index queries"| node_indexer
node_mcp -->|"serves database tools"| node_db
node_mcp -->|"serves runtime tools"| node_runtime
node_db -.->|"supports drift analysis"| node_schema
node_web -->|"uses indexing"| node_indexer
node_web -->|"requests impact analysis"| node_impact
node_graph -->|"feeds impact analysis"| node_impact
node_impact -->|"uses workspace boundaries"| node_monorepo
node_refactor -->|"reindexes after changes"| node_indexer
node_refactor -->|"uses refactor models"| node_refmodels
node_refactor -->|"validates paths"| node_security
node_freshness -.->|"checks repository state"| node_git
node_agent -.->|"initiates extension requests"| node_vscode

click node_mcp "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/mcp/server.py"
click node_web "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/ui/server.py"
click node_vscode "https://github.com/raghurammrsd/code_graph_mcp/blob/main/vscode-extension/src/extension.ts"
click node_context "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/context.py"
click node_task "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/task.py"
click node_indexer "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/indexing/indexer.py"
click node_parser "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/indexing/parser.py"
click node_indexmodels "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/indexing/models.py"
click node_classifier "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/indexing/classifier.py"
click node_frameworks "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/frameworks.py"
click node_search "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/search/hybrid.py"
click node_graph "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/graph/traversal.py"
click node_resolver "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/target_resolver.py"
click node_evidence "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/evidence_contract.py"
click node_freshness "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/freshness.py"
click node_security "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/security/paths.py"
click node_db "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/database/extractor.py"
click node_schema "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/database/schema_drift.py"
click node_runtime "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/runtime/ingestor.py"
click node_monorepo "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/monorepo.py"
click node_impact "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/change_impact.py"
click node_refactor "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/refactor/renamer.py"
click node_refmodels "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/refactor/models.py"
click node_git "https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/git.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_mcp,node_web,node_vscode toneBlue
class node_context,node_task,node_indexer,node_parser,node_indexmodels,node_classifier,node_search,node_graph,node_resolver toneAmber
class node_evidence,node_freshness,node_security toneMint
class node_frameworks,node_db,node_schema,node_runtime,node_monorepo toneRose
class node_impact,node_refactor,node_refmodels,node_git,node_agent toneIndigo
```

## Components

### Agent interfaces

- [MCP tools](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/mcp/server.py): `src/codegraph/mcp/server.py`
- [Web dashboard](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/ui/server.py): `src/codegraph/ui/server.py`
- [VS Code extension](https://github.com/raghurammrsd/code_graph_mcp/blob/main/vscode-extension/src/extension.ts): `vscode-extension/src/extension.ts`

### Repository intelligence

- [Context compiler](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/context.py): `src/codegraph/context.py`
- [Task specification](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/task.py): `src/codegraph/task.py`
- [Incremental indexer](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/indexing/indexer.py): `src/codegraph/indexing/indexer.py`
- [AST parsers](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/indexing/parser.py): `src/codegraph/indexing/parser.py`
- [Index models](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/indexing/models.py): `src/codegraph/indexing/models.py`
- [File classifier](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/indexing/classifier.py): `src/codegraph/indexing/classifier.py`
- [Hybrid search](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/search/hybrid.py): `src/codegraph/search/hybrid.py`
- [Graph traversal](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/graph/traversal.py): `src/codegraph/graph/traversal.py`
- [Target resolver](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/target_resolver.py): `src/codegraph/target_resolver.py`

### Evidence and state

- [Evidence contracts](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/evidence_contract.py): `src/codegraph/evidence_contract.py`
- [Index freshness](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/freshness.py): `src/codegraph/freshness.py`
- [Path and secret safety](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/security/paths.py): `src/codegraph/security/paths.py`

### Domain intelligence

- [Framework routes](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/frameworks.py): `src/codegraph/frameworks.py`
- [Database intelligence](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/database/extractor.py): `src/codegraph/database/extractor.py`
- [Schema drift](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/database/schema_drift.py): `src/codegraph/database/schema_drift.py`
- [Runtime observation](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/runtime/ingestor.py): `src/codegraph/runtime/ingestor.py`
- [Workspace boundaries](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/monorepo.py): `src/codegraph/monorepo.py`

### Runtime and changes

- [Change impact](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/change_impact.py): `src/codegraph/change_impact.py`
- [Safe refactoring](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/refactor/renamer.py): `src/codegraph/refactor/renamer.py`
- [Refactor models](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/refactor/models.py): `src/codegraph/refactor/models.py`
- [Git intelligence](https://github.com/raghurammrsd/code_graph_mcp/blob/main/src/codegraph/git.py): `src/codegraph/git.py`

### Other components

- **AI coding agent**

## Connections

- AI coding agent → MCP tools: queries via MCP (evidence: `README.md`)
- MCP tools → Context compiler: requests context (evidence: `src/codegraph/mcp/server.py`)
- Context compiler → Task specification: normalizes task (evidence: `src/codegraph/context.py`)
- Context compiler → Target resolver: resolves targets (evidence: `src/codegraph/context.py`)
- Context compiler → Hybrid search: retrieves matches (evidence: `src/codegraph/context.py`)
- Context compiler → Graph traversal: retrieves relationships (evidence: `src/codegraph/context.py`)
- Context compiler → Evidence contracts: grounds results (evidence: `src/codegraph/context.py`)
- Incremental indexer → AST parsers: parses source (evidence: `src/codegraph/indexing/indexer.py`)
- Incremental indexer → File classifier: classifies files (evidence: `src/codegraph/indexing/indexer.py`)
- Incremental indexer → Index models: stores parsed records (evidence: `src/codegraph/indexing/indexer.py`)
- Incremental indexer → Framework routes: analyzes frameworks (evidence: `src/codegraph/indexing/indexer.py`)
- Incremental indexer → Evidence contracts: checks evidence (evidence: `src/codegraph/indexing/indexer.py`)
- Incremental indexer → Path and secret safety: redacts indexed data (evidence: `src/codegraph/indexing/indexer.py`)
- Incremental indexer → Index freshness: tracks index state (evidence: `src/codegraph/indexing/indexer.py`)
- MCP tools → Incremental indexer: serves index queries (evidence: `src/codegraph/mcp/server.py`)
- MCP tools → Database intelligence: serves database tools (evidence: `src/codegraph/mcp/server.py`)
- MCP tools → Runtime observation: serves runtime tools (evidence: `src/codegraph/mcp/server.py`)
- Database intelligence → Schema drift: supports drift analysis
- Web dashboard → Incremental indexer: uses indexing (evidence: `src/codegraph/ui/server.py`)
- Web dashboard → Change impact: requests impact analysis (evidence: `src/codegraph/ui/server.py`)
- Graph traversal → Change impact: feeds impact analysis (evidence: `src/codegraph/change_impact.py`)
- Change impact → Workspace boundaries: uses workspace boundaries (evidence: `src/codegraph/change_impact.py`)
- Safe refactoring → Incremental indexer: reindexes after changes (evidence: `src/codegraph/refactor/renamer.py`)
- Safe refactoring → Refactor models: uses refactor models (evidence: `src/codegraph/refactor/renamer.py`)
- Safe refactoring → Path and secret safety: validates paths (evidence: `src/codegraph/refactor/renamer.py`)
- Index freshness → Git intelligence: checks repository state
- AI coding agent → VS Code extension: initiates extension requests
