@shirbarzur/planform-mcp-server 1.0.5 → 1.0.6

package/dist/server.js

@@ -4,11 +4,19 @@ import { ApiClient } from './api-client.js';
 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 {
     server;
     apiClient;
     logger;
     activePolling = new Map();
+    /** Set after successful sign_in; used for list_diagrams and create_diagram so callers need not pass user_uuid */
+    sessionUserUuid = null;
+    /** Set after create_diagram or open_diagram; used for node/link tools so callers need not pass diagram_uuid */
+    currentDiagramUuid = null;
     constructor() {
         this.server = new Server({
             name: process.env.MCP_SERVER_NAME || 'planform-mcp',
@@ -37,37 +45,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',
@@ -75,37 +83,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.',
+                    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 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)',
@@ -122,41 +104,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 title (e.g. "My class diagram")',
+                            },
+                            type: {
                                 type: 'string',
-                                description: 'Diagram UUID',
+                                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',
@@ -213,48 +207,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: {
-                                type: 'string',
-                                description: 'Diagram UUID',
-                            },
-                            node_id: {
+                            node_identifier: {
                                 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: {
+                            node_identifier: {
                                 type: 'string',
-                                description: 'Diagram UUID',
-                            },
-                            node_id: {
-                                type: 'string',
-                                description: 'Node ID',
+                                description: 'Node name (e.g. "User") or node ID.',
                             },
                             structural_fields: {
                                 type: 'object',
@@ -265,37 +251,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',
@@ -303,11 +281,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',
@@ -315,26 +293,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',
@@ -342,25 +316,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',
@@ -371,25 +341,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'],
                     },
                 },
             ];
@@ -402,35 +368,35 @@ export class PlanformMCPServer {
                 switch (request.params.name) {
                     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:
                         throw new Error(`Unknown tool: ${request.params.name}`);
@@ -542,6 +508,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'}`;
@@ -585,7 +554,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 {
@@ -636,6 +605,56 @@ 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.
+     */
+    async getCurrentDiagramData() {
+        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.
+     */
+    async resolveNodeToUuid(diagramUuid, nodeIdentifier) {
+        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.
+     */
+    async resolveNodeToLabel(diagramUuid, nodeRef) {
+        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
@@ -748,17 +767,22 @@ export class PlanformMCPServer {
     }
     async handleDiagramCreate(args) {
         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 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(args.user_uuid, {
+            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,
@@ -784,11 +808,32 @@ export class PlanformMCPServer {
     }
     async handleDiagramGet(args) {
         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;
+            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: {
@@ -821,19 +866,20 @@ export class PlanformMCPServer {
     }
     async handleDiagramsList(args) {
         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, args.page || 1, args.page_size || 10);
+            const response = await this.apiClient.getUserDiagrams(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
@@ -857,8 +903,12 @@ export class PlanformMCPServer {
     }
     async handleNodesCreate(args) {
         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 {
             const requestPayload = {
@@ -871,11 +921,10 @@ export class PlanformMCPServer {
                 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);
+            const response = await this.apiClient.createNode(diagramUuid, requestPayload);
             return {
                 content: [
                     {
@@ -896,11 +945,20 @@ export class PlanformMCPServer {
     }
     async handleNodeUpdate(args) {
         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: [
                     {
@@ -921,11 +979,20 @@ export class PlanformMCPServer {
     }
     async handleNodeVerify(args) {
         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: [
                     {
@@ -943,11 +1010,17 @@ export class PlanformMCPServer {
     }
     async handleNodeDelete(args) {
         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: [
                     {
@@ -965,19 +1038,24 @@ export class PlanformMCPServer {
     }
     async handleLinksCreate(args) {
         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 = {
                 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,
@@ -987,7 +1065,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: [
                     {
@@ -1008,11 +1086,15 @@ export class PlanformMCPServer {
     }
     async handleLinkUpdate(args) {
         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: [
                     {
@@ -1033,11 +1115,15 @@ export class PlanformMCPServer {
     }
     async handleLinkVerify(args) {
         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: [
                     {
@@ -1055,11 +1141,15 @@ export class PlanformMCPServer {
     }
     async handleLinkDelete(args) {
         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: [
                     {