# ayushd64/repomirror-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/ayushd64/repomirror-mcp
- Repository: https://github.com/ayushd64/repomirror-mcp

## Overview

1. This repo is a small Python MCP server that exposes repository-analysis capabilities to a desktop LLM client. The main runtime is a local Python process launched from `server.py`, with `calculator.py` serving as an example target file for structural analysis.

2. The primary boundary is between the client side and the local analysis engine. A VS Code/Cline client sends MCP requests over JSON-RPC to the server; the server never appears to call a cloud API and is intended to run fully locally.

3. `server.py` is the orchestration layer. It is the MCP entrypoint that registers tools and dispatches requests into repository inspection logic. In an architecture diagram, this is the central node between the LLM client and all local data sources.

4. The repository data layer is the local git checkout itself. The server reads commit history, authorship, and file changes from the on-disk repo using GitPython, so git is not just a VCS dependency but the source of timeline and evolution data.

5. One subsystem builds a codebase graph from git history. The README names `get_codebase_graph`, which uses NetworkX to model commits and file nodes chronologically. This is the temporal analysis path: commit metadata and file modifications are transformed into a graph structure for downstream reasoning.

6. A second subsystem performs AST-based code inspection. The `analyze_file_functions` tool parses Python source structurally rather than using regex, extracting function/class definitions and line boundaries. This is the file-structure path: raw source text becomes a precise syntax tree representation.

7. A third subsystem tracks file evolution over time. The `trace_evolution` capability follows a specific file across repository history, connecting a file’s current structure to prior commits and edits. This is the history path focused on one file rather than the whole repo.

8. `calculator.py` is important as a concrete fixture for these tools. The README explicitly uses it in validation, so it likely represents a simple arithmetic module whose functions can be verified by the AST scanner and tracked through evolution tooling.

9. `requirements.txt` defines the runtime dependencies that materially shape the architecture: MCP for protocol/server integration, GitPython for repository access, and NetworkX for graph modeling. These are the core technical anchors of the system.

10. The overall data flow is: Cline/LLM prompt → MCP request to `server.py` → local repo/git/AST processing → structured JSON results back to the client. The architecture is intentionally read-heavy and analysis-oriented, with no persistent database or remote service layer in the visible repo.

11. For a diagram, show three main local components: the LLM client, the MCP server process, and the on-disk git repository/code files. Then show the server branching into git-history analysis, AST parsing, and graph construction, with `calculator.py` as an example input file.

12. The key architectural constraint is privacy and locality: all inspection happens on the user’s machine against local repositories. That makes the server a secure analysis bridge rather than a general-purpose application backend.

Main entry points: [`server.py`](https://github.com/ayushd64/repomirror-mcp/blob/main/server.py) (Server entry), [`calculator.py`](https://github.com/ayushd64/repomirror-mcp/blob/main/calculator.py) (Calculator), [`requirements.txt`](https://github.com/ayushd64/repomirror-mcp/blob/main/requirements.txt) (Dependencies), [`README.md`](https://github.com/ayushd64/repomirror-mcp/blob/main/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_llm_client(("LLM client<br/>desktop client"))
  node_mcp_rpc{{"MCP RPC<br/>json-rpc transport"}}
  node_json_results["Structured output<br/>analysis results"]
end

subgraph group_server["Local server"]
  node_server_py["Server entry<br/>mcp entrypoint<br/>[server.py]"]
  node_tool_router["Tool router<br/>dispatch layer<br/>[server.py]"]
  node_ast_inspector["AST inspector<br/>source analyzer"]
  node_graph_builder["Graph builder<br/>networkx model"]
  node_evolution_tracer["Evolution tracer<br/>history tracer"]
  node_mcp_tools["Analysis tools<br/>mcp tools"]
end

subgraph group_repo["Repo data"]
  node_git_history[("Git history<br/>repo timeline")]
  node_repo_checkout[("Local checkout<br/>working tree")]
  node_calculator_py["Calculator<br/>example module<br/>[calculator.py]"]
  node_requirements_txt["Dependencies<br/>runtime deps<br/>[requirements.txt]"]
  node_readme_md["README<br/>usage docs<br/>[README.md]"]
end

node_llm_client -->|"sends request"| node_mcp_rpc
node_mcp_rpc -->|"delivers"| node_server_py
node_server_py -->|"dispatches"| node_tool_router
node_tool_router -->|"exposes"| node_mcp_tools
node_mcp_tools -->|"builds"| node_graph_builder
node_mcp_tools -->|"parses"| node_ast_inspector
node_mcp_tools -->|"traces"| node_evolution_tracer
node_graph_builder -->|"reads"| node_git_history
node_ast_inspector -->|"reads"| node_repo_checkout
node_evolution_tracer -->|"follows"| node_git_history
node_git_history -->|"sources"| node_repo_checkout
node_repo_checkout -->|"contains"| node_calculator_py
node_repo_checkout -->|"defines"| node_requirements_txt
node_repo_checkout -->|"documents"| node_readme_md
node_graph_builder -->|"returns"| node_json_results
node_ast_inspector -->|"returns"| node_json_results
node_evolution_tracer -->|"returns"| node_json_results
node_json_results -->|"feeds reasoning"| node_llm_client

click node_server_py "https://github.com/ayushd64/repomirror-mcp/blob/main/server.py"
click node_tool_router "https://github.com/ayushd64/repomirror-mcp/blob/main/server.py"
click node_calculator_py "https://github.com/ayushd64/repomirror-mcp/blob/main/calculator.py"
click node_requirements_txt "https://github.com/ayushd64/repomirror-mcp/blob/main/requirements.txt"
click node_readme_md "https://github.com/ayushd64/repomirror-mcp/blob/main/README.md"

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_llm_client,node_mcp_rpc,node_json_results toneBlue
class node_server_py,node_tool_router,node_ast_inspector,node_graph_builder,node_evolution_tracer,node_mcp_tools toneAmber
class node_git_history,node_repo_checkout,node_calculator_py,node_requirements_txt,node_readme_md toneMint
```

## Components

### Client

Local LLM client boundary

- **LLM client**: desktop client · VS Code or Cline sends MCP requests locally
- **MCP RPC**: json-rpc transport · Request/response protocol between client and server
- **Structured output**: analysis results · JSON returned to the client for downstream reasoning

### Local server

MCP analysis process

- [Server entry](https://github.com/ayushd64/repomirror-mcp/blob/main/server.py): mcp entrypoint · Registers tools and dispatches analysis requests · `server.py`
- [Tool router](https://github.com/ayushd64/repomirror-mcp/blob/main/server.py): dispatch layer · Routes MCP calls to analysis capabilities · `server.py`
- **AST inspector**: source analyzer · Parses Python files structurally for functions, classes, and spans
- **Graph builder**: networkx model · Builds a codebase graph from commits and file nodes
- **Evolution tracer**: history tracer · Follows one file across repository history and edits
- **Analysis tools**: mcp tools · Expose repository graphing, file inspection, and evolution tracing

### Repo data

On-disk repository and source files

- **Git history**: repo timeline · Reads commits, authors, and file changes from the local checkout
- **Local checkout**: working tree · On-disk repository used as the data source
- [Calculator](https://github.com/ayushd64/repomirror-mcp/blob/main/calculator.py): example module · Concrete Python file used for structural and evolution analysis · `calculator.py`
- [Dependencies](https://github.com/ayushd64/repomirror-mcp/blob/main/requirements.txt): runtime deps · Declares MCP, GitPython, and NetworkX dependencies · `requirements.txt`
- [README](https://github.com/ayushd64/repomirror-mcp/blob/main/README.md): usage docs · Describes tools, behavior, and example validation · `README.md`

## Connections

- LLM client → MCP RPC: sends request · User query becomes an MCP call
- MCP RPC → Server entry: delivers · JSON-RPC request reaches the local server
- Server entry → Tool router: dispatches · Entry point routes tool calls
- Tool router → Analysis tools: exposes · Registers the repository-analysis tools
- Analysis tools → Graph builder: builds · Whole-repo history is transformed into a graph
- Analysis tools → AST inspector: parses · Source files are inspected structurally
- Analysis tools → Evolution tracer: traces · Single-file history is followed through commits
- Graph builder → Git history: reads · Uses commit and change data from git
- AST inspector → Local checkout: reads · Parses local source files from disk
- Evolution tracer → Git history: follows · Walks history for a specific file
- Git history → Local checkout: sources · Repository checkout is the authoritative data source
- Local checkout → Calculator: contains · Example file used in analysis and validation
- Local checkout → Dependencies: defines · Runtime dependencies shape the local stack
- Local checkout → README: documents · README describes the architecture and tools
- Graph builder → Structured output: returns · Produces structured graph output
- AST inspector → Structured output: returns · Produces structured file-analysis output
- Evolution tracer → Structured output: returns · Produces history trace output
- Structured output → LLM client: feeds reasoning · Client receives structured analysis for the prompt