AI Diagram Maker MCP Server

Instructions

Implementation Reference

• src/tools/generate-text.ts:35-53 (registration)

  Registration of the 'generate_diagram_from_text' tool.

  export function registerGenerateTextTool(server: McpServer): void {
    registerAppTool(
      server,
      "generate_diagram_from_text",
      {
        description:
          "Generate a software engineering diagram from a natural language description. " +
          "Use this tool when: the user asks to 'create a diagram', 'show me a flowchart', " +
          "'visualise the architecture', uses the keyword 'adm' or 'ai diagram maker', " +
          "or asks for any visual representation of code, systems, processes or data flows. " +
          "Supported diagram types: flowchart, sequence, ERD, system architecture, " +
          "network architecture, UML, mindmap, workflow. " +
          "Returns a link to view and edit the generated diagram in the browser.",
        inputSchema,
        _meta: { ui: { resourceUri: DIAGRAM_APP_RESOURCE_URI } },
      },
      async (args) => generateDiagram("text", args)
    );
  }

• src/tools/shared.ts:158-273 (handler)

  The 'generateDiagram' handler function that implements the tool logic.

  export async function generateDiagram(
    inputType: GenerateDiagramV2Request["inputType"],
    params: DiagramParams
  ): Promise<CallToolResult> {
    debugLog("Tool called:", { inputType, params: paramsForLog(params) });
  
    const apiKey = getApiKey();
    if (!apiKey) {
      const hint =
        process.env.PORT != null
          ? "Send your API key in the Authorization header (Bearer <key>) or X-ADM-API-Key header."
          : "Set the ADM_API_KEY environment variable.";
      return {
        isError: true,
        content: [
          {
            type: "text",
            text: `AI Diagram Maker API key is required. ${hint}`,
          },
        ],
      };
    }
  
    const requestBody: GenerateDiagramV2Request = {
      inputType,
      content: params.content,
      // Request SVG, then rasterize to PNG in this MCP server so icons render in chat.
      format: "svg",
      ...(params.prompt !== undefined && { prompt: params.prompt }),
      ...(params.diagramType !== undefined && {
        diagramType: params.diagramType,
      }),
      options: {
        saveDiagramEnabled: true,
        colorTheme: "pastel-layers",
        ...(isMock() && { useMock: true }),
        ...(isDebug() && { debug: true }),
        ...(params.isIconEnabled && { isIconEnabled: true }),
      },
    };
  
    debugLog("Request payload to AI Diagram Maker API:", payloadForLog(requestBody));
  
    const response = await postApiV2DiagramsGenerate(requestBody);
  
    const responseForLog = {
      status: response.status,
      data: {
        ...response.data,
        ...(typeof (response.data as { svg?: string })?.svg === "string" && {
          svg: truncateForLog((response.data as { svg: string }).svg),
        }),
      },
    };
    debugLog("Generate diagram API response:", responseForLog);
  
    if (response.status === 200) {
      const { svg, text, diagramUrl } = response.data;
  
      const content: CallToolResult["content"] = [];
  
      let textContent = text ?? "";
      if (diagramUrl) {
        const baseUrl = (process.env.ADM_BASE_URL ?? "https://app.aidiagrammaker.com").replace(
          /\/$/,
          ""
        );
        const fullDiagramUrl = diagramUrl.startsWith("/")
          ? `${baseUrl}${diagramUrl}`
          : diagramUrl;
        textContent += `\n\nEdit diagram: ${fullDiagramUrl} (open in browser to view and edit)`;
  
        if (svg) {
          try {
            const diagramId = new URL(fullDiagramUrl).pathname.split("/").filter(Boolean).pop();
            if (diagramId) {
              const inlined = await inlineSvgImages(svg, baseUrl);
              storeSvg(diagramId, inlined);
            }
          } catch {
            // URL parsing failed; image unavailable in App
          }
        }
      }
      if (textContent) {
        content.push({ type: "text", text: textContent });
      }
  
      return { content };
    }
  
    // Handle error responses
    const errorData = response.data as {
      error?: string;
      details?: string;
      rateLimitError?: { retryAfter?: number };
    };
  
    let errorMessage = `API request failed with status ${response.status}`;
  
    if (errorData?.error) {
      errorMessage = errorData.error;
      if (errorData.details) {
        errorMessage += `: ${errorData.details}`;
      }
    }
  
    if (response.status === 429 && errorData?.rateLimitError?.retryAfter) {
      errorMessage += ` (retry after ${errorData.rateLimitError.retryAfter} seconds)`;
    }
  
    return {
      isError: true,
      content: [{ type: "text", text: errorMessage }],
    };
  }

• src/tools/generate-text.ts:6-33 (schema)

  Input schema definition for the tool.

  const inputSchema = {
    content: z
      .string()
      .min(1)
      .describe(
        "Natural language description of the diagram to generate. " +
          "Be descriptive — include components, relationships, data flows, etc. " +
          'Example: "Create a microservices architecture with API gateway, auth service, user service, and PostgreSQL database"'
      ),
    diagramType: z
      .enum(DIAGRAM_TYPES)
      .optional()
      .describe(
        "Preferred diagram type. Leave blank to let the AI infer the best type from your description."
      ),
    prompt: z
      .string()
      .optional()
      .describe(
        'Additional styling or layout instruction. Example: "Use left-to-right layout with pastel colors"'
      ),
    isIconEnabled: z
      .boolean()
      .optional()
      .describe(
        "Set to true when the user asks to include icons in the diagram."
      ),
  };