diagrams-mcp-server: Instructions file for Codex

AGENTS.md — Azure Diagram MCP Server

Comprehensive onboarding guide for AI agents and human contributors working on this repository.

Project Overview

Azure Diagram MCP Server is a Python Model Context Protocol (MCP) server that generates professional infrastructure and architecture diagrams using the diagrams package DSL. It has first-class Azure support and integrates with the GitHub Copilot SDK for natural language diagram generation.

Key capability: A user describes a diagram via the GitHub Copilot CLI or VS Code Copilot → the MCP server generates Python diagram code → executes it → returns a PNG image rendered in the MCP Apps viewer.

Repository Structure

diagrams-mcp-server/
├── microsoft/                         # Main source package
│   └── azure_diagram_mcp_server/
│       ├── __init__.py                # Package init, version string
│       ├── server.py                  # FastMCP server — tool registration + entry point
│       ├── diagram_tools.py           # Core logic — diagram generation, examples, icon listing
│       ├── models.py                  # Pydantic models — request/response schemas, DiagramType enum
│       ├── scanner.py                 # Security scanner — AST analysis + Bandit integration
│       ├── copilot_client.py          # Copilot SDK client — natural language diagram interface
│       └── viewer/
│           └── app.html               # MCP Apps interactive diagram viewer (HTML/CSS/JS)
├── tests/
│   ├── conftest.py                    # Pytest fixtures — temp dirs, example code, dangerous code
│   ├── test_server.py                 # Server tool function tests (15 tests)
│   ├── test_diagram_tools.py          # Diagram generation + example tests (28 tests)
│   ├── test_models.py                 # Pydantic model validation tests (12 tests)
│   ├── test_scanner.py                # Security scanner tests (58 tests)
│   ├── test_copilot_client.py         # Copilot SDK client tests (37 tests)
│   └── resources/example_diagrams/    # Runnable example diagram scripts
├── docs-site/                         # VitePress documentation site
│   ├── .vitepress/config.ts           # Site config — nav, sidebar, theme
│   ├── index.md                       # Home page with hero + features
│   ├── guide/
│   │   ├── getting-started.md         # Quick start
│   │   ├── installation.md            # Install methods (uv, pip, Docker)
│   │   └── examples.md               # Diagram examples with code
│   └── public/                        # Static assets (logos, favicons)
├── .github/workflows/
│   ├── ci.yml                         # CI — Ruff lint, Pyright types, Pytest (Python 3.12+3.13)
│   └── docs.yml                       # Docs — VitePress build + GitHub Pages deploy
├── .pre-commit-config.yaml            # Pre-commit hooks (Ruff, Pyright, pytest on push)
├── Dockerfile                         # Multi-stage Docker build with Graphviz
├── pyproject.toml                     # Project metadata, dependencies, tool config
└── uv.lock                           # Dependency lockfile (uv package manager)