@shirbarzur/planform-mcp-server 1.0.1

package/src/server.ts

@@ -0,0 +1,1189 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  Tool,
+  CallToolResult,
+  ListToolsResult,
+} from '@modelcontextprotocol/sdk/types.js';
+import { ApiClient } from './api-client.js';
+import { Logger } from './logger.js';
+import { USAGE_EXAMPLES } from './usage-examples.js';
+import open from 'open';
+
+export class PlanformMCPServer {
+  private server: Server;
+  private apiClient: ApiClient;
+  private logger: Logger;
+  private activePolling: Map<string, NodeJS.Timeout> = new Map();
+
+  constructor() {
+    this.server = new Server(
+      {
+        name: process.env.MCP_SERVER_NAME || 'planform-mcp',
+        version: process.env.MCP_SERVER_VERSION || '1.0.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+        instructions: USAGE_EXAMPLES.trim(),
+      }
+    );
+
+    this.apiClient = new ApiClient();
+    this.logger = new Logger();
+
+    this.setupHandlers();
+  }
+
+  private setupHandlers() {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      this.logger.info('Listing available tools');
+      
+      const tools: Tool[] = [
+        {
+          name: 'health_check',
+          description: 'Check the health status of the Planform MCP server',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+          },
+        },
+        {
+          name: 'get_usage_examples',
+          description: 'Get usage examples and step-by-step instructions for the Planform MCP (auth flow, list diagrams, create diagram, etc.). Call this when unsure how to use the server.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+          },
+        },
+        {
+          name: 'device_start',
+          description: 'REQUIRED FIRST before listing or managing diagrams. Start device code flow: opens browser for user to approve; after approval returns approved_user_uuid and stores the token. Use approved_user_uuid from the response as user_uuid for diagrams_list, diagram_create, etc.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+          },
+        },
+        {
+          name: 'device_token_poll',
+          description: '[Optional/Advanced] Manually poll for MCP JWT after user approves. Usually not needed since device_start polls automatically.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              device_code: {
+                type: 'string',
+                description: 'Device code from device_start response',
+              },
+            },
+            required: ['device_code'],
+          },
+        },
+        {
+          name: 'backend_health_check',
+          description: 'Check the health status of the Planform backend API',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+          },
+        },
+        {
+          name: 'diagram_create',
+          description: 'Create a new diagram. Requires prior authentication via device_start; use approved_user_uuid from device_start response as user_uuid.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              user_uuid: {
+                type: 'string',
+                description: 'User UUID who owns the diagram (use approved_user_uuid from device_start response)',
+              },
+              title: {
+                type: 'string',
+                description: 'Diagram title',
+              },
+              type: {
+                type: 'string',
+                description: 'Diagram type (e.g., "uml.class")',
+              },
+            },
+            required: ['user_uuid', 'title', 'type'],
+          },
+        },
+        {
+          name: 'diagrams_list',
+          description: 'List all diagrams of the authenticated user. REQUIRES authentication first: call device_start, then use the approved_user_uuid from that response as user_uuid here.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              user_uuid: {
+                type: 'string',
+                description: 'User UUID (use approved_user_uuid from device_start response after authenticating)',
+              },
+              status: {
+                type: 'string',
+                description: 'Filter by status (active|archived)',
+                enum: ['active', 'archived'],
+              },
+              page: {
+                type: 'number',
+                description: 'Page number (default: 1)',
+                default: 1,
+              },
+              page_size: {
+                type: 'number',
+                description: 'Number of items per page (default: 10)',
+                default: 10,
+              },
+            },
+            required: ['user_uuid'],
+          },
+        },
+        {
+          name: 'diagram_get',
+          description: 'Fetch full diagram (nodes + links) to mirror state locally. Requires prior authentication via device_start.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              diagram_uuid: {
+                type: 'string',
+                description: 'Diagram UUID',
+              },
+            },
+            required: ['diagram_uuid'],
+          },
+        },
+        {
+          name: 'nodes_create',
+          description: 'Create UML node with immutable grid placement',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              diagram_uuid: {
+                type: 'string',
+                description: 'Diagram UUID',
+              },
+              kind: {
+                type: 'string',
+                description: 'Node kind',
+                enum: ['class', 'interface', 'enum'],
+              },
+              name: {
+                type: 'string',
+                description: 'Node name',
+              },
+              fields: {
+                type: 'array',
+                description: 'Node fields',
+                items: {
+                  type: 'object',
+                  properties: {
+                    name: { type: 'string' },
+                    type: { type: 'string' },
+                    visibility: { type: 'string' },
+                    static: { type: 'boolean' },
+                  },
+                },
+              },
+              methods: {
+                type: 'array',
+                description: 'Node methods',
+                items: {
+                  type: 'object',
+                  properties: {
+                    name: { type: 'string' },
+                    returns: { type: 'string' },
+                    visibility: { type: 'string' },
+                    static: { type: 'boolean' },
+                    params: {
+                      type: 'array',
+                      items: {
+                        type: 'object',
+                        properties: {
+                          name: { type: 'string' },
+                          type: { type: 'string' },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+              enumValues: {
+                type: 'array',
+                description: 'Enum values (for enum nodes)',
+                items: {
+                  type: 'object',
+                  properties: {
+                    name: { type: 'string' },
+                    value: { type: ['string', 'null'] },
+                    documentation: { type: ['string', 'null'] },
+                  },
+                  required: ['name'],
+                },
+              },
+              stereotypes: {
+                type: 'array',
+                description: 'Node stereotypes',
+                items: { type: 'string' },
+              },
+            },
+            required: ['diagram_uuid', 'kind'],
+          },
+        },
+        {
+          name: 'node_update',
+          description: 'Update structural fields (MCP authoritative)',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              diagram_uuid: {
+                type: 'string',
+                description: 'Diagram UUID',
+              },
+              node_id: {
+                type: 'string',
+                description: 'Node ID',
+              },
+              patch: {
+                type: 'object',
+                description: 'Node fields to update',
+              },
+              if_version: {
+                type: 'number',
+                description: 'Version for optimistic concurrency',
+              },
+            },
+            required: ['diagram_uuid', 'node_id', 'patch'],
+          },
+        },
+        {
+          name: 'node_verify',
+          description: 'Mark a node as verified by MCP after confirming structure in code',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              diagram_uuid: {
+                type: 'string',
+                description: 'Diagram UUID',
+              },
+              node_id: {
+                type: 'string',
+                description: 'Node ID',
+              },
+              structural_fields: {
+                type: 'object',
+                description: 'Structural fields to verify',
+              },
+              diff_detected: {
+                type: 'boolean',
+                description: 'Whether differences were detected',
+              },
+            },
+            required: ['diagram_uuid', 'node_id', 'structural_fields'],
+          },
+        },
+        {
+          name: 'node_delete',
+          description: 'Delete node with status-based logic',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              diagram_uuid: {
+                type: 'string',
+                description: 'Diagram UUID',
+              },
+              node_id: {
+                type: 'string',
+                description: 'Node ID',
+              },
+            },
+            required: ['diagram_uuid', 'node_id'],
+          },
+        },
+        {
+          name: 'links_create',
+          description: 'Create link between nodes (never moves nodes). Note: from and to must be node labels (e.g. n-1, n-2), not UUIDs; using UUIDs returns 400.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              diagram_uuid: {
+                type: 'string',
+                description: 'Diagram UUID',
+              },
+              kind: {
+                type: 'string',
+                description: 'Link kind',
+                enum: ['association', 'aggregation', 'composition', 'inheritance', 'implements', 'dependency'],
+              },
+              from: {
+                type: 'string',
+                description: 'Source node label (e.g. n-1, n-2). Backend expects labels, not node UUIDs.',
+              },
+              to: {
+                type: 'string',
+                description: 'Target node label (e.g. n-1, n-2). Backend expects labels, not node UUIDs.',
+              },
+              label: {
+                type: 'string',
+                description: 'Link label',
+              },
+              directional: {
+                type: 'string',
+                description: 'Link directionality: "none", "unidirectional", or "bidirectional". For inheritance/implements/dependency links, must be "unidirectional" or "bidirectional" (not "none"). If omitted, backend will set appropriate defaults based on link kind.',
+                enum: ['none', 'unidirectional', 'bidirectional'],
+              },
+            },
+            required: ['diagram_uuid', 'kind', 'from', 'to'],
+          },
+        },
+        {
+          name: 'link_update',
+          description: 'Update link fields (MCP authoritative)',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              diagram_uuid: {
+                type: 'string',
+                description: 'Diagram UUID',
+              },
+              link_id: {
+                type: 'string',
+                description: 'Link ID',
+              },
+              patch: {
+                type: 'object',
+                description: 'Link fields to update',
+              },
+              if_version: {
+                type: 'number',
+                description: 'Version for optimistic concurrency',
+              },
+            },
+            required: ['diagram_uuid', 'link_id', 'patch'],
+          },
+        },
+        {
+          name: 'link_verify',
+          description: 'Mark a link as verified by MCP after confirming relationship in code',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              diagram_uuid: {
+                type: 'string',
+                description: 'Diagram UUID',
+              },
+              link_id: {
+                type: 'string',
+                description: 'Link ID',
+              },
+              structural_fields: {
+                type: 'object',
+                description: 'Structural fields to verify',
+              },
+              diff_detected: {
+                type: 'boolean',
+                description: 'Whether differences were detected',
+              },
+            },
+            required: ['diagram_uuid', 'link_id', 'structural_fields'],
+          },
+        },
+        {
+          name: 'link_delete',
+          description: 'Delete link with status-based logic',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              diagram_uuid: {
+                type: 'string',
+                description: 'Diagram UUID',
+              },
+              link_id: {
+                type: 'string',
+                description: 'Link ID',
+              },
+            },
+            required: ['diagram_uuid', 'link_id'],
+          },
+        },
+      ];
+
+      return { tools };
+    });
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      this.logger.info(`Tool called: ${request.params.name}`);
+
+      try {
+        switch (request.params.name) {
+          case 'health_check':
+            return await this.handleHealthCheck();
+          
+          case 'get_usage_examples':
+            return await this.handleGetUsageExamples();
+          
+          case 'device_start':
+            return await this.handleDeviceStart();
+          
+          case 'device_token_poll':
+            return await this.handleDeviceTokenPoll(request.params.arguments);
+          
+          case 'backend_health_check':
+            return await this.handleBackendHealthCheck();
+          
+          case 'diagram_create':
+            return await this.handleDiagramCreate(request.params.arguments);
+          
+          case 'diagram_get':
+            return await this.handleDiagramGet(request.params.arguments);
+          
+          case 'diagrams_list':
+            return await this.handleDiagramsList(request.params.arguments);
+          
+          case 'nodes_create':
+            return await this.handleNodesCreate(request.params.arguments);
+          
+          case 'node_update':
+            return await this.handleNodeUpdate(request.params.arguments);
+          
+          case 'node_verify':
+            return await this.handleNodeVerify(request.params.arguments);
+          
+          case 'node_delete':
+            return await this.handleNodeDelete(request.params.arguments);
+          
+          case 'links_create':
+            return await this.handleLinksCreate(request.params.arguments);
+          
+          case 'link_update':
+            return await this.handleLinkUpdate(request.params.arguments);
+          
+          case 'link_verify':
+            return await this.handleLinkVerify(request.params.arguments);
+          
+          case 'link_delete':
+            return await this.handleLinkDelete(request.params.arguments);
+          
+          default:
+            throw new Error(`Unknown tool: ${request.params.name}`);
+        }
+      } catch (error) {
+        this.logger.error(`Error in tool ${request.params.name}:`, error);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  private async handleHealthCheck(): Promise<CallToolResult> {
+    this.logger.info('Health check requested');
+    
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            status: 'healthy',
+            server: 'planform-mcp',
+            version: process.env.MCP_SERVER_VERSION || '1.0.0',
+            timestamp: new Date().toISOString(),
+          }, null, 2),
+        },
+      ],
+      isError: false,
+    };
+  }
+
+  private async handleGetUsageExamples(): Promise<CallToolResult> {
+    this.logger.info('Usage examples requested');
+    return {
+      content: [
+        {
+          type: 'text',
+          text: USAGE_EXAMPLES.trim(),
+        },
+      ],
+      isError: false,
+    };
+  }
+
+  private async handleDeviceStart(): Promise<CallToolResult> {
+    this.logger.info('Device start requested');
+    
+    try {
+      const response = await this.apiClient.startDeviceFlow();
+      
+      // Override verification URI if FRONTEND_BASE_URL is set
+      let verificationUri = response.verificationUri;
+      let verificationUriComplete = response.verificationUriComplete;
+      
+      const frontendBaseUrl = process.env.FRONTEND_BASE_URL;
+      if (frontendBaseUrl) {
+        // Parse the original URI to extract the path
+        try {
+          const originalUrl = new URL(response.verificationUri);
+          const path = originalUrl.pathname + originalUrl.search;
+          
+          // Replace with the configured frontend base URL
+          const newBaseUrl = frontendBaseUrl.endsWith('/') 
+            ? frontendBaseUrl.slice(0, -1) 
+            : frontendBaseUrl;
+          verificationUri = `${newBaseUrl}${path}`;
+          
+          // Update verification_uri_complete with the user code
+          const userCode = response.session.userCode;
+          const separator = path.includes('?') ? '&' : '?';
+          verificationUriComplete = `${verificationUri}${separator}code=${userCode}`;
+          
+          this.logger.info(`Overriding verification URI: ${response.verificationUri} -> ${verificationUri}`);
+        } catch (urlError) {
+          this.logger.warn(`Failed to parse verification URI, using original: ${urlError}`);
+        }
+      }
+      
+      // Automatically open the browser with the verification URI
+      try {
+        await open(verificationUriComplete);
+        this.logger.info(`Opened browser with verification URI: ${verificationUriComplete}`);
+      } catch (openError) {
+        this.logger.warn(`Failed to open browser automatically: ${openError}. Please open ${verificationUriComplete} manually.`);
+      }
+      
+      // Poll synchronously until token is received or expired
+      const maxWaitSeconds = parseInt(process.env.MCP_AUTH_MAX_WAIT_SECONDS || '120', 10);
+      const actualWaitTime = Math.min(response.expiresIn, maxWaitSeconds);
+      this.logger.info(`Waiting for user approval (polling every ${response.interval}s, will wait up to ${actualWaitTime}s of ${response.expiresIn}s total)...`);
+      const pollResult = await this.pollUntilApproved(
+        response.session.deviceCode,
+        response.expiresIn,
+        response.interval
+      );
+      
+      // Extract the relevant information for the MCP client
+      const deviceInfo: any = {
+        // Session fields from MCPDeviceSessionDTO
+        uuid: response.session.uuid,
+        created_at: response.session.createdAt,
+        updated_at: response.session.updatedAt,
+        device_code: response.session.deviceCode,
+        user_code: response.session.userCode,
+        state: response.session.state,
+        approved_user_uuid: response.session.approvedUserUuid,
+        expires_at: response.session.expiresAt,
+        approved_at: response.session.approvedAt,
+        // Additional device flow fields
+        verification_uri: verificationUri,
+        verification_uri_complete: verificationUriComplete,
+        expires_in: response.expiresIn,
+        interval: response.interval,
+      };
+      
+      if (pollResult.success) {
+        deviceInfo.message = '✅ Authentication successful! Token received and stored.';
+        deviceInfo.access_token_received = true;
+      } else {
+        deviceInfo.message = `❌ Authentication failed: ${pollResult.error || 'Unknown error'}`;
+        deviceInfo.access_token_received = false;
+      }
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(deviceInfo, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Device start failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Poll synchronously until token is received, expired, or denied
+   * Returns a promise that resolves when polling completes
+   */
+  private async pollUntilApproved(
+    deviceCode: string, 
+    expiresIn: number, 
+    interval: number
+  ): Promise<{ success: boolean; error?: string }> {
+    const startTime = Date.now();
+    
+    // Use a shorter timeout for synchronous waiting (default 2 minutes)
+    // This prevents Cursor from waiting the full 10 minutes
+    const maxWaitSeconds = parseInt(process.env.MCP_AUTH_MAX_WAIT_SECONDS || '120', 10);
+    const actualExpireTime = Math.min(
+      startTime + (expiresIn * 1000),  // Backend expiration
+      startTime + (maxWaitSeconds * 1000)  // Configurable max wait
+    );
+    
+    let pollCount = 0;
+    
+    while (true) {
+      const now = Date.now();
+      pollCount++;
+      
+      // Check if expired or max wait time reached
+      if (now >= actualExpireTime) {
+        const elapsed = Math.floor((now - startTime) / 1000);
+        if (elapsed >= maxWaitSeconds && elapsed < expiresIn) {
+          this.logger.warn(`Max wait time (${maxWaitSeconds}s) reached. Device code still valid for ${expiresIn - elapsed}s.`);
+          return { 
+            success: false, 
+            error: `Max wait time (${maxWaitSeconds}s) reached. Please approve in browser and use device_token_poll manually (optional), or try device_start again.` 
+          };
+        } else {
+          this.logger.warn('Device code expired while waiting for approval');
+          return { success: false, error: 'Device code expired' };
+        }
+      }
+
+      try {
+        this.logger.info(`Polling for token (attempt ${pollCount})...`);
+        const response = await this.apiClient.pollDeviceToken(deviceCode);
+        
+        if (response.access_token) {
+          // Success! Token received
+          this.logger.info('✅ Device token received successfully!');
+          return { success: true };
+        } else if (response.error) {
+          if (response.error === 'authorization_pending') {
+            // Continue polling
+            this.logger.info(`⏳ Authorization still pending (attempt ${pollCount}), waiting ${interval}s before next poll...`);
+            await new Promise(resolve => setTimeout(resolve, interval * 1000));
+            continue;
+          } else if (response.error === 'access_denied') {
+            this.logger.warn('❌ User denied access');
+            return { success: false, error: 'User denied access' };
+          } else if (response.error === 'expired_token') {
+            this.logger.warn('❌ Device code expired');
+            return { success: false, error: 'Device code expired' };
+          } else {
+            this.logger.warn(`Unexpected error: ${response.error}`);
+            return { success: false, error: response.error };
+          }
+        } else {
+          // No access_token and no error - unexpected, but continue polling
+          this.logger.warn(`Unexpected response format, continuing to poll...`);
+          await new Promise(resolve => setTimeout(resolve, interval * 1000));
+          continue;
+        }
+      } catch (error) {
+        // On HTTP errors, log and continue polling (might be temporary network issue)
+        this.logger.warn(`Polling error (will retry): ${error instanceof Error ? error.message : String(error)}`);
+        await new Promise(resolve => setTimeout(resolve, interval * 1000));
+        continue;
+      }
+    }
+  }
+
+  /**
+   * Start automatic background polling for device token (kept for backward compatibility)
+   * @deprecated Use pollUntilApproved for synchronous polling
+   */
+  private startAutomaticPolling(deviceCode: string, expiresIn: number, interval: number): void {
+    // Clear any existing polling for this device code
+    const existingTimeout = this.activePolling.get(deviceCode);
+    if (existingTimeout) {
+      clearTimeout(existingTimeout);
+    }
+
+    this.logger.info(`Starting automatic polling for device code (expires in ${expiresIn}s, polling every ${interval}s)`);
+    
+    const startTime = Date.now();
+    const expireTime = startTime + (expiresIn * 1000);
+    let pollCount = 0;
+    
+    const poll = async () => {
+      const now = Date.now();
+      pollCount++;
+      
+      // Check if expired
+      if (now >= expireTime) {
+        this.logger.warn('Device code expired, stopping automatic polling');
+        this.activePolling.delete(deviceCode);
+        return;
+      }
+
+      try {
+        this.logger.info(`Polling for token (attempt ${pollCount})...`);
+        const response = await this.apiClient.pollDeviceToken(deviceCode);
+        
+        if (response.access_token) {
+          // Success! Token received
+          this.logger.info('✅ Device token received successfully via automatic polling');
+          this.activePolling.delete(deviceCode);
+          return;
+        } else if (response.error) {
+          if (response.error === 'authorization_pending') {
+            // Continue polling
+            this.logger.info(`⏳ Authorization still pending (attempt ${pollCount}), continuing to poll...`);
+            const timeout = setTimeout(poll, interval * 1000);
+            this.activePolling.set(deviceCode, timeout);
+          } else if (response.error === 'access_denied') {
+            this.logger.warn('❌ User denied access, stopping polling');
+            this.activePolling.delete(deviceCode);
+          } else if (response.error === 'expired_token') {
+            this.logger.warn('❌ Device code expired, stopping polling');
+            this.activePolling.delete(deviceCode);
+          } else {
+            this.logger.warn(`Unexpected error: ${response.error}, stopping polling`);
+            this.activePolling.delete(deviceCode);
+          }
+        } else {
+          // No access_token and no error - unexpected, but continue polling
+          this.logger.warn(`Unexpected response format, continuing to poll...`);
+          const timeout = setTimeout(poll, interval * 1000);
+          this.activePolling.set(deviceCode, timeout);
+        }
+      } catch (error) {
+        // On HTTP errors, log and continue polling (might be temporary network issue)
+        this.logger.warn(`Polling error (will retry): ${error instanceof Error ? error.message : String(error)}`);
+        const timeout = setTimeout(poll, interval * 1000);
+        this.activePolling.set(deviceCode, timeout);
+      }
+    };
+
+    // Start first poll immediately (don't wait for interval)
+    poll();
+  }
+
+  private async handleDeviceTokenPoll(args: any): Promise<CallToolResult> {
+    this.logger.info('Device token poll requested');
+    
+    if (!args.device_code) {
+      throw new Error('device_code is required');
+    }
+
+    try {
+      const response = await this.apiClient.pollDeviceToken(args.device_code);
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(response, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Device token poll failed:', error);
+      throw error;
+    }
+  }
+
+  private async handleBackendHealthCheck(): Promise<CallToolResult> {
+    this.logger.info('Backend health check requested');
+    
+    try {
+      const response = await this.apiClient.healthCheck();
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(response, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Backend health check failed:', error);
+      throw error;
+    }
+  }
+
+  private async handleDiagramCreate(args: any): Promise<CallToolResult> {
+    this.logger.info('Diagram create requested');
+    
+    if (!args.user_uuid || !args.title) {
+      throw new Error('user_uuid and title are required');
+    }
+
+    try {
+      if (!args.type) {
+        throw new Error('type is required');
+      }
+
+      const response = await this.apiClient.createDiagram(args.user_uuid, {
+        title: args.title,
+        type: args.type,
+      });
+      
+      // Return the response in the format specified by the design document
+      const result = {
+        diagram_uuid: response.uuid,
+        external_id: response.label, // Using label as external_id for now
+        title: response.title,
+        type: response.type,
+        version: 1, // Default version for new diagrams
+      };
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Diagram create failed:', error);
+      throw error;
+    }
+  }
+
+  private async handleDiagramGet(args: any): Promise<CallToolResult> {
+    this.logger.info('Diagram get requested');
+    
+    if (!args.diagram_uuid) {
+      throw new Error('diagram_uuid is required');
+    }
+
+    try {
+      const response = await this.apiClient.getDiagram(args.diagram_uuid);
+      
+      // Return the response in the format specified by the design document
+      const result = {
+        diagram: {
+          meta: {
+            uuid: response.uuid,
+            title: response.title,
+            type: response.type,
+            createdAt: response.createdAt,
+            updatedAt: response.updatedAt,
+            user: response.user,
+          },
+          nodes: response.nodes,
+          links: response.links,
+        },
+      };
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Diagram get failed:', error);
+      throw error;
+    }
+  }
+
+  private async handleDiagramsList(args: any): Promise<CallToolResult> {
+    this.logger.info('Diagrams list requested');
+    
+    if (!args.user_uuid) {
+      throw new Error('user_uuid is required');
+    }
+
+    try {
+      const response = await this.apiClient.getUserDiagrams(
+        args.user_uuid,
+        args.page || 1,
+        args.page_size || 10
+      );
+      
+      // Return the response in the format specified by the design document
+      const result = {
+        items: response.diagrams.map(diagram => ({
+          diagram_uuid: diagram.uuid,
+          external_id: diagram.label, // Using label as external_id for now
+          title: diagram.title,
+          type: diagram.type,
+          version: 1, // Default version
+          updated_at: diagram.updatedAt,
+        })),
+        next_page: response.pagination.page < response.pagination.totalPages 
+          ? (response.pagination.page + 1).toString() 
+          : undefined,
+      };
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Diagrams list failed:', error);
+      throw error;
+    }
+  }
+
+  private async handleNodesCreate(args: any): Promise<CallToolResult> {
+    this.logger.info('Nodes create requested');
+    
+    if (!args.diagram_uuid || !args.kind) {
+      throw new Error('diagram_uuid and kind are required');
+    }
+
+    try {
+      const requestPayload = {
+        kind: args.kind,
+        name: args.name || null,
+        fields: args.fields || null,
+        methods: args.methods || null,
+        enum_values: args.enumValues || null,
+        stereotypes: args.stereotypes || null,
+        group: args.group || null,
+        meta: args.meta || null,
+      };
+
+      // Log the request payload for debugging enum values
+      if (args.kind === 'enum') {
+        this.logger.info(`Creating enum node with enum_values: ${JSON.stringify(requestPayload.enum_values)}`);
+      }
+
+      const response = await this.apiClient.createNode(args.diagram_uuid, requestPayload);
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              node: response,
+              version: 1, // Default version
+            }, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Nodes create failed:', error);
+      throw error;
+    }
+  }
+
+  private async handleNodeUpdate(args: any): Promise<CallToolResult> {
+    this.logger.info('Node update requested');
+    
+    if (!args.diagram_uuid || !args.node_id || !args.patch) {
+      throw new Error('diagram_uuid, node_id, and patch are required');
+    }
+
+    try {
+      const response = await this.apiClient.updateNode(args.diagram_uuid, args.node_id, args.patch);
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              node: response,
+              version: 1, // Default version
+            }, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Node update failed:', error);
+      throw error;
+    }
+  }
+
+  private async handleNodeVerify(args: any): Promise<CallToolResult> {
+    this.logger.info('Node verify requested');
+    
+    if (!args.diagram_uuid || !args.node_id || !args.structural_fields) {
+      throw new Error('diagram_uuid, node_id, and structural_fields are required');
+    }
+
+    try {
+      const response = await this.apiClient.verifyNode(args.diagram_uuid, args.node_id, args.structural_fields);
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(response, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Node verify failed:', error);
+      throw error;
+    }
+  }
+
+  private async handleNodeDelete(args: any): Promise<CallToolResult> {
+    this.logger.info('Node delete requested');
+    
+    if (!args.diagram_uuid || !args.node_id) {
+      throw new Error('diagram_uuid and node_id are required');
+    }
+
+    try {
+      const response = await this.apiClient.deleteNode(args.diagram_uuid, args.node_id);
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(response, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Node delete failed:', error);
+      throw error;
+    }
+  }
+
+  private async handleLinksCreate(args: any): Promise<CallToolResult> {
+    this.logger.info('Links create requested');
+    
+    if (!args.diagram_uuid || !args.kind || !args.from || !args.to) {
+      throw new Error('diagram_uuid, kind, from, and to are required');
+    }
+
+    // Validate that "none" is not used for inheritance/implements/dependency links
+    const directionalRequiredKinds = ['inheritance', 'implements', 'dependency'];
+    if (args.directional === 'none' && directionalRequiredKinds.includes(args.kind)) {
+      throw new Error(`Link kind "${args.kind}" requires directional to be "unidirectional" or "bidirectional". "none" is not allowed.`);
+    }
+
+    try {
+      const requestBody: any = {
+        kind: args.kind,
+        fromNode: args.from,
+        toNode: args.to,
+        name: args.label || null,
+        meta: args.meta || null,
+        fromMultiplicity: args.fromMultiplicity || null,
+        toMultiplicity: args.toMultiplicity || null,
+      };
+      
+      // Only include directional if it was provided
+      if (args.directional !== undefined) {
+        requestBody.directional = args.directional;
+      }
+      
+      const response = await this.apiClient.createLink(args.diagram_uuid, requestBody);
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              link: response,
+              version: 1, // Default version
+            }, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Links create failed:', error);
+      throw error;
+    }
+  }
+
+  private async handleLinkUpdate(args: any): Promise<CallToolResult> {
+    this.logger.info('Link update requested');
+    
+    if (!args.diagram_uuid || !args.link_id || !args.patch) {
+      throw new Error('diagram_uuid, link_id, and patch are required');
+    }
+
+    try {
+      const response = await this.apiClient.updateLink(args.diagram_uuid, args.link_id, args.patch);
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              link: response,
+              version: 1, // Default version
+            }, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Link update failed:', error);
+      throw error;
+    }
+  }
+
+  private async handleLinkVerify(args: any): Promise<CallToolResult> {
+    this.logger.info('Link verify requested');
+    
+    if (!args.diagram_uuid || !args.link_id || !args.structural_fields) {
+      throw new Error('diagram_uuid, link_id, and structural_fields are required');
+    }
+
+    try {
+      const response = await this.apiClient.verifyLink(args.diagram_uuid, args.link_id, args.structural_fields);
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(response, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Link verify failed:', error);
+      throw error;
+    }
+  }
+
+  private async handleLinkDelete(args: any): Promise<CallToolResult> {
+    this.logger.info('Link delete requested');
+    
+    if (!args.diagram_uuid || !args.link_id) {
+      throw new Error('diagram_uuid and link_id are required');
+    }
+
+    try {
+      const response = await this.apiClient.deleteLink(args.diagram_uuid, args.link_id);
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(response, null, 2),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      this.logger.error('Link delete failed:', error);
+      throw error;
+    }
+  }
+
+  async start(transport: StdioServerTransport) {
+    await this.server.connect(transport);
+    this.logger.info('Planform MCP Server connected and ready');
+  }
+}