Architecture Review Agent
The Architecture Review Agent is an open-source AI agent sample that reviews software architectures and generates interactive diagrams automatically.
What is Architecture Review Agent?
Architecture Review Agent is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to architecture review agent is an open-source ai agent sample that reviews software architectures and generates interactive diagrams automatically.
The Architecture Review Agent is an open-source AI agent sample that reviews software architectures and generates interactive diagrams automatically.
This server falls under the Coding Agents category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- The Architecture Review Agent is an open-source AI agent sam
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx agent-architecture-review-sampleConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Architecture Review Agent
The Architecture Review Agent is an open-source Azure AI sample that automatically reviews software architecture documents and generates interactive diagrams. Given a YAML, Markdown, or plaintext description of a system, it parses components and connections, performs risk detection, maps relationships, and produces an Excalidraw diagram along with a structured review report. It demonstrates how to combine Azure OpenAI with the Model Context Protocol and draw.io or Excalidraw MCP tools for agentic diagram generation.
Prerequisites
- Python 3.11 or later and pip installed
- An Azure subscription with Azure OpenAI service enabled and a deployed model (e.g., gpt-4.1)
- Azure OpenAI API key and endpoint URL
- Microsoft Azure AI Foundry project endpoint (PROJECT_ENDPOINT)
- Git installed for cloning the repository
Clone the repository
Clone the Azure Samples repository to your local machine.
git clone https://github.com/Azure-Samples/agent-architecture-review-sample
cd agent-architecture-review-sampleRun the setup script
Use the platform-specific setup script to create a virtual environment and install dependencies automatically.
# macOS/Linux
bash scripts/linux-mac/setup.sh
# Windows PowerShell
.\scripts\windows\setup.ps1Configure environment variables
Copy the environment template and fill in your Azure OpenAI credentials and Foundry project endpoint.
cp .env.template .env
# Edit .env and set:
# PROJECT_ENDPOINT=https://your-project.services.ai.azure.com
# AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
# AZURE_OPENAI_API_KEY=your_api_key
# MODEL_DEPLOYMENT_NAME=gpt-4.1Activate the virtual environment
Activate the Python virtual environment created by the setup script before running the agent.
# macOS/Linux
source .venv/bin/activate
# Windows
.\.venv\Scripts\Activate.ps1Review an architecture file
Run the agent on a YAML or Markdown architecture description. The agent produces architecture.excalidraw, architecture.png, and review_bundle.json in the output/ directory.
python run_local.py scenarios/ecommerce.yamlReview plaintext or force LLM inference
For unstructured text descriptions or to force LLM-based component extraction instead of rule-based parsing, use the --text or --infer flags.
# Plaintext architecture description
python run_local.py --text "Load Balancer -> Web Server -> PostgreSQL DB"
# Force LLM inference on any file
python run_local.py design_doc.txt --inferArchitecture Review Agent Examples
Client configuration
Environment variable configuration needed to run the Architecture Review Agent with Azure OpenAI.
{
"PROJECT_ENDPOINT": "https://your-project.services.ai.azure.com",
"AZURE_OPENAI_ENDPOINT": "https://your-resource.openai.azure.com/",
"AZURE_OPENAI_API_KEY": "your_azure_openai_api_key",
"MODEL_DEPLOYMENT_NAME": "gpt-4.1"
}Prompts to try
Example commands and descriptions you can pass to the Architecture Review Agent.
- Run: python run_local.py scenarios/ecommerce.yaml
- Run: python run_local.py --text "API Gateway -> Auth Service -> User DB"
- Run: python run_local.py design_doc.md --infer --render
- In an MCP session: "Review the architecture described in scenarios/microservices.yaml and identify single points of failure."
- In an MCP session: "Generate an Excalidraw diagram from this architecture: CDN -> Load Balancer -> App Cluster -> Redis Cache -> PostgreSQL"Troubleshooting Architecture Review Agent
Azure OpenAI returns 401 Unauthorized
Verify that AZURE_OPENAI_API_KEY matches the key shown in your Azure OpenAI resource under Keys and Endpoint, and that AZURE_OPENAI_ENDPOINT ends with a trailing slash.
SSL verification errors when behind a corporate proxy
Set ARCH_REVIEW_NO_SSL_VERIFY=1 in your .env file to disable SSL certificate verification. Do not use this in production environments.
output/ directory contains no diagram after running run_local.py
Check the terminal for parsing errors. If the architecture file uses a format the rule-based parser does not recognize, add the --infer flag to fall back to LLM-based extraction.
Frequently Asked Questions about Architecture Review Agent
What is Architecture Review Agent?
Architecture Review Agent is a Model Context Protocol (MCP) server that architecture review agent is an open-source ai agent sample that reviews software architectures and generates interactive diagrams automatically. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Architecture Review Agent?
Follow the installation instructions on the Architecture Review Agent GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Architecture Review Agent?
Architecture Review Agent works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Architecture Review Agent free to use?
Yes, Architecture Review Agent is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
Architecture Review Agent Alternatives — Similar Coding Agents Servers
Looking for alternatives to Architecture Review Agent? Here are other popular coding agents servers you can use with Claude, Cursor, and VS Code.
Dify
★ 142.2kProduction-ready platform for agentic workflow development.
Ruflo
★ 54.0k🌊 The leading agent orchestration platform for Claude. Deploy intelligent multi-agent swarms, coordinate autonomous workflows, and build conversational AI systems. Features enterprise-grade architecture, self-learning swarm intelligence, RAG integrat
Goose
★ 45.7kan open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM
Antigravity Awesome Skills
★ 38.3kInstallable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.
AgentScope
★ 25.5kBuild and run agents you can see, understand and trust.
Serena
★ 24.5kA coding agent toolkit that provides IDE-like semantic code retrieval and editing tools, enabling LLMs to efficiently navigate and modify codebases using symbol-level operations instead of basic file reading and string replacements.
Browse More Coding Agents MCP Servers
Explore all coding agents servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Architecture Review Agent in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Architecture Review Agent?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.