graph LR
    A[AI Assistant] -->|Natural Language| B[MCP Server]
    B -->|Python DSL| C[Diagrams + Graphviz]
    C -->|PNG| D[MCP Apps Viewer]
    B -->|Security Scan| E[AST + Bandit]
    E -->|Pass| C

uvx microsoft.azure-diagram-mcp-server

{
  "mcp": {
    "servers": {
      "azure-diagram": {
        "command": "uvx",
        "args": ["microsoft.azure-diagram-mcp-server"],
        "env": {
          "FASTMCP_LOG_LEVEL": "ERROR"
        }
      }
    }
  }
}

docker build -t microsoft/azure-diagram-mcp-server .

{
  "mcp": {
    "servers": {
      "azure-diagram": {
        "command": "docker",
        "args": ["run", "--rm", "-i", "--env", "FASTMCP_LOG_LEVEL=ERROR",
                 "microsoft/azure-diagram-mcp-server:latest"]
      }
    }
  }
}

graph TB
    subgraph "GitHub Copilot"
        CLI[Copilot CLI]
        VS[VS Code Copilot]
    end

    subgraph "MCP Server"
        S[server.py<br/>FastMCP]
        DT[diagram_tools.py<br/>Generation + Examples]
        SC[scanner.py<br/>AST + Bandit]
        V[viewer/app.html<br/>MCP Apps Viewer]
    end

    subgraph "Copilot SDK Layer"
        CC[copilot_client.py<br/>DiagramCopilotClient]
        AG[Custom Agent<br/>azure-diagram-architect]
    end

    CLI & VS -->|MCP stdio| S
    CC -->|MCP local| S
    AG --> CC
    S --> DT
    S --> V
    DT --> SC
    SC -->|Pass| DT
    DT -->|Python DSL| GV[Graphviz → PNG]

sequenceDiagram
    participant User
    participant Copilot as GitHub Copilot
    participant MCP as MCP Server
    participant App as MCP Apps Viewer

    User->>Copilot: "Create an Azure web app diagram"
    Copilot->>MCP: list_icons(provider_filter="azure")
    MCP-->>Copilot: Available icons
    Copilot->>MCP: get_diagram_examples(diagram_type="azure")
    MCP-->>Copilot: Example code
    Copilot->>MCP: generate_diagram(code="...")
    MCP-->>Copilot: PNG + structuredContent
    Copilot->>App: Render diagram in viewer
    App-->>User: Interactive diagram with pan/zoom

graph LR
    subgraph "MCP Server"
        GD[generate_diagram] -->|CallToolResult| SC[structuredContent<br/>status + imageData]
        SC --> META["_meta.ui.resourceUri<br/>ui://diagram-viewer/app.html"]
    end

    subgraph "MCP Apps Viewer"
        META --> V[Interactive Viewer]
        V --> PAN[Pan & Drag]
        V --> ZOOM[Zoom In/Out]
        V --> DL[Download PNG]
        V --> THEME[Dark/Light Theme]
        V --> FIT[Fit to View]
    end

from diagrams import Diagram
from diagrams.azure.compute import AppServices, FunctionApps
from diagrams.azure.database import CosmosDb
from diagrams.azure.network import ApplicationGateway

with Diagram("Azure Web Architecture", show=False):
    gateway = ApplicationGateway("Gateway")
    app = AppServices("App Service")
    functions = FunctionApps("Functions")
    db = CosmosDb("Cosmos DB")

    gateway >> app >> db
    gateway >> functions >> db

graph LR
    U[User Prompt] --> CC[DiagramCopilotClient]
    CC -->|Creates Session| CS[CopilotClient]
    CS -->|Connects| MCP[Diagram MCP Server]
    CS -->|Uses| AG[azure-diagram-architect<br/>Custom Agent]
    MCP -->|Returns| IMG[PNG Diagram]

uv run microsoft.azure-diagram-copilot

import asyncio
from microsoft.azure_diagram_mcp_server.copilot_client import DiagramCopilotClient

async def main():
    async with DiagramCopilotClient(model="gpt-4.1") as client:
        client.on_delta(lambda delta: print(delta, end="", flush=True))
        client.on_idle(lambda: print())

        await client.generate(
            "Create a 3-tier Azure architecture with App Gateway, "
            "App Service, and Cosmos DB"
        )

asyncio.run(main())

export DIAGRAM_COPILOT_PROVIDER_TYPE=azure
export DIAGRAM_COPILOT_BASE_URL=https://your-resource.openai.azure.com
export DIAGRAM_COPILOT_API_KEY=your-api-key
uv run microsoft.azure-diagram-copilot

client = DiagramCopilotClient(session_id="my-project-diagrams")
await client.start()
await client.generate("Create an Azure web app diagram")

# Resume later
await client.resume("my-project-diagrams")
await client.generate("Add a Redis cache to the previous diagram")
await client.stop()

# Setup
uv sync --group dev

# Test (140 tests, 9 skip without Graphviz)
uv run pytest tests/ -v

# Lint + format
uv run ruff check microsoft/ tests/
uv run ruff format --check microsoft/ tests/

# Type check
uv run pyright

# Coverage
uv run pytest --cov=microsoft --cov-report=term-missing tests/

cd docs-site && npm install && npm run docs:dev  # Local dev server