MCP Tool Specification

{
  "name": "generate_architecture_diagram",
  "description": "Analyzes a codebase or a set of infrastructure files and generates an animated cloud-arch diagram showing the system architecture. Returns a script and a shareable diagram URL.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "files": {
        "type": "array",
        "description": "List of file paths and their contents to analyze. At least one file is required.",
        "items": {
          "type": "object",
          "properties": {
            "path": {
              "type": "string",
              "description": "Relative file path from the repository root (e.g. 'docker-compose.yml', 'k8s/deployments/api.yaml')"
            },
            "content": {
              "type": "string",
              "description": "Full text content of the file"
            }
          },
          "required": ["path", "content"]
        },
        "minItems": 1
      },
      "focus": {
        "type": "string",
        "description": "Optional natural language description of what aspect of the architecture to highlight. If omitted, the full topology is generated. Examples: 'authentication flow', 'Kafka topics and consumers', 'database layer'.",
        "examples": [
          "authentication flow",
          "Kafka topics and consumer groups",
          "database layer and connection pooling",
          "external integrations"
        ]
      },
      "layers": {
        "type": "array",
        "description": "Optional layer names to assign. If the codebase has multiple environments or evolutionary stages, specify layer names to assign. The generator will attempt to assign components to layers accordingly.",
        "items": { "type": "string" },
        "examples": [["v1", "v2", "v3"], ["prod", "staging"], ["mvp", "highload"]]
      },
      "slug": {
        "type": "string",
        "description": "Optional URL slug for the saved diagram. If omitted, a random slug is generated. Must match [a-z0-9-]+.",
        "pattern": "^[a-z0-9-]+$"
      },
      "save": {
        "type": "boolean",
        "description": "Whether to save the generated script to the cloud-arch server and return a shareable URL. Defaults to true.",
        "default": true
      }
    },
    "required": ["files"]
  }
}

{
  "type": "object",
  "properties": {
    "script": {
      "type": "string",
      "description": "The generated cloud-arch TypeScript script. Can be pasted directly into the editor."
    },
    "url": {
      "type": "string",
      "description": "Shareable URL to the rendered diagram. Null if save=false or if the server is unavailable.",
      "nullable": true,
      "example": "https://web.cloud-arch.ru/s/my-service"
    },
    "slug": {
      "type": "string",
      "description": "The URL slug used to save the script.",
      "nullable": true
    },
    "summary": {
      "type": "object",
      "description": "Summary of what the generator found in the input files.",
      "properties": {
        "servicesFound": {
          "type": "integer",
          "description": "Number of distinct services/processes identified"
        },
        "connectionsFound": {
          "type": "integer",
          "description": "Number of directed connections inferred"
        },
        "topicsFound": {
          "type": "integer",
          "description": "Number of Kafka/AMQP topics identified"
        },
        "layersUsed": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Layer names actually used in the generated script"
        },
        "warnings": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Non-fatal warnings about ambiguous or inferred connections"
        }
      }
    }
  },
  "required": ["script", "summary"]
}

{
  "files": [
    {
      "path": "docker-compose.yml",
      "content": "version: '3.8'\nservices:\n  api:\n    image: myapp/api:latest\n    ports:\n      - '8080:8080'\n    environment:\n      DATABASE_URL: postgres://pg:5432/mydb\n      REDIS_URL: redis://redis:6379\n    depends_on:\n      - pg\n      - redis\n  pg:\n    image: postgres:15\n    ports:\n      - '5432:5432'\n  redis:\n    image: redis:7\n    ports:\n      - '6379:6379'\n  nginx:\n    image: nginx:latest\n    ports:\n      - '80:80'\n      - '443:443'\n    depends_on:\n      - api\n"
    }
  ],
  "focus": "full topology",
  "slug": "my-app",
  "save": true
}

{
  "script": "const topology = new TopologyBuilder(true);\n\nconst infra = topology.createGroup('infra', { label: 'Infrastructure' });\ninfra\n  .addProcess({ id: 'nginx', label: 'Nginx', state: 'running' })\n  .addProcess({ id: 'api',   label: 'API Service', state: 'running' })\n  .addProcess({ id: 'pg',    label: 'PostgreSQL', shape: 'cylinder', state: 'running' })\n  .addProcess({ id: 'redis', label: 'Redis',       shape: 'cylinder', state: 'running' })\n  .autoResize();\n\ntopology.connect('nginx', 'api',   { protocol: 'http',       label: 'proxy' });\ntopology.connect('api',   'pg',    { protocol: 'postgresql', label: 'DATABASE_URL' });\ntopology.connect('api',   'redis', { protocol: 'redis',      label: 'REDIS_URL' });\n\nawait topology.apply();\nreturn null;",
  "url": "https://web.cloud-arch.ru/s/my-app",
  "slug": "my-app",
  "summary": {
    "servicesFound": 4,
    "connectionsFound": 3,
    "topicsFound": 0,
    "layersUsed": [],
    "warnings": [
      "nginx→api connection inferred from depends_on; verify if Nginx proxies or just starts after API"
    ]
  }
}