aws-diagrams-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Development Setup

# Install development dependencies
uv pip install -e ".[dev]"

# Install Python 3.10+ using uv
uv python install 3.10

Testing

# Run all tests with verbose output
pytest -xvs tests/

# Run specific test file
pytest -xvs tests/test_models.py

# Run with coverage report
pytest --cov=aws_diagram_mcp_server --cov-report=term-missing tests/

# Run specific test class or method
pytest -xvs tests/test_models.py::TestDiagramType
pytest -xvs tests/test_models.py::TestDiagramType::test_diagram_type_values

Code Quality

# Run linter (configured in pyproject.toml)
ruff check .
ruff format .

# Run type checker
pyright

# Run security scanner
bandit -c pyproject.toml -r aws_diagram_mcp_server/

Building

# Build Docker image
docker build -t aws-diagram-mcp-server .

# Run Docker container
docker run --rm --interactive --env FASTMCP_LOG_LEVEL=ERROR aws-diagram-mcp-server:latest

Architecture

This is an MCP (Model Context Protocol) server that generates diagrams using the Python diagrams package. The server architecture follows:

Core Components

1. MCP Server (server.py): FastMCP-based server exposing four main tools:

   • generate_diagram: Creates PNG diagrams from Python code
   • generate_diagram_dot: Creates Graphviz DOT files from Python code
   • list_diagram_icons: Lists available diagram icons organized by provider
   • get_diagram_examples: Provides example code for different diagram types

2. Security Scanner (scanner.py):

   • Uses Bandit to scan diagram code for security issues before execution
   • Validates that only safe diagram-related imports are used
   • Prevents execution of potentially dangerous code

3. Diagram Tools (diagrams_tools.py):

   • Handles actual diagram generation using the diagrams package
   • Manages workspace directory for generated diagrams
   • Provides icon discovery and example generation