aws_diagrams_mcp_server by cwcala - MCP Server

AWS Architecture Diagram Generator

A powerful tool that generates AWS architecture diagrams from natural language descriptions or JSON specifications. This project includes both a web interface and an MCP (Model Context Protocol) server integration for Amazon Q.

Overview

The AWS Architecture Diagram Generator allows you to:

Generate AWS architecture diagrams from natural language descriptions
Convert infrastructure code (Terraform, CloudFormation, CDK, SAM) to diagrams
Directly input JSON specifications for diagram generation
Use the tool through a web interface or as an MCP server with Amazon Q CLI

File Structure

/
├── integrated_server.py       # Main web server implementation
├── aws_diagram_mcp_server.py  # MCP server implementation for AWS diagrams
├── aws_diagram_mcp_config.json # Configuration for the MCP server
├── run_mcp_server.py          # Helper utilities for MCP server
├── run_diagram_mcp_server.sh  # Script to start the MCP server
├── setup_diagram_mcp.sh       # Script to set up the MCP server environment
├── templates/                 # HTML templates for web interface
│   ├── index_with_nl.html     # Main interface with natural language support
│   └── ...
├── static/                    # Static assets and generated diagrams
│   ├── css/                   # Stylesheets
│   ├── js/                    # JavaScript files
│   └── diagrams/              # Generated diagram output
├── .env.example               # Example environment variables
├── requirements.txt           # Python dependencies for web server
└── requirements_mcp.txt       # Python dependencies for MCP server

Key Files

integrated_server.py: FastAPI web server that provides the browser interface for generating diagrams
aws_diagram_mcp_server.py: MCP server implementation that integrates with Amazon Q CLI
run_mcp_server.py: Contains the core logic to convert JSON specifications to diagram code
aws_diagram_mcp_config.json: Configuration for the MCP server
run_diagram_mcp_server.sh: Script to start the MCP server
setup_diagram_mcp.sh: Script to set up the MCP server environment
.env.example: Template for environment variables

Setup Instructions

Prerequisites

Python 3.8+ installed

Graphviz installed (required by the diagrams package)

# For macOS
brew install graphviz

# For Ubuntu/Debian
apt-get install graphviz

# For Windows
# Download and install from https://graphviz.org/download/

Amazon Q CLI installed (for CLI usage)
AWS account with Bedrock access (optional, falls back to mock implementation)

Setting Up the MCP Server for Amazon Q CLI

Clone the repository:

git clone https://github.com/yourusername/aws-diagram-generator.git
cd aws-diagram-generator

Create a dedicated virtual environment for the MCP server:

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

Install the required dependencies:
```
pip install -r requirements_mcp.txt
```

Configure environment variables:

cp .env.example .env
# Edit .env with your AWS credentials and settings

Configure Amazon Q to use the MCP server:

Create or edit the file ~/.aws/amazonq/mcp.json to include:

{
  "mcpServers": {
    "awslabs.aws-diagram-mcp-server": {
      "command": "awslabs.aws-diagram-mcp-server",
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Replace "your-aws-profile" with your actual AWS profile name

Start the MCP server:
```
./run_diagram_mcp_server.sh
```
Alternatively, you can use the setup script which will create the virtual environment and install dependencies:
```
./setup_diagram_mcp.sh
```

Setting Up the Web Interface

Create a separate virtual environment for the web server:

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

Install the required dependencies:
```
pip install -r requirements.txt
```

Configure environment variables:

cp .env.example .env
# Edit .env with your AWS credentials and settings

Start the web server:
```
python integrated_server.py
```
The server will start on http://127.0.0.1:8765. Open this URL in your browser to access the web interface.

Usage

Using with Amazon Q CLI

Once the MCP server is running, you can use it with Amazon Q CLI:

Open a new terminal window
Start Amazon Q CLI:
```
q chat
```

Ask Amazon Q to generate an AWS architecture diagram:

Generate an AWS architecture diagram for a serverless web application with API Gateway, Lambda, and DynamoDB

Create a diagram for a three-tier web application on AWS

Amazon Q will use the MCP server to generate the diagram and display the path to the generated image file.

Using the Web Interface

Open your browser and go to http://127.0.0.1:8765
Choose between Natural Language or JSON input
Enter your description or JSON specification
Click "Generate Diagram"
View the generated diagram and JSON

Example Prompts for Amazon Q CLI

Try these examples with Amazon Q CLI:

"Generate an AWS architecture diagram for a serverless web application with API Gateway, Lambda functions, and DynamoDB for storage. Users authenticate with Cognito and static content is served from S3 through CloudFront."
"Create an AWS diagram for a data processing pipeline that uses S3 for storage, Lambda for processing, and stores results in DynamoDB."
"Make an architecture diagram for a mobile backend with API Gateway, Lambda, DynamoDB, and Cognito for user authentication."
"Generate a diagram from this Terraform code: [paste your Terraform code]"

JSON Specification Format

The JSON format for diagram specifications:

{
  "title": "Diagram Title",
  "services": [
    {
      "id": "api_gateway",
      "type": "apigateway",
      "name": "API Gateway"
    },
    {
      "id": "lambda_function",
      "type": "lambda",
      "name": "Lambda Function"
    }
  ],
  "connections": [
    {
      "from": "api_gateway",
      "to": "lambda_function"
    }
  ]
}

Preparing for GitHub Upload

To prepare this project for GitHub upload:

Ensure sensitive information is not included:
- Remove any AWS credentials from configuration files
- Make sure .env is in .gitignore
- Check for any hardcoded secrets or API keys

Create a .gitignore file if not already present:

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
env/
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
*.egg-info/
.installed.cfg
*.egg

# Virtual Environments
venv/
diagram_venv/
ENV/

# Environment variables
.env

# IDE files
.idea/
.vscode/
*.swp
*.swo

# OS specific
.DS_Store
Thumbs.db

Create a zip file of the project:

zip -r aws-diagram-generator.zip . -x "*.DS_Store" "*.git/*" "venv/*" "diagram_venv/*" "*.zip"

Upload to GitHub:

# Initialize a new repository
git init

# Add all files
git add .

# Commit
git commit -m "Initial commit of AWS Architecture Diagram Generator"

# Add remote repository
git remote add origin https://github.com/yourusername/aws-diagram-generator.git

# Push to GitHub
git push -u origin main

Troubleshooting

MCP Server Issues

MCP Server Not Found:
- Ensure the MCP server is running
- Check that the MCP configuration in ~/.aws/amazonq/mcp.json is correct
- Verify that the virtual environment is activated
Permission Issues:
- Make sure the script files are executable:
```
chmod +x run_diagram_mcp_server.sh setup_diagram_mcp.sh
```
AWS Credentials:
- Verify your AWS credentials are correctly configured
- Check that the AWS profile specified in the MCP configuration exists

Web Server Issues

Port Conflicts:
- If port 8765 is already in use, modify the port in integrated_server.py
Missing Dependencies:
- Ensure all dependencies are installed:
```
pip install -r requirements.txt
```
Graphviz Not Found:
- Verify Graphviz is installed and in your PATH

cwcala/aws_diagrams_mcp_server