Repository Architecture MCP Server

An MCP (Model Context Protocol) server that analyzes GitHub repositories and automatically generates visual architectural diagrams including dependency graphs, class diagrams, and data flow diagrams.

Features

Repository Analysis: Analyze both GitHub repositories (public/private) and local repositories
Multi-language Support: Parse Python, JavaScript, TypeScript, Java, and Go codebases
Dependency Diagrams: Visualize module dependencies and service interconnections
Class Diagrams: Generate UML class diagrams with inheritance relationships
Data Flow Diagrams: Show how data moves through the system
Multiple Export Formats: Support for Mermaid, SVG, and PNG outputs
Local Analysis: No GitHub token required for local repository analysis

Diagram Preview Tools

To preview the generated diagrams, you'll need appropriate tools or extensions depending on the output format:

Mermaid Diagrams

Mermaid diagrams can be previewed using:

VS Code Extensions:

Mermaid Preview by vstirbu: Install via VS Code Extensions marketplace
Search for "Mermaid Preview" in VS Code Extensions (Ctrl+Shift+X)
Click Install
Open any .md file containing Mermaid code blocks and use the preview pane

Markdown Preview Mermaid Support by Matt Bierner: Enhanced markdown preview with Mermaid support
Search for "Markdown Preview Mermaid Support" in VS Code Extensions
Provides live preview of Mermaid diagrams in markdown files

Online Tools:

Mermaid Live Editor - Paste your Mermaid code directly
Mermaid Chart - Professional diagramming tool

Browser Extensions:

Mermaid Diagrams for Chrome/Firefox - Renders Mermaid in GitHub and other platforms

SVG Diagrams

SVG files can be viewed in:

Any modern web browser (Chrome, Firefox, Safari, Edge)
VS Code with SVG preview extensions
Image viewers that support SVG format

PNG Diagrams

PNG files can be viewed in:

Any image viewer or web browser
VS Code with image preview extensions
Built-in system image viewers

Recommended Setup

For the best experience, we recommend:

Install the Mermaid Preview extension in VS Code for live Mermaid diagram preview
Use the Markdown Preview Mermaid Support extension for enhanced markdown rendering
Keep a browser tab open to Mermaid Live Editor for quick diagram testing

Installation

pip install -e .

For development: ``bash pip install -e ".[dev]" ``

Verify Installation

Test that the server is working: ```bash

Check command is available

repo-architecture-mcp --help

Test server startup (Ctrl+C to stop)

repo-architecture-mcp --log-level DEBUG ```

Usage

As MCP Server

Run the server with stdio transport: ``bash repo-architecture-mcp ``

With debug logging: ``bash repo-architecture-mcp --log-level DEBUG ``

Available MCP Tools

All tools work with both GitHub URLs and local repository paths:

analyze_repository: Analyze repository structure (GitHub URL or local path)
generate_dependency_diagram: Create dependency visualization
generate_class_diagram: Create class relationship diagram
generate_data_flow_diagram: Create data flow visualization
get_repository_summary: Get high-level repository statistics

Local Path Examples:

Current directory: "url": "."
Relative path: "url": "./my-project"
Absolute path: "url": "/home/user/project"
Home directory: "url": "~/projects/app"

File Saving Feature: All diagram generation tools now support automatic file saving:

save_to_file: Set to true to save diagrams to files
output_path: Optional custom file path (auto-generates if not provided)

Example with file saving: ``json { "tool": "generate_dependency_diagram", "arguments": { "url": ".", "format": "mermaid", "save_to_file": true, "output_path": "./diagrams/dependencies.mmd" } } ``

Diagram Quality Improvements:

✅ Proper Mermaid syntax: All generated diagrams use valid Mermaid syntax
✅ Markdown code blocks: Diagrams are wrapped in proper markdown code blocks for better display
✅ Character sanitization: Special characters in node names are properly handled
✅ Clean display names: Node labels are cleaned for better readability
✅ Edge limiting: Automatically limits edges to prevent Mermaid rendering issues (default: 400 edges)
✅ Smart prioritization: Most important relationships are preserved when limiting edges

Local Repository Analysis

For local repositories, you don't need a GitHub token:

# Analyze current directory
repo-architecture-mcp --analyze-local .

# Analyze specific local path  
repo-architecture-mcp --analyze-local /path/to/project

MCP Configuration

Quick Setup

Copy the provided mcp.json to your MCP client configuration directory
Set your GitHub token: export GITHUB_TOKEN=your_token_here
Add the server to your MCP client

Basic MCP Configuration

For GitHub repositories: ``json { "mcpServers": { "repo-architecture": { "command": "repo-architecture-mcp", "args": ["--log-level", "INFO"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }, "disabled": false, "autoApprove": ["analyze_repository"] } } } ``

For local repositories (no token needed): ``json { "mcpServers": { "repo-architecture-local": { "command": "repo-architecture-mcp", "args": ["--log-level", "INFO"], "cwd": "${workspaceFolder}", "disabled": false, "autoApprove": [ "analyze_repository", "generate_dependency_diagram" ] } } } ``

For Cursor IDE

Workspace Configuration for Local Analysis (.cursor/settings/mcp.json): ``json { "mcpServers": { "repo-architecture-local": { "command": "repo-architecture-mcp", "cwd": "${workspaceFolder}", "disabled": false, "autoApprove": [ "analyze_repository", "generate_dependency_diagram" ] } } } ``

User Configuration for GitHub (~/.cursor/settings/mcp.json): ``json { "mcpServers": { "repo-architecture": { "command": "repo-architecture-mcp", "args": ["--max-workers", "4"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }, "disabled": false, "autoApprove": ["analyze_repository"] } } } ``

For GitHub Copilot Chat

This MCP server integrates seamlessly with GitHub Copilot Chat to provide architectural insights directly in your development workflow. Use the available tools through Copilot's chat interface to analyze repositories and generate diagrams.

Available Tools

analyze_repository: Analyze repository structure and code
generate_dependency_diagram: Create dependency visualizations
generate_class_diagram: Generate UML class diagrams
generate_data_flow_diagram: Create data flow diagrams
get_repository_summary: Get repository statistics

Configuration Options

The server accepts these command-line arguments:

--config PATH: Custom configuration file
--log-level LEVEL: Set logging level (DEBUG, INFO, WARNING, ERROR)
--github-token TOKEN: GitHub authentication token
--max-workers N: Number of parallel workers (default: 4)
--memory-limit MB: Memory limit in megabytes (default: 2048)
--cache-ttl HOURS: Cache time-to-live (default: 24)
--output-format FORMAT: Default output format (mermaid, svg, png)

Environment Variables

GITHUB_TOKEN: GitHub personal access token
LOG_LEVEL: Logging level
REPO_ARCH_CONFIG: Path to configuration file

See examples/mcp-config-examples.md for more detailed configuration examples and examples/local-repo-config.md for local repository setup.

Development

Project Structure

src/repo_architecture_mcp/
├── __init__.py          # Package initialization
├── main.py              # Main entry point
└── server.py            # Core MCP server implementation

Running Tests

pytest

Code Formatting

black src/ tests/

Type Checking

mypy src/

License

MIT License

Repository Architecture MCP Server