Archy - Architectural Diagram Builder

Archy is an MCP (Model Context Protocol) server that generates architectural diagrams using Mermaid syntax. It can process both natural language descriptions and GitHub repository URLs to create various types of diagrams.

Features

• Generate diagrams from text descriptions
• Generate diagrams from GitHub repositories
• Support for all Mermaid diagram types:
• Flowcharts
• Sequence Diagrams
• Class Diagrams
• State Diagrams
• Entity Relationship Diagrams
• User Journeys
• Gantt Charts
• Pie Charts
• Quadrant Charts
• Requirement Diagrams
• Git Graphs
• C4 Diagrams

Installation

Prerequisites

• Node.js (v16 or higher)
• npm (v7 or higher)
• TypeScript (v5.8 or higher, included in dependencies)

Install from Source

1. Clone the repository:

git clone https://github.com/phxdev1/archy.git
   cd archy

2. Install dependencies:

npm install

3. Build the project:

npm run build

This compiles the TypeScript source files to JavaScript in the build directory.

Automated MCP Installation

Archy includes a convenient installation script that automatically configures the MCP server for both VS Code and Claude:

npm run install-mcp

This script:

• Automatically detects the correct MCP settings locations for your operating system
• Updates the MCP configuration files for VS Code and Claude
• Prompts for a GitHub token for repository analysis (optional)
• Makes the server executable

No need to manually edit JSON configuration files like some kind of cave-dwelling animal! The script handles all the tedious configuration work for you, so you can focus on creating beautiful diagrams instead of wrestling with file paths and permissions.

Configuration

Configuration

Archy can be configured using environment variables:

• GITHUB_TOKEN: GitHub API token for authenticated requests (optional)
• OPENROUTER_API_KEY: OpenRouter API key for AI-powered diagram generation (optional)

OpenRouter Integration

Archy includes integration with OpenRouter through LangChain, enabling enhanced AI-powered diagram generation. When an OpenRouter API key is configured, additional tools become available:

• AI-Enhanced Text-to-Diagram Generation: Generate more sophisticated diagrams from text descriptions
• Code-to-Diagram Generation: Analyze code and generate appropriate diagrams
• Diff Visualization: Generate diagrams showing differences between code versions

To use these features:

1. Sign up for an account at OpenRouter

2. Get your API key from the OpenRouter dashboard

3. Set the OPENROUTER_API_KEY environment variable before running Archy

Image Export

Archy supports exporting Mermaid diagrams to various image formats:

• PNG: Raster image format suitable for web and documentation
• SVG: Vector image format that scales without losing quality
• PDF: Document format suitable for printing and sharing

Images can be exported with customizable dimensions and background colors.

Repository Evolution Tracking

Archy can analyze Git repositories to track their evolution over time:

• In-Memory Git: Clone and analyze repositories without writing to the file system
• Commit History: Track changes across multiple commits (limited to 10 by default)
• File Evolution: Track how specific files change over time
• Evolution Visualization: Generate diagrams showing the repository's evolution

MCP Integration

To use Archy with an MCP client, add it to your MCP settings file if you're a masochist:

{
  "mcpServers": {
    "archy": {
      "command": "node",
      "args": ["/path/to/archy/build/index.js"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

Available Tools

generate_diagram_from_text

Generates a Mermaid diagram from a text description.

Parameters:

• description: Text description of the diagram to generate
• diagramType: Type of diagram to generate (e.g., 'flowchart', 'classDiagram', etc.)

Example:

{
  "description": "A user authentication system with login, registration, and password reset",
  "diagramType": "flowchart"
}

generate_diagram_from_github

Generates a Mermaid diagram from a GitHub repository.

Parameters:

• repoUrl: URL of the GitHub repository
• diagramType: Type of diagram to generate (e.g., 'classDiagram', 'sequenceDiagram', etc.)

Example:

{
  "repoUrl": "https://github.com/username/repository",
  "diagramType": "classDiagram"
}

list_supported_diagram_types

Lists all supported diagram types with descriptions.

Parameters: None

AI-Powered Tools

The following tools are available when an OpenRouter API key is configured:

generate_diagram_from_text_with_ai

Generates a Mermaid diagram from a text description using AI (LangChain with OpenRouter).

Parameters:

• description: Text description of the diagram to generate
• diagramType: Type of diagram to generate (e.g., 'flowchart', 'classDiagram', etc.)
• useAdvancedModel: (Optional) Whether to use a more advanced AI model for complex diagrams

Example:

{
  "description": "A microservice architecture with user service, product service, and order service communicating through a message queue",
  "diagramType": "flowchart",
  "useAdvancedModel": true
}

generate_diagram_from_code

Generates a Mermaid diagram from code using AI.

Parameters:

• code: The code to analyze and generate a diagram from
• diagramType: Type of diagram to generate (e.g., 'classDiagram', 'flowchart', etc.)

Example:

{
  "code": "class User { ... } class AuthService { ... }",
  "diagramType": "classDiagram"
}

generate_diff_diagram

Generates a Mermaid diagram showing differences between two versions of code.

Parameters:

• beforeCode: The code before changes
• afterCode: The code after changes
• diagramType: Type of diagram to generate (e.g., 'classDiagram', 'flowchart', etc.)

Example:

{
  "beforeCode": "class User { ... }",
  "afterCode": "class User { ... additional methods ... }",
  "diagramType": "classDiagram"
}

export_diagram_to_image

Exports a Mermaid diagram to an image format (PNG, SVG, or PDF).

Parameters:

• mermaidCode: The Mermaid diagram code to export
• format: (Optional) The image format to export to ('png', 'svg', 'pdf', default: 'png')
• width: (Optional) The width of the image in pixels (default: 800)
• height: (Optional) The height of the image in pixels (default: 600)
• backgroundColor: (Optional) The background color of the image (CSS color or "transparent", default: '#ffffff')

Example:

{
  "mermaidCode": "flowchart TD\n  A[Start] --> B[End]",
  "format": "svg",
  "width": 1200,
  "height": 800,
  "backgroundColor": "#f0f0f0"
}

generate_repository_evolution_diagram

Generates a diagram showing the evolution of a repository over time.

Parameters:

• repoUrl: URL of the GitHub repository
• diagramType: Type of diagram to generate (e.g., 'gitGraph', 'flowchart', etc.)
• filepath: (Optional) Path to a specific file to track
• commitLimit: (Optional) Maximum number of commits to analyze (default: 10)

Example:

{
  "repoUrl": "https://github.com/username/repository",
  "diagramType": "gitGraph",
  "filepath": "src/main.js",
  "commitLimit": 5
}

Examples

Generating a Class Diagram from Text

generate_diagram_from_text({
  "description": "Create a class diagram for a library system with Book, Author, and Library classes. Books have titles and ISBNs. Authors have names and can write multiple books. Libraries contain many books.",
  "diagramType": "classDiagram"
})

Result:

classDiagram
  class Book {
    +String title
    +String ISBN
    +getDetails()
  }
  class Author {
    +String name
    +List books
    +addBook(Book)
  }
  class Library {
    +List books
    +addBook(Book)
    +findBookByISBN(String)
  }
  Author "1" -- "n" Book: writes
  Library "1" -- "n" Book: contains

Generating a Flowchart from GitHub

generate_diagram_from_github({
  "repoUrl": "https://github.com/username/api-service",
  "diagramType": "flowchart"
})

Result:

flowchart TD
  A[Client] --> B[API Gateway]
  B --> C{Authentication}
  C -->|Valid| D[Route Request]
  C -->|Invalid| E[Return 401]
  D --> F[Service 1]
  D --> G[Service 2]
  D --> H[Service 3]
  F --> I[Database]
  G --> I
  H --> I

Development

Running in Development Mode

To run the server in development mode with automatic reloading:

npm run dev

This uses nodemon and ts-node to run the TypeScript code directly without a separate build step, automatically restarting when files change.

Running the TypeScript Compiler

You can run the TypeScript compiler directly using the following methods:

Using the locally installed TypeScript

# Using npx to run the local TypeScript installation
npx tsc

# Compile with specific tsconfig file
npx tsc --project tsconfig.json

# Watch mode - automatically recompile when files change
npx tsc --watch

# Compile specific files
npx tsc src/index.ts src/server.ts

Using globally installed TypeScript

If you have TypeScript installed globally:

# Install TypeScript globally (if not already installed)
npm install -g typescript

# Run the TypeScript compiler
tsc

# Compile with specific tsconfig file
tsc --project tsconfig.json

# Watch mode
tsc --watch

Common TypeScript Compiler Options

• --outDir : Specify output directory for compiled files
• --target : Specify ECMAScript target version (e.g., ES2020)
• --module : Specify module system (e.g., NodeNext)
• --declaration: Generate .d.ts declaration files
• --sourceMap: Generate source map files for debugging
• --strict: Enable all strict type checking options
• --noEmit: Check for errors without generating output files
• --noImplicitAny: Raise error on expressions with implied 'any' type

For a complete list of compiler options, run npx tsc --help or refer to the TypeScript documentation.

TypeScript Configuration

Archy is built with TypeScript using the following configuration:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "build",
    "declaration": true,
    "sourceMap": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "build"]
}

Key TypeScript features used:

• ES2020 target for modern JavaScript features
• NodeNext module resolution for compatibility with Node.js
• Declaration files generation for better type support
• Source maps for easier debugging

Project Structure

• src/: TypeScript source files
• src/index.ts: Main entry point and server implementation
• src/server.ts: Server implementation
• src/generators/: Diagram generation logic
• src/utils/: Utility functions and helpers
• build/: Compiled JavaScript output
• examples/: Example usage scripts
• test/: Test files