@shirbarzur/planform-mcp-server 1.0.1

package/src/usage-examples.ts

@@ -0,0 +1,40 @@
+/**
+ * Usage examples for the Planform MCP. Exposed via server instructions and get_usage_examples tool.
+ */
+export const USAGE_EXAMPLES = `
+# Planform MCP – How to use
+
+## 1. Authentication (required first)
+
+Before listing or managing diagrams, the user must authenticate:
+
+1. Call **device_start** (no arguments). A browser window opens for the user to approve.
+2. After the user approves, the response includes **approved_user_uuid** and the token is stored automatically.
+3. Use **approved_user_uuid** from that response as **user_uuid** in all subsequent tools (diagrams_list, diagram_create, etc.).
+
+## 2. Example: List the user's diagrams
+
+1. **device_start** → user approves in browser → response includes \`approved_user_uuid\`.
+2. **diagrams_list** with \`user_uuid: "<approved_user_uuid from step 1>"\`.
+
+Example: \`diagrams_list({ "user_uuid": "abc-123-from-device_start" })\`
+
+## 3. Example: Create a diagram and add nodes
+
+1. **device_start** → get \`approved_user_uuid\`.
+2. **diagram_create** with \`user_uuid\`, \`title\`, \`type\` (e.g. "uml.class") → returns diagram info including \`diagram_uuid\`.
+3. **nodes_create** with \`diagram_uuid\`, \`kind\` ("class"|"interface"|"enum"), \`name\`, optional \`fields\` and \`methods\`.
+4. **links_create** to connect nodes: use **node labels** (e.g. \`n-1\`, \`n-2\`) for \`from\` and \`to\`, **not** node UUIDs; the backend expects labels and returns 400 if given UUIDs.
+
+## 4. Example: Fetch a diagram
+
+1. **device_start** (if not already authenticated).
+2. **diagram_get** with \`diagram_uuid\` (from diagrams_list or diagram_create).
+
+## Summary
+
+- **Always call device_start first** when the user wants to list/create/edit diagrams.
+- **user_uuid** in API tools = **approved_user_uuid** from the device_start response.
+- The access token is stored by the server after device_start; you do not pass it to other tools.
+- **links_create**: use **node labels** (e.g. n-1, n-2) for \`from\` and \`to\`, not node UUIDs; the backend returns 400 if given UUIDs.
+`;

package/test-execution-template.csv

@@ -0,0 +1,86 @@
+Test ID	Category	Test Case	Steps	Expected Result	Status	Notes	Browser	OS
+1.1	Health Checks	MCP Server Health Check	1. Call health_check tool with no arguments; 2. Verify response contains status: "healthy"; 3. Verify response includes server name and version; 4. Verify timestamp is present and valid	JSON response with status, server info, and timestamp			Chrome	Windows 10
+1.2	Health Checks	Backend API Health Check	1. Call backend_health_check tool with no arguments; 2. Verify backend API is reachable; 3. Verify response indicates backend is healthy	Successful response from backend API			Chrome	Windows 10
+1.2.1	Health Checks	Backend API Health Check (Offline)	1. Stop backend API; 2. Call backend_health_check tool; 3. Verify error is returned gracefully	Error response indicating backend is unavailable			Chrome	Windows 10
+2.1	Authentication	Device Flow Start	1. Call device_start tool with no arguments; 2. Verify response contains device_code, user_code, verification_uri, verification_uri_complete; 3. Verify expires_in is a positive number (typically 600 seconds); 4. Verify interval is a positive number (typically 3 seconds); 5. Verify user_code format (e.g., "ABCD-EFGH"); 6. Verify verification_uri is a valid URL	Complete device flow information returned			Chrome	Windows 10
+2.2	Authentication	Device Token Poll - Pending State	1. Start device flow (test 2.1); 2. Call device_token_poll with device_code from step 2.1 (before user approval); 3. Verify response indicates authorization_pending error	Error response with authorization_pending			Chrome	Windows 10
+2.3	Authentication	Device Token Poll - Approved State	1. Start device flow (test 2.1); 2. Approve via frontend; 3. Call device_token_poll with approved device_code; 4. Verify response contains access_token (JWT); 5. Verify token_type is "Bearer"; 6. Verify expires_in is present (typically 600 seconds); 7. Verify scope is "diagrams:write"; 8. Verify token is stored and used for subsequent authenticated requests	Valid JWT token returned			Chrome	Windows 10
+2.4	Authentication	Device Token Poll - Expired State	1. Start device flow (test 2.1); 2. Wait for expiry (>10 minutes) or manually expire; 3. Call device_token_poll with expired device_code; 4. Verify response indicates expired_token error	Error response with expired_token			Chrome	Windows 10
+2.5	Authentication	Device Token Poll - Denied State	1. Start device flow (test 2.1); 2. User denies access in frontend; 3. Call device_token_poll with denied device_code; 4. Verify response indicates access_denied error	Error response with access_denied			Chrome	Windows 10
+3.1	Diagram Operations	Create Diagram	1. Call diagram_create with user_uuid and title; 2. Verify response contains diagram_uuid, external_id, title, type, version; 3. Verify type defaults to "uml.class" if not specified; 4. Verify custom type is accepted	New diagram created with valid UUID and metadata			Chrome	Windows 10
+3.1.1	Diagram Operations	Create Diagram - Default Type	1. Call diagram_create with user_uuid and title (no type specified); 2. Verify type defaults to "uml.class"	Type defaults to "uml.class"			Chrome	Windows 10
+3.1.2	Diagram Operations	Create Diagram - Custom Type	1. Call diagram_create with user_uuid, title, and custom type; 2. Verify custom type is accepted	Custom type is stored correctly			Chrome	Windows 10
+3.1.3	Diagram Operations	Create Diagram - Missing user_uuid	1. Call diagram_create with only title; 2. Verify error is returned	Error: missing user_uuid			Chrome	Windows 10
+3.1.4	Diagram Operations	Create Diagram - Missing title	1. Call diagram_create with only user_uuid; 2. Verify error is returned	Error: missing title			Chrome	Windows 10
+3.2	Diagram Operations	Get Diagram	1. Call diagram_get with diagram_uuid; 2. Verify response contains diagram object with meta, nodes, links; 3. Verify meta contains uuid, title, type, createdAt, updatedAt, user; 4. Verify nodes is an array; 5. Verify links is an array	Complete diagram data returned			Chrome	Windows 10
+3.2.1	Diagram Operations	Get Diagram - Invalid UUID	1. Call diagram_get with invalid/non-existent diagram_uuid; 2. Verify error is returned	Error: diagram not found			Chrome	Windows 10
+3.2.2	Diagram Operations	Get Diagram - Missing UUID	1. Call diagram_get with no parameters; 2. Verify error is returned	Error: missing diagram_uuid			Chrome	Windows 10
+3.3	Diagram Operations	List Diagrams	1. Call diagrams_list with user_uuid; 2. Verify response contains items array; 3. Verify each item has diagram_uuid, external_id, title, type, version, updated_at	List of user's diagrams returned			Chrome	Windows 10
+3.3.1	Diagram Operations	List Diagrams - Pagination	1. Call diagrams_list with user_uuid, page, and page_size parameters; 2. Verify pagination works correctly; 3. Verify next_page is present when more pages exist	Pagination works correctly			Chrome	Windows 10
+3.3.2	Diagram Operations	List Diagrams - Status Filter	1. Call diagrams_list with user_uuid and status filter ("active" or "archived"); 2. Verify only diagrams with matching status are returned	Filtered results by status			Chrome	Windows 10
+3.3.3	Diagram Operations	List Diagrams - Invalid user_uuid	1. Call diagrams_list with invalid/non-existent user_uuid; 2. Verify error is returned	Error: user not found			Chrome	Windows 10
+4.1	Node Operations	Create Node - Class	1. Call nodes_create with diagram_uuid, kind: "class", name; 2. Verify response contains node object with uuid, kind, name, grid, size; 3. Verify code_status is "implemented" (MCP auth) or "new" (Firebase auth); 4. Verify grid contains row, col, rowSpan, colSpan; 5. Verify size contains w, h (computed by backend)	Node created with grid placement and computed size			Chrome	Windows 10
+4.1.1	Node Operations	Create Node - Missing diagram_uuid	1. Call nodes_create with kind and name but no diagram_uuid; 2. Verify error is returned	Error: missing diagram_uuid			Chrome	Windows 10
+4.1.2	Node Operations	Create Node - Missing kind	1. Call nodes_create with diagram_uuid and name but no kind; 2. Verify error is returned	Error: missing kind			Chrome	Windows 10
+4.1.3	Node Operations	Create Node - Invalid kind	1. Call nodes_create with invalid kind value; 2. Verify error is returned	Error: invalid kind			Chrome	Windows 10
+4.2	Node Operations	Create Node - Interface	1. Call nodes_create with kind: "interface"; 2. Verify node is placed in interfaces zone (row < 0); 3. Verify code_status is correct based on auth type	Interface node created in correct zone			Chrome	Windows 10
+4.3	Node Operations	Create Node - Enum	1. Call nodes_create with kind: "enum"; 2. Verify node is placed in enums zone (col < 0); 3. Verify code_status is correct based on auth type	Enum node created in correct zone			Chrome	Windows 10
+4.4	Node Operations	Create Node - With Fields	1. Call nodes_create with fields array containing name, type, visibility, static; 2. Verify all fields are stored correctly; 3. Verify computed size accounts for content	Node created with fields stored correctly			Chrome	Windows 10
+4.4.1	Node Operations	Create Node - With Methods	1. Call nodes_create with methods array containing name, returns, visibility, static, params; 2. Verify all methods are stored correctly; 3. Verify computed size accounts for content	Node created with methods stored correctly			Chrome	Windows 10
+4.5	Node Operations	Update Node	1. Call node_update with patch containing name, fields, or methods; 2. Verify response contains updated node object; 3. Verify changes are persisted	Node updated successfully			Chrome	Windows 10
+4.5.1	Node Operations	Update Node - Optimistic Concurrency	1. Call node_update with if_version parameter; 2. Verify optimistic concurrency control works	Optimistic concurrency prevents overwrites			Chrome	Windows 10
+4.5.2	Node Operations	Update Node - Missing Parameters	1. Call node_update with missing required parameters; 2. Verify error is returned	Error: missing required parameters			Chrome	Windows 10
+4.6	Node Operations	Verify Node	1. Call node_verify with structural_fields matching code; 2. Verify code_status becomes "implemented"	Node status updated to implemented			Chrome	Windows 10
+4.6.1	Node Operations	Verify Node - Diff Detected	1. Call node_verify with diff_detected: true; 2. Verify code_status becomes "out_of_sync"	Node status updated to out_of_sync			Chrome	Windows 10
+4.6.2	Node Operations	Verify Node - Missing structural_fields	1. Call node_verify without structural_fields; 2. Verify error is returned	Error: missing structural_fields			Chrome	Windows 10
+4.7	Node Operations	Delete Node - Hard Delete (NEW status)	1. Create node with code_status: "new"; 2. Call node_delete; 3. Verify response indicates deletion_type: "hard"; 4. Verify node is removed from diagram; 5. Verify connected links are deleted (cascading); 6. Verify connected_links_deleted array in response	Node and connected links hard deleted			Chrome	Windows 10
+4.8	Node Operations	Delete Node - Soft Delete (IMPLEMENTED, FE token)	1. Create node with code_status: "implemented"; 2. Call node_delete with Firebase token; 3. Verify response indicates deletion_type: "soft"; 4. Verify new_status: "user_deleted"; 5. Verify node still exists but marked for deletion	Node soft deleted to user_deleted status			Chrome	Windows 10
+4.9	Node Operations	Delete Node - Transition (IMPLEMENTED, MCP token)	1. Create node with code_status: "implemented"; 2. Call node_delete with MCP token; 3. Verify response indicates deletion_type: "transition"; 4. Verify new_status: "removed_from_code"; 5. Verify node status changed but not deleted	Node status transitioned to removed_from_code			Chrome	Windows 10
+5.1	Link Operations	Create Link - Association	1. Call links_create with kind: "association", from, to; 2. Verify response contains link object with uuid, kind, from, to	Link created between nodes			Chrome	Windows 10
+5.1.1	Link Operations	Create Link - Aggregation	1. Call links_create with kind: "aggregation"; 2. Verify link is created correctly	Aggregation link created			Chrome	Windows 10
+5.1.2	Link Operations	Create Link - Composition	1. Call links_create with kind: "composition"; 2. Verify link is created correctly	Composition link created			Chrome	Windows 10
+5.1.3	Link Operations	Create Link - Inheritance	1. Call links_create with kind: "inheritance"; 2. Verify link is created correctly	Inheritance link created			Chrome	Windows 10
+5.1.4	Link Operations	Create Link - Implements	1. Call links_create with kind: "implements"; 2. Verify link is created correctly	Implements link created			Chrome	Windows 10
+5.1.5	Link Operations	Create Link - Dependency	1. Call links_create with kind: "dependency"; 2. Verify link is created correctly	Dependency link created			Chrome	Windows 10
+5.1.6	Link Operations	Create Link - With Label/Directional	1. Call links_create with label and directional parameters; 2. Verify optional parameters are stored correctly	Link created with label and directional flag			Chrome	Windows 10
+5.1.7	Link Operations	Create Link - With Multiplicity	1. Call links_create with fromMultiplicity and toMultiplicity; 2. Verify multiplicity is stored correctly	Link created with multiplicity			Chrome	Windows 10
+5.1.8	Link Operations	Create Link - Invalid Node IDs	1. Call links_create with invalid from or to node IDs; 2. Verify error is returned	Error: invalid node IDs			Chrome	Windows 10
+5.1.9	Link Operations	Create Link - Missing Parameters	1. Call links_create with missing required parameters; 2. Verify error is returned	Error: missing required parameters			Chrome	Windows 10
+5.2	Link Operations	Update Link	1. Call link_update with patch containing label, directional, etc.; 2. Verify response contains updated link object; 3. Verify changes are persisted	Link updated successfully			Chrome	Windows 10
+5.2.1	Link Operations	Update Link - Optimistic Concurrency	1. Call link_update with if_version parameter; 2. Verify optimistic concurrency control works	Optimistic concurrency prevents overwrites			Chrome	Windows 10
+5.3	Link Operations	Verify Link	1. Call link_verify with structural_fields matching code; 2. Verify code_status becomes "implemented"	Link status updated to implemented			Chrome	Windows 10
+5.3.1	Link Operations	Verify Link - Diff Detected	1. Call link_verify with diff_detected: true; 2. Verify code_status becomes "out_of_sync"	Link status updated to out_of_sync			Chrome	Windows 10
+5.4	Link Operations	Delete Link - Hard Delete (NEW status)	1. Create link with NEW/REMOVED_FROM_CODE status; 2. Call link_delete; 3. Verify hard delete occurs	Link hard deleted			Chrome	Windows 10
+5.4.1	Link Operations	Delete Link - Soft Delete (IMPLEMENTED, FE token)	1. Create link with IMPLEMENTED/OUT_OF_SYNC status; 2. Call link_delete with FE token; 3. Verify soft delete to user_deleted	Link soft deleted to user_deleted			Chrome	Windows 10
+5.4.2	Link Operations	Delete Link - Transition (IMPLEMENTED, MCP token)	1. Create link with IMPLEMENTED/OUT_OF_SYNC status; 2. Call link_delete with MCP token; 3. Verify transition to removed_from_code	Link status transitioned to removed_from_code			Chrome	Windows 10
+5.4.3	Link Operations	Delete Link - Hard Delete (USER_DELETED, MCP token)	1. Create link with USER_DELETED status; 2. Call link_delete with MCP token; 3. Verify hard delete occurs	Link hard deleted			Chrome	Windows 10
+5.4.4	Link Operations	Delete Link - No Change (USER_DELETED, FE token)	1. Create link with USER_DELETED status; 2. Call link_delete with FE token; 3. Verify no change occurs	No change (already marked for deletion)			Chrome	Windows 10
+6.1	Error Handling	Invalid Parameters - Missing Required	1. Test all tools with missing required parameters; 2. Verify error messages are clear and helpful	Appropriate error messages for invalid inputs			Chrome	Windows 10
+6.1.1	Error Handling	Invalid Parameters - Wrong Type	1. Test tools with invalid parameter types (string instead of number, etc.); 2. Verify error messages are clear	Appropriate error messages for wrong types			Chrome	Windows 10
+6.1.2	Error Handling	Invalid Parameters - Invalid Enum	1. Test tools with invalid enum values; 2. Verify error messages are clear	Appropriate error messages for invalid enums			Chrome	Windows 10
+6.2	Error Handling	Authentication Errors - No Token	1. Test authenticated endpoints without token; 2. Verify proper authentication error response	Authentication error returned			Chrome	Windows 10
+6.2.1	Error Handling	Authentication Errors - Expired Token	1. Test authenticated endpoints with expired token; 2. Verify proper error response	Expired token error returned			Chrome	Windows 10
+6.2.2	Error Handling	Authentication Errors - Invalid Token	1. Test authenticated endpoints with invalid token format; 2. Verify proper error response	Invalid token error returned			Chrome	Windows 10
+6.2.3	Error Handling	Authentication Errors - Wrong User	1. Test authenticated endpoints with token for wrong user; 2. Verify proper error response	Authorization error returned			Chrome	Windows 10
+6.3	Error Handling	Backend Connectivity - Offline	1. Stop backend API; 2. Test all tools; 3. Verify graceful error handling and logging	Graceful error handling when backend is unavailable			Chrome	Windows 10
+6.3.1	Error Handling	Backend Connectivity - 500 Error	1. Configure backend to return 500 errors; 2. Test tools; 3. Verify error handling	Error handling for server errors			Chrome	Windows 10
+6.3.2	Error Handling	Backend Connectivity - Timeout	1. Configure backend to timeout; 2. Test tools; 3. Verify timeout handling	Timeout error handled gracefully			Chrome	Windows 10
+6.4	Error Handling	Resource Not Found - Diagram	1. Test operations with non-existent diagram_uuid; 2. Verify appropriate 404 or not found error message	Appropriate not found error message			Chrome	Windows 10
+6.4.1	Error Handling	Resource Not Found - Node	1. Test operations with non-existent node_id; 2. Verify appropriate 404 or not found error message	Appropriate not found error message			Chrome	Windows 10
+6.4.2	Error Handling	Resource Not Found - Link	1. Test operations with non-existent link_id; 2. Verify appropriate 404 or not found error message	Appropriate not found error message			Chrome	Windows 10
+6.4.3	Error Handling	Resource Not Found - User	1. Test operations with non-existent user_uuid; 2. Verify appropriate 404 or not found error message	Appropriate not found error message			Chrome	Windows 10
+7.1	Integration	Complete Workflow - Create Diagram with Nodes and Links	1. Start device flow; 2. Approve via frontend; 3. Poll for token; 4. Create diagram; 5. Create multiple nodes (class, interface, enum); 6. Create links between nodes; 7. Verify diagram structure; 8. Update nodes and links; 9. Delete some nodes/links; 10. Verify final state	Complete workflow executes successfully			Chrome	Windows 10
+7.2	Integration	Concurrent Operations	1. Create multiple nodes simultaneously; 2. Update same node from multiple sources; 3. Test optimistic concurrency with if_version; 4. Verify no data corruption	Concurrent operations handled correctly			Chrome	Windows 10
+7.3	Integration	Status Transitions	1. Create node with status "new"; 2. Verify node → "implemented"; 3. Edit node → "out_of_sync"; 4. Verify node → "implemented"; 5. Delete from code → "removed_from_code"; 6. Verify node → "implemented"; 7. Test all status transitions per design document	Status transitions follow design specification			Chrome	Windows 10
+8.1	Edge Cases	Large Diagrams - 50+ Nodes	1. Create diagram with 50+ nodes; 2. Verify performance and response times; 3. Test pagination with large result sets	System handles large diagrams efficiently			Chrome	Windows 10
+8.1.1	Edge Cases	Large Diagrams - 100+ Links	1. Create diagram with 100+ links; 2. Verify performance and response times	System handles large number of links efficiently			Chrome	Windows 10
+8.1.2	Edge Cases	Large Diagrams - Performance	1. Test all tools with large diagrams; 2. Measure response times; 3. Verify acceptable performance	Performance is acceptable for large diagrams			Chrome	Windows 10
+8.2	Edge Cases	Special Characters - Node Names	1. Test node names with special characters; 2. Verify special characters are handled correctly	Special characters handled correctly			Chrome	Windows 10
+8.2.1	Edge Cases	Special Characters - Link Labels	1. Test link labels with special characters; 2. Verify special characters are handled correctly	Special characters handled correctly			Chrome	Windows 10
+8.2.2	Edge Cases	Special Characters - Diagram Titles	1. Test diagram titles with Unicode; 2. Verify Unicode is handled correctly	Unicode handled correctly			Chrome	Windows 10
+8.3	Edge Cases	Empty States - Empty Diagram	1. Test operations on empty diagram; 2. Verify empty states are handled gracefully	Empty states handled gracefully			Chrome	Windows 10
+8.3.1	Edge Cases	Empty States - No Diagrams	1. Test listing diagrams for user with no diagrams; 2. Verify empty list is returned	Empty list returned gracefully			Chrome	Windows 10
+8.3.2	Edge Cases	Empty States - Node No Fields/Methods	1. Test node with no fields/methods; 2. Verify node is created correctly	Node created correctly without fields/methods			Chrome	Windows 10
+8.4	Edge Cases	Grid Placement - Zone Verification	1. Create multiple nodes and verify zone placement; 2. Verify interfaces at row < 0, enums at col < 0, classes at origin	Grid placement follows zone rules			Chrome	Windows 10
+8.4.1	Edge Cases	Grid Placement - No Overlap	1. Create multiple nodes; 2. Verify nodes don't overlap; 3. Verify grid coordinates are unique	Nodes don't overlap			Chrome	Windows 10
+8.4.2	Edge Cases	Grid Placement - Coordinate Consistency	1. Create multiple nodes; 2. Verify grid coordinates are consistent; 3. Verify coordinates don't change unexpectedly	Grid coordinates are consistent			Chrome	Windows 10

package/test-quick-reference.md

@@ -0,0 +1,214 @@
+# Planform MCP Server - Test Quick Reference Guide
+
+This is a quick reference guide for manual testers. Use this alongside the detailed test execution template.
+
+## Test Status Codes
+- **PASS** ✓ - Test passed
+- **FAIL** ✗ - Test failed
+- **BLOCKED** ⚠ - Cannot execute
+- **SKIP** ⊘ - Skipped
+- **IN PROGRESS** ⟳ - Currently testing
+
+---
+
+## 1. Health Checks (3 tests)
+
+| ID | Tool | Quick Check |
+|----|------|-------------|
+| 1.1 | `health_check` | Returns status: "healthy" with server info |
+| 1.2 | `backend_health_check` | Backend API responds successfully |
+| 1.2.1 | `backend_health_check` | Returns error when backend offline |
+
+---
+
+## 2. Authentication Flow (5 tests)
+
+| ID | Tool | Quick Check |
+|----|------|-------------|
+| 2.1 | `device_start` | Returns device_code, user_code, verification_uri |
+| 2.2 | `device_token_poll` | Returns "authorization_pending" before approval |
+| 2.3 | `device_token_poll` | Returns access_token JWT after approval |
+| 2.4 | `device_token_poll` | Returns "expired_token" after expiry |
+| 2.5 | `device_token_poll` | Returns "access_denied" if user denied |
+
+**Prerequisites for 2.3-2.5:** Need device_code from 2.1
+
+---
+
+## 3. Diagram Operations (12 tests)
+
+| ID | Tool | Parameters | Expected Response |
+|----|------|------------|-------------------|
+| 3.1 | `diagram_create` | user_uuid, title | diagram_uuid, external_id, title, type, version |
+| 3.1.1 | `diagram_create` | user_uuid, title (no type) | type defaults to "uml.class" |
+| 3.1.2 | `diagram_create` | user_uuid, title, type | Custom type accepted |
+| 3.1.3 | `diagram_create` | title only | Error: missing user_uuid |
+| 3.1.4 | `diagram_create` | user_uuid only | Error: missing title |
+| 3.2 | `diagram_get` | diagram_uuid | diagram with meta, nodes[], links[] |
+| 3.2.1 | `diagram_get` | invalid UUID | Error: not found |
+| 3.2.2 | `diagram_get` | no params | Error: missing diagram_uuid |
+| 3.3 | `diagrams_list` | user_uuid | items[] with pagination |
+| 3.3.1 | `diagrams_list` | user_uuid, page, page_size | Pagination works |
+| 3.3.2 | `diagrams_list` | user_uuid, status | Filter by status works |
+| 3.3.3 | `diagrams_list` | invalid user_uuid | Error: not found |
+
+---
+
+## 4. Node Operations (16 tests)
+
+| ID | Tool | Key Parameters | Expected Behavior |
+|----|------|----------------|-------------------|
+| 4.1 | `nodes_create` | diagram_uuid, kind: "class" | Node created with grid, size, code_status |
+| 4.1.1-4.1.3 | `nodes_create` | Missing/invalid params | Appropriate errors |
+| 4.2 | `nodes_create` | kind: "interface" | Placed in interfaces zone (row < 0) |
+| 4.3 | `nodes_create` | kind: "enum" | Placed in enums zone (col < 0) |
+| 4.4 | `nodes_create` | With fields array | Fields stored correctly |
+| 4.4.1 | `nodes_create` | With methods array | Methods stored correctly |
+| 4.5 | `node_update` | diagram_uuid, node_id, patch | Node updated, changes persisted |
+| 4.5.1 | `node_update` | With if_version | Optimistic concurrency works |
+| 4.6 | `node_verify` | structural_fields matching | code_status → "implemented" |
+| 4.6.1 | `node_verify` | diff_detected: true | code_status → "out_of_sync" |
+| 4.7 | `node_delete` | NEW status node | Hard delete + cascading links |
+| 4.8 | `node_delete` | IMPLEMENTED + FE token | Soft delete → "user_deleted" |
+| 4.9 | `node_delete` | IMPLEMENTED + MCP token | Transition → "removed_from_code" |
+
+**Node Status Flow:**
+- new → (verify) → implemented
+- implemented → (edit) → out_of_sync
+- implemented → (MCP delete) → removed_from_code
+- out_of_sync → (verify) → implemented
+
+---
+
+## 5. Link Operations (19 tests)
+
+| ID | Tool | Key Parameters | Expected Behavior |
+|----|------|----------------|-------------------|
+| 5.1 | `links_create` | kind: "association", from, to | Link created |
+| 5.1.1-5.1.5 | `links_create` | All link kinds | All kinds work |
+| 5.1.6 | `links_create` | With label, directional | Optional params work |
+| 5.1.7 | `links_create` | With multiplicity | Multiplicity stored |
+| 5.1.8 | `links_create` | Invalid node IDs | Error: invalid nodes |
+| 5.2 | `link_update` | diagram_uuid, link_id, patch | Link updated |
+| 5.3 | `link_verify` | structural_fields matching | code_status → "implemented" |
+| 5.4 | `link_delete` | Various statuses + tokens | Status-based deletion logic |
+
+**Link Kinds:** association, aggregation, composition, inheritance, implements, dependency
+
+---
+
+## 6. Error Handling (13 tests)
+
+| ID | Category | Test Focus |
+|----|----------|------------|
+| 6.1 | Invalid Parameters | Missing required, wrong types, invalid enums |
+| 6.2 | Authentication | No token, expired, invalid, wrong user |
+| 6.3 | Backend Connectivity | Offline, 500 errors, timeouts |
+| 6.4 | Resource Not Found | Invalid UUIDs for diagram/node/link/user |
+
+**Key:** Test error messages are clear and helpful
+
+---
+
+## 7. Integration Tests (3 tests)
+
+| ID | Test | Scope |
+|----|------|-------|
+| 7.1 | Complete Workflow | Full end-to-end: auth → create → nodes → links → verify |
+| 7.2 | Concurrent Operations | Multiple simultaneous requests, no corruption |
+| 7.3 | Status Transitions | All status transitions per design doc |
+
+---
+
+## 8. Edge Cases (10 tests)
+
+| ID | Category | Test Focus |
+|----|----------|------------|
+| 8.1 | Large Diagrams | 50+ nodes, 100+ links, performance |
+| 8.2 | Special Characters | Unicode, special chars in names/labels |
+| 8.3 | Empty States | Empty diagrams, no diagrams, minimal nodes |
+| 8.4 | Grid Placement | Zone placement, no overlap, consistency |
+
+---
+
+## Common Test Data Fields
+
+Record these as you test:
+- **User UUID**: _________________
+- **Diagram UUID**: _________________
+- **Node IDs**: _________________
+- **Link IDs**: _________________
+- **Device Code**: _________________
+- **User Code**: _________________
+- **Access Token**: _________________
+
+---
+
+## Quick Test Execution Order
+
+### Phase 1: Setup & Health (Start Here)
+1. 1.1, 1.2 - Health checks
+2. 2.1 - Start device flow
+
+### Phase 2: Authentication
+3. 2.2 - Poll pending (before approval)
+4. [Approve in frontend]
+5. 2.3 - Poll approved (get token)
+6. 2.4, 2.5 - Error cases (optional)
+
+### Phase 3: Basic Operations
+7. 3.1 - Create diagram
+8. 3.2 - Get diagram
+9. 3.3 - List diagrams
+10. 4.1, 4.2, 4.3 - Create nodes (class, interface, enum)
+11. 5.1 - Create links
+
+### Phase 4: Advanced Operations
+12. 4.5 - Update nodes
+13. 4.6 - Verify nodes
+14. 5.2 - Update links
+15. 5.3 - Verify links
+
+### Phase 5: Deletion & Status
+16. 4.7, 4.8, 4.9 - Delete nodes (various statuses)
+17. 5.4 - Delete links (various statuses)
+
+### Phase 6: Error Cases
+18. 6.1-6.4 - Error handling tests
+
+### Phase 7: Integration & Edge Cases
+19. 7.1 - Complete workflow
+20. 7.2, 7.3 - Integration tests
+21. 8.1-8.4 - Edge cases
+
+---
+
+## Critical Test Points
+
+⚠️ **Pay Special Attention To:**
+1. Status-based deletion logic (complex, see design doc)
+2. Grid placement zones (interfaces: row < 0, enums: col < 0, classes: origin)
+3. Code status transitions (new → implemented → out_of_sync, etc.)
+4. Token authentication (MCP vs Firebase tokens behave differently)
+5. Cascading deletes (hard delete of node should delete connected links)
+
+---
+
+## Common Issues to Watch For
+
+- **Grid coordinates**: Verify nodes are in correct zones
+- **Code status**: Check it matches auth type (MCP = "implemented", FE = "new")
+- **Token expiry**: Device flow tokens expire in 10 minutes
+- **Pagination**: Verify next_page appears when more results exist
+- **Error messages**: Should be clear and actionable
+
+---
+
+## Notes Template
+
+For each test, note:
+- **Actual Response**: What you got
+- **Deviations**: Any differences from expected
+- **Performance**: Response times if relevant
+- **Bugs**: Document with steps to reproduce
+

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": false,
+    "noEmit": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}