# Repo Architecture Mcp

> An MCP server that provides architecture insights by creating diagrams of class, service, and data-flow relationships across the codebase.

- **Type:** MCP server
- **Install:** `agentstack add mcp-vinit-devops-repo-architecture-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vinit-devops](https://agentstack.voostack.com/s/vinit-devops)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vinit-devops](https://github.com/vinit-devops)
- **Source:** https://github.com/vinit-devops/repo-architecture-mcp

## Install

```sh
agentstack add mcp-vinit-devops-repo-architecture-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://mermaid.live/) - Paste your Mermaid code directly
- [Mermaid Chart](https://www.mermaidchart.com/) - 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:
1. Install the **Mermaid Preview** extension in VS Code for live Mermaid diagram preview
2. Use the **Markdown Preview Mermaid Support** extension for enhanced markdown rendering
3. Keep a browser tab open to [Mermaid Live Editor](https://mermaid.live/) for quick diagram testing

## Installation

```bash
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:

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

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

## MCP Configuration

### Quick Setup

1. Copy the provided `mcp.json` to your MCP client configuration directory
2. Set your GitHub token: `export GITHUB_TOKEN=your_token_here`
3. 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

```bash
pytest
```

### Code Formatting

```bash
black src/ tests/
```

### Type Checking

```bash
mypy src/
```

## License

MIT License

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vinit-devops](https://github.com/vinit-devops)
- **Source:** [vinit-devops/repo-architecture-mcp](https://github.com/vinit-devops/repo-architecture-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-vinit-devops-repo-architecture-mcp
- Seller: https://agentstack.voostack.com/s/vinit-devops
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.