ai-architect-webapp

This MCP server provides an automated workflow for validating and integrating Azure components into architecture diagrams using the Model Context Protocol (MCP). It orchestrates a set of AI-assisted agents (design, validation, and diagram generation) to produce professional Azure architecture diagrams in multiple formats (PNG, SVG, PDF) while ensuring components adhere to the official diagrams library. You can leverage the validation engine to automatically correct import paths and component names, and you’ll receive smart suggestions for valid alternatives when components don’t align with MCP rules. The server is designed to work in conjunction with frontend tooling and cloud deployment pipelines, enabling rapid iteration from design prompts to validated diagrams.

To use the MCP server, start the service and interact with the MCP protocol endpoints exposed by the Python backend. Send prompts describing the desired Azure architecture, and the multi-agent system will interpret requirements, validate Azure components against the library, and render diagrams. The system integrates with Cosmos DB for storage and versioning, ensuring artifacts are persisted across runs, and it provides error handling and logging to help diagnose issues during generation or validation. If you’re deploying in a cloud environment, you can route requests through the MCP service container(s) and coordinate with the frontend to present diagrams and export options to end users.

Prerequisites

• Python 3.9+ installed on your machine or in your environment
• Git installed
• Docker (optional, for containerized deployments)
• Access to a Python package repository if you plan to install dependencies from a custom source

Step 1: Clone the repository

git clone https://github.com/passadis/ai-architect-webapp.git
cd ai-architect-webapp

Step 2: Set up a Python virtual environment

python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

Step 3: Install dependencies

pip install -r requirements.txt

Step 4: Configure environment variables (example)

export MCP_LAYER=validation
export COSMOS_ENDPOINT=https://your-cosmos.documents.azure.com
export COSMOS_DATABASE_NAME=ai-architect-db
export COSMOS_CONTAINER_NAME=architectures
export MODEL_NAME=gpt-4o
export PROJECT_ENDPOINT=https://your-ai-project.cognitiveservices.azure.com

Step 5: Run the MCP server

python -m mcp_server

Step 6: Optional – run in Docker

docker build -t ai-architect-mcp .
docker run -p 8000:8000 ai-architect-mcp

Step 7: Verify the server is running

curl http://localhost:8000/health

Notes and tips:

• The MCP server validates Azure components against the official diagrams library and can automatically correct common import path and naming issues. If a component is invalid, you’ll receive suggested alternatives.
• Ensure your Azure credentials and RBAC permissions are correctly configured in your deployment environment to allow creation and validation of resources.
• The Cosmos DB integration provides persistent storage and versioning for generated architectures. Make sure your Cosmos account is provisioned and accessible.
• When deploying in production, consider containerizing the MCP service and using a reverse proxy or API gateway to manage routing and security.
• If you encounter validation failures, enable verbose logging to capture agent prompts and validation decisions for easier debugging.