ayushd64/repomirror-mcp

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.