Merge pull request #43 from Mermaid-Chart/AT-360-new-mcp-tool-for-the-chat-with-mermaid

AT-360 Added Diagram Chat Functionality To Mermaid/sdk So MCP Server Can Directly Access Mermaid AI

Author: Prashant-7718

.changeset/upset-owls-kiss.md

@@ -0,0 +1,5 @@
+---
+'@mermaidchart/sdk': patch
+---
+
+Add diagramChat method to SDK for external clients like MCP to interact with Mermaid chat

packages/sdk/src/index.e2e.test.ts

@@ -180,7 +180,7 @@ describe('deleteDocument', () => {
     expect(deletedDoc.projectID).toStrictEqual(newDocument.projectID);
 
     expect(await client.getDocuments(testProjectId)).not.toContainEqual(newDocument);
-  });
+  }, 20000); // 20 seconds — test makes 4 sequential HTTP calls
 });
 
 describe('getDocument', () => {

packages/sdk/src/index.test.ts

@@ -87,6 +87,51 @@ describe('MermaidChart', () => {
     });
   });
 
+  describe('#diagramChat', () => {
+    beforeEach(async () => {
+      await client.setAccessToken('test-access-token');
+    });
+
+    it('should parse JSON response with text and documentChatThreadID', async () => {
+      const jsonResponse = {
+        text: 'Hello, here is your diagram!',
+        documentChatThreadID: 'thread-abc-123',
+        documentID: 'doc-123',
+      };
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      vi.spyOn((client as any).axios, 'post').mockResolvedValue({ data: jsonResponse });
+
+      const result = await client.diagramChat({
+        message: 'Create a flowchart',
+        documentID: 'doc-123',
+      });
+
+      expect(result.text).toBe('Hello, here is your diagram!');
+      expect(result.documentChatThreadID).toBe('thread-abc-123');
+      expect(result.documentID).toBe('doc-123');
+    });
+
+    it('should throw AICreditsLimitExceededError on 402', async () => {
+      // Mock the underlying axios call to simulate a 402 response from the API
+      // so the actual error-mapping logic inside diagramChat() is exercised.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      vi.spyOn((client as any).axios, 'post').mockRejectedValue({
+        response: {
+          status: 402,
+          data: 'AI credits limit exceeded',
+        },
+      });
+
+      await expect(
+        client.diagramChat({
+          message: 'Create a flowchart',
+          documentID: 'doc-123',
+        }),
+      ).rejects.toThrow(AICreditsLimitExceededError);
+    });
+  });
+
   describe('#repairDiagram', () => {
     beforeEach(async () => {
       await client.setAccessToken('test-access-token');
@@ -109,9 +154,14 @@ describe('MermaidChart', () => {
     });
 
     it('should throw AICreditsLimitExceededError on 402', async () => {
-      vi.spyOn(client, 'repairDiagram').mockRejectedValue(
-        new AICreditsLimitExceededError('AI credits limit exceeded'),
-      );
+      // Mock the underlying axios call to simulate a 402 response from the API
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      vi.spyOn((client as any).axios, 'post').mockRejectedValue({
+        response: {
+          status: 402,
+          data: 'AI credits limit exceeded',
+        },
+      });
 
       await expect(
         client.repairDiagram({

packages/sdk/src/index.ts

@@ -10,6 +10,8 @@ import {
 import type {
   AuthState,
   AuthorizationData,
+  DiagramChatRequest,
+  DiagramChatResponse,
   Document,
   InitParams,
   MCDocument,
@@ -24,6 +26,30 @@ import { URLS } from './urls.js';
 const defaultBaseURL = 'https://www.mermaid.ai'; // "http://127.0.0.1:5174"
 const authorizationURLTimeout = 60_000;
 
+/**
+ * Re-throws an Axios error as {@link AICreditsLimitExceededError} when the
+ * server responds with HTTP 402, otherwise rethrows the original error.
+ */
+function throwIfAICreditsExceeded(error: unknown): never {
+  if (
+    error &&
+    typeof error === 'object' &&
+    'response' in error &&
+    error.response &&
+    typeof error.response === 'object' &&
+    'status' in error.response &&
+    (error as { response: { status: number } }).response.status === 402
+  ) {
+    const axiosError = error as { response: { status: number; data?: unknown } };
+    throw new AICreditsLimitExceededError(
+      typeof axiosError.response.data === 'string'
+        ? axiosError.response.data
+        : 'AI credits limit exceeded',
+    );
+  }
+  throw error as Error;
+}
+
 export class MermaidChart {
   private clientID: string;
   #baseURL!: string;
@@ -300,23 +326,44 @@ export class MermaidChart {
       );
       return response.data;
     } catch (error: unknown) {
-      if (
-        error &&
-        typeof error === 'object' &&
-        'response' in error &&
-        error.response &&
-        typeof error.response === 'object' &&
-        'status' in error.response &&
-        error.response.status === 402
-      ) {
-        const axiosError = error as { response: { status: number; data?: unknown } };
-        throw new AICreditsLimitExceededError(
-          typeof axiosError.response.data === 'string'
-            ? axiosError.response.data
-            : 'AI credits limit exceeded',
-        );
-      }
-      throw error;
+      throwIfAICreditsExceeded(error);
+    }
+  }
+
+  /**
+   * Chat with Mermaid AI about a diagram.
+   *
+   * Sends a single user message to the Mermaid AI chat endpoint.  The backend
+   * automatically fetches the full conversation history from the database
+   * (when `documentChatThreadID` is provided), so callers never need to track
+   * or resend previous messages.
+   *
+   * @param request - The chat request containing the user message and diagram context
+   * @returns The AI response text and the chat thread ID
+   * @throws {@link AICreditsLimitExceededError} if AI credits limit is exceeded (HTTP 402)
+   */
+  public async diagramChat(request: DiagramChatRequest): Promise<DiagramChatResponse> {
+    const { message, documentID, code = '', documentChatThreadID } = request;
+
+    try {
+      const { data } = await this.axios.post<DiagramChatResponse>(URLS.rest.openai.chat, {
+        messages: [
+          { id: uuid(), role: 'user' as const, content: message, experimental_attachments: [] },
+        ],
+        code,
+        documentID,
+        documentChatThreadID,
+        parentID: null,
+        autoFetchHistory: true,
+      });
+
+      return {
+        text: data.text,
+        documentChatThreadID: data.documentChatThreadID ?? documentChatThreadID,
+        documentID,
+      };
+    } catch (error: unknown) {
+      throwIfAICreditsExceeded(error);
     }
   }
 }

packages/sdk/src/types.ts

@@ -96,6 +96,40 @@ export interface RepairDiagramRequest {
   userID?: string;
 }
 
+/**
+ * Request parameters for chatting with the Mermaid AI about a diagram.
+ */
+export interface DiagramChatRequest {
+  /** The user's chat message / question. */
+  message: string;
+  /** The MermaidChart document ID to associate the chat thread with. */
+  documentID: string;
+  /** Mermaid diagram code for context. Defaults to an empty string. */
+  code?: string;
+  /**
+   * Existing chat thread ID to continue a conversation.
+   * Returned from a previous diagramChat() call.
+   * When provided, the backend automatically fetches the stored conversation
+   * history from the database so the AI has full context.
+   */
+  documentChatThreadID?: string;
+}
+
+/**
+ * Response from chatting with the Mermaid AI.
+ */
+export interface DiagramChatResponse {
+  /** The AI response text, which may contain Mermaid code blocks. */
+  text: string;
+  /** Same as the document ID passed in the request. */
+  documentID: string;
+  /**
+   * The chat thread ID created or used for this conversation.
+   * Pass this back as documentChatThreadID in subsequent calls to continue the thread.
+   */
+  documentChatThreadID?: string;
+}
+
 /**
  * Response from repairing a diagram.
  * Matches OpenAIGenerationResult from collab.

packages/sdk/src/urls.ts

@@ -41,6 +41,7 @@ export const URLS = {
     },
     openai: {
       repair: `/rest-api/openai/repair`,
+      chat: `/rest-api/openai/chat`,
     },
   },
   raw: (document: Pick<MCDocument, 'documentID' | 'major' | 'minor'>, theme: 'light' | 'dark') => {