Integrations
Provides in-memory Git functionality to clone and analyze repositories, track changes across multiple commits, and visualize repository evolution without writing to the file system.
Enables diagram generation from GitHub repositories, analyzing repository structure and code to create architectural visualizations. Supports repository evolution tracking and commit history analysis for creating diagrams showing changes over time.
Integrates with LangChain for AI-powered diagram generation, enabling enhanced text-to-diagram generation, code-to-diagram conversion, and visualization of differences between code versions.
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
- Clone the repository:Copy
- Install dependencies:Copy
- Build the project:This compiles the TypeScript source files to JavaScript in theCopy
build
directory.
Automated MCP Installation
Archy includes a convenient installation script that automatically configures the MCP server for both VS Code and Claude:
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:
- Sign up for an account at OpenRouter
- Get your API key from the OpenRouter dashboard
- 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:
Available Tools
generate_diagram_from_text
Generates a Mermaid diagram from a text description.
Parameters:
description
: Text description of the diagram to generatediagramType
: Type of diagram to generate (e.g., 'flowchart', 'classDiagram', etc.)
Example:
generate_diagram_from_github
Generates a Mermaid diagram from a GitHub repository.
Parameters:
repoUrl
: URL of the GitHub repositorydiagramType
: Type of diagram to generate (e.g., 'classDiagram', 'sequenceDiagram', etc.)
Example:
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 generatediagramType
: Type of diagram to generate (e.g., 'flowchart', 'classDiagram', etc.)useAdvancedModel
: (Optional) Whether to use a more advanced AI model for complex diagrams
Example:
generate_diagram_from_code
Generates a Mermaid diagram from code using AI.
Parameters:
code
: The code to analyze and generate a diagram fromdiagramType
: Type of diagram to generate (e.g., 'classDiagram', 'flowchart', etc.)
Example:
generate_diff_diagram
Generates a Mermaid diagram showing differences between two versions of code.
Parameters:
beforeCode
: The code before changesafterCode
: The code after changesdiagramType
: Type of diagram to generate (e.g., 'classDiagram', 'flowchart', etc.)
Example:
export_diagram_to_image
Exports a Mermaid diagram to an image format (PNG, SVG, or PDF).
Parameters:
mermaidCode
: The Mermaid diagram code to exportformat
: (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:
generate_repository_evolution_diagram
Generates a diagram showing the evolution of a repository over time.
Parameters:
repoUrl
: URL of the GitHub repositorydiagramType
: Type of diagram to generate (e.g., 'gitGraph', 'flowchart', etc.)filepath
: (Optional) Path to a specific file to trackcommitLimit
: (Optional) Maximum number of commits to analyze (default: 10)
Example:
Examples
Generating a Class Diagram from Text
Result:
Generating a Flowchart from GitHub
Result:
Development
Running in Development Mode
To run the server in development mode with automatic reloading:
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 globally installed TypeScript
If you have TypeScript installed globally:
Common TypeScript Compiler Options
--outDir <directory>
: Specify output directory for compiled files--target <ES version>
: Specify ECMAScript target version (e.g., ES2020)--module <module system>
: 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:
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 filessrc/index.ts
: Main entry point and server implementationsrc/server.ts
: Server implementationsrc/generators/
: Diagram generation logicsrc/utils/
: Utility functions and helpers
build/
: Compiled JavaScript outputexamples/
: Example usage scriptstest/
: Test files
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
archy
Related MCP Servers
- -securityAlicense-qualityEnables AI assistants to interact with Obsidian vaults, providing tools for reading, creating, editing and managing notes and tags.Last updated -598149TypeScriptMIT License
- -securityAlicense-qualityProvides a standardized interface for AI assistants to interact with Obsidian vaults through a local REST API, enabling reading, writing, searching, and managing notes.Last updated -37TypeScriptMIT License
- MIT License
- PythonMIT License