@shirbarzur/planform-mcp-server 1.0.5 → 1.0.6

package/src/server.ts

@@ -12,11 +12,20 @@ import { Logger } from './logger.js';
 import { USAGE_EXAMPLES } from './usage-examples.js';
 import open from 'open';
 
+/** UUID v4 pattern for distinguishing UUIDs from names/titles */
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Node label pattern (e.g. n-1, n-2) */
+const NODE_LABEL_REGEX = /^n-\d+$/;
+
 export class PlanformMCPServer {
   private server: Server;
   private apiClient: ApiClient;
   private logger: Logger;
   private activePolling: Map<string, NodeJS.Timeout> = new Map();
+  /** Set after successful sign_in; used for list_diagrams and create_diagram so callers need not pass user_uuid */
+  private sessionUserUuid: string | null = null;
+  /** Set after create_diagram or open_diagram; used for node/link tools so callers need not pass diagram_uuid */
+  private currentDiagramUuid: string | null = null;
 
   constructor() {
     this.server = new Server(
@@ -53,37 +62,37 @@ export class PlanformMCPServer {
           },
         },
         {
-          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.',
+          name: 'get_usage_guide',
+          description: 'Get step-by-step instructions and the recommended flow for the Planform MCP. Call 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.',
+          name: 'sign_in',
+          description: 'Call this first to sign in. Opens the browser for you to approve; after approval the server remembers your session. You do not need to pass or remember any IDs—later tools use your session and current diagram automatically.',
           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.',
+          name: 'poll_auth_token',
+          description: '[Optional/Advanced] Manually poll for auth token after user approves. Usually not needed since sign_in polls automatically.',
           inputSchema: {
             type: 'object',
             properties: {
               device_code: {
                 type: 'string',
-                description: 'Device code from device_start response',
+                description: 'Device code from sign_in response',
               },
             },
             required: ['device_code'],
           },
         },
         {
-          name: 'backend_health_check',
+          name: 'check_backend_health',
           description: 'Check the health status of the Planform backend API',
           inputSchema: {
             type: 'object',
@@ -91,37 +100,11 @@ export class PlanformMCPServer {
           },
         },
         {
-          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.',
+          name: 'list_diagrams',
+          description: 'List your diagrams. Uses your session from sign_in—no IDs to pass. Optional: filter by status, page, page_size.',
           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)',
@@ -138,41 +121,53 @@ export class PlanformMCPServer {
                 default: 10,
               },
             },
-            required: ['user_uuid'],
           },
         },
         {
-          name: 'diagram_get',
-          description: 'Fetch full diagram (nodes + links) to mirror state locally. Requires prior authentication via device_start.',
+          name: 'create_diagram',
+          description: 'Create a new diagram and set it as the current one. Uses your session—just pass title and type. After this you can add nodes and links without specifying a diagram.',
           inputSchema: {
             type: 'object',
             properties: {
-              diagram_uuid: {
+              title: {
                 type: 'string',
-                description: 'Diagram UUID',
+                description: 'Diagram title (e.g. "My class diagram")',
+              },
+              type: {
+                type: 'string',
+                description: 'Diagram type (e.g. "uml.class")',
               },
             },
-            required: ['diagram_uuid'],
+            required: ['title', 'type'],
           },
         },
         {
-          name: 'nodes_create',
-          description: 'Create UML node with immutable grid placement',
+          name: 'open_diagram',
+          description: 'Open a diagram by title or ID. If you omit the argument, re-loads the currently open diagram. The opened diagram becomes current for create_node and create_link.',
           inputSchema: {
             type: 'object',
             properties: {
-              diagram_uuid: {
+              diagram_identifier: {
                 type: 'string',
-                description: 'Diagram UUID',
+                description: 'Diagram title (e.g. "My class diagram") or diagram ID. Omit to refresh the current diagram.',
               },
+            },
+          },
+        },
+        {
+          name: 'create_node',
+          description: 'Add a node (class, interface, or enum) to the current diagram. You only need kind and optionally name, fields, methods. The server uses the diagram you created or opened.',
+          inputSchema: {
+            type: 'object',
+            properties: {
               kind: {
                 type: 'string',
-                description: 'Node kind',
+                description: 'Node kind: class, interface, or enum',
                 enum: ['class', 'interface', 'enum'],
               },
               name: {
                 type: 'string',
-                description: 'Node name',
+                description: 'Node name (e.g. "User")',
               },
               fields: {
                 type: 'array',
@@ -229,48 +224,40 @@ export class PlanformMCPServer {
                 items: { type: 'string' },
               },
             },
-            required: ['diagram_uuid', 'kind'],
+            required: ['kind'],
           },
         },
         {
-          name: 'node_update',
-          description: 'Update structural fields (MCP authoritative)',
+          name: 'update_node',
+          description: "Update a node's fields, methods, or name. Refer to the node by its name (e.g. 'User')—no IDs needed. Uses the current diagram.",
           inputSchema: {
             type: 'object',
             properties: {
-              diagram_uuid: {
+              node_identifier: {
                 type: 'string',
-                description: 'Diagram UUID',
-              },
-              node_id: {
-                type: 'string',
-                description: 'Node ID',
+                description: 'Node name (e.g. "User") or node ID. The server resolves the name to the node in the current diagram.',
               },
               patch: {
                 type: 'object',
-                description: 'Node fields to update',
+                description: 'Fields to update (name, fields, methods, etc.)',
               },
               if_version: {
                 type: 'number',
-                description: 'Version for optimistic concurrency',
+                description: 'Version for optimistic concurrency (optional)',
               },
             },
-            required: ['diagram_uuid', 'node_id', 'patch'],
+            required: ['node_identifier', 'patch'],
           },
         },
         {
-          name: 'node_verify',
-          description: 'Mark a node as verified by MCP after confirming structure in code',
+          name: 'verify_node',
+          description: 'Mark a node as verified (e.g. after confirming it matches code). Refer to the node by name (e.g. "User"). Uses the current diagram.',
           inputSchema: {
             type: 'object',
             properties: {
-              diagram_uuid: {
-                type: 'string',
-                description: 'Diagram UUID',
-              },
-              node_id: {
+              node_identifier: {
                 type: 'string',
-                description: 'Node ID',
+                description: 'Node name (e.g. "User") or node ID.',
               },
               structural_fields: {
                 type: 'object',
@@ -281,37 +268,29 @@ export class PlanformMCPServer {
                 description: 'Whether differences were detected',
               },
             },
-            required: ['diagram_uuid', 'node_id', 'structural_fields'],
+            required: ['node_identifier', 'structural_fields'],
           },
         },
         {
-          name: 'node_delete',
-          description: 'Delete node with status-based logic',
+          name: 'delete_node',
+          description: 'Delete a node from the current diagram. Refer to the node by its name (e.g. "User").',
           inputSchema: {
             type: 'object',
             properties: {
-              diagram_uuid: {
+              node_identifier: {
                 type: 'string',
-                description: 'Diagram UUID',
-              },
-              node_id: {
-                type: 'string',
-                description: 'Node ID',
+                description: 'Node name (e.g. "User") or node ID.',
               },
             },
-            required: ['diagram_uuid', 'node_id'],
+            required: ['node_identifier'],
           },
         },
         {
-          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.',
+          name: 'create_link',
+          description: 'Create a link between two nodes in the current diagram. Use node names (e.g. "User" and "Account") for from and to—the server resolves them. No diagram or node IDs needed.',
           inputSchema: {
             type: 'object',
             properties: {
-              diagram_uuid: {
-                type: 'string',
-                description: 'Diagram UUID',
-              },
               kind: {
                 type: 'string',
                 description: 'Link kind',
@@ -319,11 +298,11 @@ export class PlanformMCPServer {
               },
               from: {
                 type: 'string',
-                description: 'Source node label (e.g. n-1, n-2). Backend expects labels, not node UUIDs.',
+                description: 'Source node name (e.g. "User") or label (e.g. n-1).',
               },
               to: {
                 type: 'string',
-                description: 'Target node label (e.g. n-1, n-2). Backend expects labels, not node UUIDs.',
+                description: 'Target node name (e.g. "Account") or label (e.g. n-2).',
               },
               label: {
                 type: 'string',
@@ -331,26 +310,22 @@ export class PlanformMCPServer {
               },
               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.',
+                description: 'Link directionality: "none", "unidirectional", or "bidirectional". For inheritance/implements/dependency, use "unidirectional" or "bidirectional".',
                 enum: ['none', 'unidirectional', 'bidirectional'],
               },
             },
-            required: ['diagram_uuid', 'kind', 'from', 'to'],
+            required: ['kind', 'from', 'to'],
           },
         },
         {
-          name: 'link_update',
-          description: 'Update link fields (MCP authoritative)',
+          name: 'update_link',
+          description: "Update a link's label, direction, etc. Uses the current diagram. link_id comes from the response when you created the link or from open_diagram.",
           inputSchema: {
             type: 'object',
             properties: {
-              diagram_uuid: {
-                type: 'string',
-                description: 'Diagram UUID',
-              },
               link_id: {
                 type: 'string',
-                description: 'Link ID',
+                description: 'Link ID (from create_link or open_diagram response).',
               },
               patch: {
                 type: 'object',
@@ -358,25 +333,21 @@ export class PlanformMCPServer {
               },
               if_version: {
                 type: 'number',
-                description: 'Version for optimistic concurrency',
+                description: 'Version for optimistic concurrency (optional)',
               },
             },
-            required: ['diagram_uuid', 'link_id', 'patch'],
+            required: ['link_id', 'patch'],
           },
         },
         {
-          name: 'link_verify',
-          description: 'Mark a link as verified by MCP after confirming relationship in code',
+          name: 'verify_link',
+          description: 'Mark a link as verified (e.g. after confirming it matches code). Uses the current diagram. link_id from create_link or open_diagram.',
           inputSchema: {
             type: 'object',
             properties: {
-              diagram_uuid: {
-                type: 'string',
-                description: 'Diagram UUID',
-              },
               link_id: {
                 type: 'string',
-                description: 'Link ID',
+                description: 'Link ID (from create_link or open_diagram response).',
               },
               structural_fields: {
                 type: 'object',
@@ -387,25 +358,21 @@ export class PlanformMCPServer {
                 description: 'Whether differences were detected',
               },
             },
-            required: ['diagram_uuid', 'link_id', 'structural_fields'],
+            required: ['link_id', 'structural_fields'],
           },
         },
         {
-          name: 'link_delete',
-          description: 'Delete link with status-based logic',
+          name: 'delete_link',
+          description: 'Delete a link from the current diagram. link_id comes from create_link or open_diagram response.',
           inputSchema: {
             type: 'object',
             properties: {
-              diagram_uuid: {
-                type: 'string',
-                description: 'Diagram UUID',
-              },
               link_id: {
                 type: 'string',
-                description: 'Link ID',
+                description: 'Link ID (from create_link or open_diagram response).',
               },
             },
-            required: ['diagram_uuid', 'link_id'],
+            required: ['link_id'],
           },
         },
       ];
@@ -422,49 +389,49 @@ export class PlanformMCPServer {
           case 'health_check':
             return await this.handleHealthCheck();
           
-          case 'get_usage_examples':
+          case 'get_usage_guide':
             return await this.handleGetUsageExamples();
           
-          case 'device_start':
+          case 'sign_in':
             return await this.handleDeviceStart();
           
-          case 'device_token_poll':
+          case 'poll_auth_token':
             return await this.handleDeviceTokenPoll(request.params.arguments);
           
-          case 'backend_health_check':
+          case 'check_backend_health':
             return await this.handleBackendHealthCheck();
           
-          case 'diagram_create':
+          case 'create_diagram':
             return await this.handleDiagramCreate(request.params.arguments);
           
-          case 'diagram_get':
+          case 'open_diagram':
             return await this.handleDiagramGet(request.params.arguments);
           
-          case 'diagrams_list':
+          case 'list_diagrams':
             return await this.handleDiagramsList(request.params.arguments);
           
-          case 'nodes_create':
+          case 'create_node':
             return await this.handleNodesCreate(request.params.arguments);
           
-          case 'node_update':
+          case 'update_node':
             return await this.handleNodeUpdate(request.params.arguments);
           
-          case 'node_verify':
+          case 'verify_node':
             return await this.handleNodeVerify(request.params.arguments);
           
-          case 'node_delete':
+          case 'delete_node':
             return await this.handleNodeDelete(request.params.arguments);
           
-          case 'links_create':
+          case 'create_link':
             return await this.handleLinksCreate(request.params.arguments);
           
-          case 'link_update':
+          case 'update_link':
             return await this.handleLinkUpdate(request.params.arguments);
           
-          case 'link_verify':
+          case 'verify_link':
             return await this.handleLinkVerify(request.params.arguments);
           
-          case 'link_delete':
+          case 'delete_link':
             return await this.handleLinkDelete(request.params.arguments);
           
           default:
@@ -592,6 +559,9 @@ export class PlanformMCPServer {
       if (pollResult.success) {
         deviceInfo.message = '✅ Authentication successful! Token received and stored.';
         deviceInfo.access_token_received = true;
+        if (response.session.approvedUserUuid) {
+          this.sessionUserUuid = response.session.approvedUserUuid;
+        }
       } else {
         deviceInfo.message = `❌ Authentication failed: ${pollResult.error || 'Unknown error'}`;
         deviceInfo.access_token_received = false;
@@ -644,7 +614,7 @@ export class PlanformMCPServer {
           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.` 
+            error: `Max wait time (${maxWaitSeconds}s) reached. Please approve in browser and use poll_auth_token manually (optional), or try sign_in again.` 
           };
         } else {
           this.logger.warn('Device code expired while waiting for approval');
@@ -691,6 +661,63 @@ export class PlanformMCPServer {
     }
   }
 
+  /**
+   * Returns the current diagram data (nodes, links, etc.). Throws if no diagram is selected.
+   * Used to resolve node names to uuids/labels under the hood.
+   */
+  private async getCurrentDiagramData(): Promise<{ uuid: string; nodes: Array<{ uuid: string; label: string; name: string | null }>; links: Array<{ uuid: string }> }> {
+    const diagramUuid = this.currentDiagramUuid;
+    if (!diagramUuid) {
+      throw new Error('No diagram selected. Create one with create_diagram or open one with open_diagram first.');
+    }
+    const diagram = await this.apiClient.getDiagram(diagramUuid);
+    return {
+      uuid: diagram.uuid,
+      nodes: diagram.nodes.map((n) => ({ uuid: n.uuid, label: n.label, name: n.name })),
+      links: diagram.links.map((l) => ({ uuid: l.uuid })),
+    };
+  }
+
+  /**
+   * Resolve node_identifier (name or UUID) to node UUID using the current diagram.
+   */
+  private async resolveNodeToUuid(diagramUuid: string, nodeIdentifier: string): Promise<string> {
+    if (UUID_REGEX.test(nodeIdentifier)) {
+      return nodeIdentifier;
+    }
+    const data = await this.getCurrentDiagramData();
+    if (data.uuid !== diagramUuid) {
+      throw new Error('Current diagram changed; resolve again.');
+    }
+    const byName = data.nodes.find(
+      (n) => n.name === nodeIdentifier || n.name?.toLowerCase() === String(nodeIdentifier).toLowerCase()
+    );
+    if (!byName) {
+      throw new Error(`No node named "${nodeIdentifier}" in the current diagram. Use node names or UUIDs.`);
+    }
+    return byName.uuid;
+  }
+
+  /**
+   * Resolve node reference (name or label like n-1) to node label for create_link.
+   */
+  private async resolveNodeToLabel(diagramUuid: string, nodeRef: string): Promise<string> {
+    if (NODE_LABEL_REGEX.test(nodeRef)) {
+      return nodeRef;
+    }
+    const data = await this.getCurrentDiagramData();
+    if (data.uuid !== diagramUuid) {
+      throw new Error('Current diagram changed; resolve again.');
+    }
+    const byName = data.nodes.find(
+      (n) => n.name === nodeRef || n.name?.toLowerCase() === String(nodeRef).toLowerCase()
+    );
+    if (!byName) {
+      throw new Error(`No node named "${nodeRef}" in the current diagram. Use node names (e.g. "User") or labels (e.g. n-1).`);
+    }
+    return byName.label;
+  }
+
   /**
    * Start automatic background polling for device token (kept for backward compatibility)
    * @deprecated Use pollUntilApproved for synchronous polling
@@ -811,20 +838,24 @@ export class PlanformMCPServer {
   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');
+    if (!args.title) {
+      throw new Error('title is required');
+    }
+    if (!args.type) {
+      throw new Error('type is required');
     }
 
     try {
-      if (!args.type) {
-        throw new Error('type is required');
-      }
 
-      const response = await this.apiClient.createDiagram(args.user_uuid, {
+      const userUuid = args.user_uuid ?? this.sessionUserUuid;
+      if (!userUuid) {
+        throw new Error('Not authenticated. Call sign_in first, then approve in the browser.');
+      }
+      const response = await this.apiClient.createDiagram(userUuid, {
         title: args.title,
         type: args.type,
       });
-      
+      this.currentDiagramUuid = response.uuid;
       // Return the response in the format specified by the design document
       const result = {
         diagram_uuid: response.uuid,
@@ -851,14 +882,33 @@ export class PlanformMCPServer {
 
   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);
-      
+      let diagramUuid: string;
+      const identifier = args.diagram_identifier ?? args.diagram_uuid;
+      if (!identifier) {
+        diagramUuid = this.currentDiagramUuid ?? '';
+        if (!diagramUuid) {
+          throw new Error('No diagram selected. Create one with create_diagram or open one with open_diagram(diagram_identifier) first.');
+        }
+      } else if (UUID_REGEX.test(identifier)) {
+        diagramUuid = identifier;
+      } else {
+        const userUuid = this.sessionUserUuid;
+        if (!userUuid) {
+          throw new Error('Not authenticated. Call sign_in first, then approve in the browser.');
+        }
+        const listRes = await this.apiClient.getUserDiagrams(userUuid, 1, 100);
+        const byTitle = listRes.diagrams.find(
+          (d) => d.title === identifier || d.title?.toLowerCase() === String(identifier).toLowerCase()
+        );
+        if (!byTitle) {
+          throw new Error(`No diagram found with title "${identifier}". Use list_diagrams to see available diagrams.`);
+        }
+        diagramUuid = byTitle.uuid;
+      }
+      const response = await this.apiClient.getDiagram(diagramUuid);
+      this.currentDiagramUuid = response.uuid;
       // Return the response in the format specified by the design document
       const result = {
         diagram: {
@@ -874,7 +924,6 @@ export class PlanformMCPServer {
           links: response.links,
         },
       };
-      
       return {
         content: [
           {
@@ -892,31 +941,31 @@ export class PlanformMCPServer {
 
   private async handleDiagramsList(args: any): Promise<CallToolResult> {
     this.logger.info('Diagrams list requested');
-    
-    if (!args.user_uuid) {
-      throw new Error('user_uuid is required');
+    const userUuid = args.user_uuid ?? this.sessionUserUuid;
+    if (!userUuid) {
+      throw new Error('Not authenticated. Call sign_in first, then approve in the browser.');
     }
 
     try {
       const response = await this.apiClient.getUserDiagrams(
-        args.user_uuid,
+        userUuid,
         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 => ({
+        items: response.diagrams.map((diagram) => ({
           diagram_uuid: diagram.uuid,
-          external_id: diagram.label, // Using label as external_id for now
+          external_id: diagram.label,
           title: diagram.title,
           type: diagram.type,
-          version: 1, // Default version
+          version: 1,
           updated_at: diagram.updatedAt,
         })),
-        next_page: response.pagination.page < response.pagination.totalPages 
-          ? (response.pagination.page + 1).toString() 
-          : undefined,
+        next_page:
+          response.pagination.page < response.pagination.totalPages
+            ? (response.pagination.page + 1).toString()
+            : undefined,
       };
       
       return {
@@ -936,9 +985,12 @@ export class PlanformMCPServer {
 
   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');
+    if (!args.kind) {
+      throw new Error('kind is required');
+    }
+    const diagramUuid = args.diagram_uuid ?? this.currentDiagramUuid;
+    if (!diagramUuid) {
+      throw new Error('No diagram selected. Create one with create_diagram or open one with open_diagram first.');
     }
 
     try {
@@ -953,12 +1005,11 @@ export class PlanformMCPServer {
         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);
+      const response = await this.apiClient.createNode(diagramUuid, requestPayload);
 
       return {
         content: [
@@ -980,13 +1031,21 @@ export class PlanformMCPServer {
 
   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');
+    if (!args.patch) {
+      throw new Error('patch is required');
+    }
+    const nodeIdentifier = args.node_identifier ?? args.node_id;
+    if (!nodeIdentifier) {
+      throw new Error('node_identifier is required (use the node name, e.g. "User", or its UUID).');
+    }
+    const diagramUuid = args.diagram_uuid ?? this.currentDiagramUuid;
+    if (!diagramUuid) {
+      throw new Error('No diagram selected. Create one with create_diagram or open one with open_diagram first.');
     }
 
     try {
-      const response = await this.apiClient.updateNode(args.diagram_uuid, args.node_id, args.patch);
+      const nodeUuid = await this.resolveNodeToUuid(diagramUuid, nodeIdentifier);
+      const response = await this.apiClient.updateNode(diagramUuid, nodeUuid, args.patch);
       
       return {
         content: [
@@ -1008,13 +1067,21 @@ export class PlanformMCPServer {
 
   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');
+    if (!args.structural_fields) {
+      throw new Error('structural_fields is required');
+    }
+    const nodeIdentifier = args.node_identifier ?? args.node_id;
+    if (!nodeIdentifier) {
+      throw new Error('node_identifier is required (use the node name, e.g. "User", or its UUID).');
+    }
+    const diagramUuid = args.diagram_uuid ?? this.currentDiagramUuid;
+    if (!diagramUuid) {
+      throw new Error('No diagram selected. Create one with create_diagram or open one with open_diagram first.');
     }
 
     try {
-      const response = await this.apiClient.verifyNode(args.diagram_uuid, args.node_id, args.structural_fields);
+      const nodeUuid = await this.resolveNodeToUuid(diagramUuid, nodeIdentifier);
+      const response = await this.apiClient.verifyNode(diagramUuid, nodeUuid, args.structural_fields);
       
       return {
         content: [
@@ -1033,13 +1100,18 @@ export class PlanformMCPServer {
 
   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');
+    const nodeIdentifier = args.node_identifier ?? args.node_id;
+    if (!nodeIdentifier) {
+      throw new Error('node_identifier is required (use the node name, e.g. "User", or its UUID).');
+    }
+    const diagramUuid = args.diagram_uuid ?? this.currentDiagramUuid;
+    if (!diagramUuid) {
+      throw new Error('No diagram selected. Create one with create_diagram or open one with open_diagram first.');
     }
 
     try {
-      const response = await this.apiClient.deleteNode(args.diagram_uuid, args.node_id);
+      const nodeUuid = await this.resolveNodeToUuid(diagramUuid, nodeIdentifier);
+      const response = await this.apiClient.deleteNode(diagramUuid, nodeUuid);
       
       return {
         content: [
@@ -1058,22 +1130,26 @@ export class PlanformMCPServer {
 
   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');
+    if (!args.kind || !args.from || !args.to) {
+      throw new Error('kind, from, and to are required (from/to can be node names, e.g. "User" and "Account").');
+    }
+    const diagramUuid = args.diagram_uuid ?? this.currentDiagramUuid;
+    if (!diagramUuid) {
+      throw new Error('No diagram selected. Create one with create_diagram or open one with open_diagram first.');
     }
 
-    // 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 fromLabel = await this.resolveNodeToLabel(diagramUuid, args.from);
+      const toLabel = await this.resolveNodeToLabel(diagramUuid, args.to);
       const requestBody: any = {
         kind: args.kind,
-        fromNode: args.from,
-        toNode: args.to,
+        fromNode: fromLabel,
+        toNode: toLabel,
         name: args.label || null,
         meta: args.meta || null,
         fromMultiplicity: args.fromMultiplicity || null,
@@ -1084,8 +1160,7 @@ export class PlanformMCPServer {
       if (args.directional !== undefined) {
         requestBody.directional = args.directional;
       }
-      
-      const response = await this.apiClient.createLink(args.diagram_uuid, requestBody);
+      const response = await this.apiClient.createLink(diagramUuid, requestBody);
       
       return {
         content: [
@@ -1107,13 +1182,16 @@ export class PlanformMCPServer {
 
   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');
+    if (!args.link_id || !args.patch) {
+      throw new Error('link_id and patch are required (link_id comes from create_link or open_diagram response).');
+    }
+    const diagramUuid = args.diagram_uuid ?? this.currentDiagramUuid;
+    if (!diagramUuid) {
+      throw new Error('No diagram selected. Create one with create_diagram or open one with open_diagram first.');
     }
 
     try {
-      const response = await this.apiClient.updateLink(args.diagram_uuid, args.link_id, args.patch);
+      const response = await this.apiClient.updateLink(diagramUuid, args.link_id, args.patch);
       
       return {
         content: [
@@ -1135,13 +1213,16 @@ export class PlanformMCPServer {
 
   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');
+    if (!args.link_id || !args.structural_fields) {
+      throw new Error('link_id and structural_fields are required.');
+    }
+    const diagramUuid = args.diagram_uuid ?? this.currentDiagramUuid;
+    if (!diagramUuid) {
+      throw new Error('No diagram selected. Create one with create_diagram or open one with open_diagram first.');
     }
 
     try {
-      const response = await this.apiClient.verifyLink(args.diagram_uuid, args.link_id, args.structural_fields);
+      const response = await this.apiClient.verifyLink(diagramUuid, args.link_id, args.structural_fields);
       
       return {
         content: [
@@ -1160,13 +1241,16 @@ export class PlanformMCPServer {
 
   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');
+    if (!args.link_id) {
+      throw new Error('link_id is required (from create_link or open_diagram response).');
+    }
+    const diagramUuid = args.diagram_uuid ?? this.currentDiagramUuid;
+    if (!diagramUuid) {
+      throw new Error('No diagram selected. Create one with create_diagram or open one with open_diagram first.');
     }
 
     try {
-      const response = await this.apiClient.deleteLink(args.diagram_uuid, args.link_id);
+      const response = await this.apiClient.deleteLink(diagramUuid, args.link_id);
       
       return {
         content: [