@shirbarzur/planform-mcp-server 1.0.4 → 1.0.6

package/src/usage-examples.ts

@@ -1,40 +1,48 @@
 /**
- * Usage examples for the Planform MCP. Exposed via server instructions and get_usage_examples tool.
+ * Usage examples for the Planform MCP. Exposed via server instructions and get_usage_guide tool.
  */
 export const USAGE_EXAMPLES = `
 # Planform MCP – How to use
 
-## 1. Authentication (required first)
+All IDs (user, diagram, node, link) are handled by the server. You never need to pass or remember UUIDs.
 
-Before listing or managing diagrams, the user must authenticate:
+## Recommended flow
 
-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.).
+1. **sign_in** (no arguments) – Sign in; the browser opens for you to approve. The server remembers your session.
+2. **list_diagrams**() – List your diagrams. No arguments needed.
+3. **create_diagram**({ title: "My diagram", type: "uml.class" }) – Create a diagram; it becomes the "current" one. Or **open_diagram**("My diagram") to open an existing diagram by title.
+4. **create_node**({ kind: "class", name: "User" }) – Add nodes to the current diagram. Use **node names** (e.g. "User", "Account").
+5. **create_link**({ kind: "inheritance", from: "User", to: "Account", directional: "unidirectional" }) – Connect nodes by **name** (from/to are node names). No diagram or node IDs needed.
+6. **update_node**("User", { ... }) / **delete_node**("User") – Refer to nodes by **name**. **update_link** / **delete_link** use the link_id from the response when you created the link (or from open_diagram).
 
-## 2. Example: List the user's diagrams
+## 1. Sign in (required first)
 
-1. **device_start** → user approves in browser → response includes \`approved_user_uuid\`.
-2. **diagrams_list** with \`user_uuid: "<approved_user_uuid from step 1>"\`.
+Call **sign_in** with no arguments. A browser window opens; approve the request. The server stores your session—you do not pass any IDs to other tools.
 
-Example: \`diagrams_list({ "user_uuid": "abc-123-from-device_start" })\`
+## 2. List or create diagrams
 
-## 3. Example: Create a diagram and add nodes
+- **list_diagrams**() – Lists your diagrams (optional: status, page, page_size).
+- **create_diagram**({ title: "My class diagram", type: "uml.class" }) – Creates a diagram and sets it as current. Then you can add nodes and links without specifying a diagram.
 
-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.
+## 3. Open an existing diagram
 
-## 4. Example: Fetch a diagram
+- **open_diagram**("My class diagram") – Open by **title**. Omit the argument to re-load the current diagram. The opened diagram becomes current for create_node and create_link.
 
-1. **device_start** (if not already authenticated).
-2. **diagram_get** with \`diagram_uuid\` (from diagrams_list or diagram_create).
+## 4. Add nodes and links
+
+- **create_node**({ kind: "class", name: "User" }) – Adds a node to the current diagram. Use **kind** (class | interface | enum), **name**, and optionally **fields**, **methods**.
+- **create_link**({ kind: "inheritance", from: "User", to: "Account" }) – **from** and **to** are **node names** (e.g. "User", "Account"). The server resolves them; no node IDs or labels needed.
+
+## 5. Update or delete by name
+
+- **update_node**("User", { name: "UserEntity", ... }) – First argument is the **node name**.
+- **delete_node**("User") – Delete by node name.
+- **update_link** / **verify_link** / **delete_link** – Use **link_id** from the response when you created the link (or from open_diagram). The server uses the current diagram.
 
 ## 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.
+- Call **sign_in** first; no IDs to copy or pass.
+- **create_diagram** and **open_diagram** set the "current" diagram; **create_node** and **create_link** use it automatically.
+- Refer to **nodes by name** (e.g. "User") in update_node, verify_node, delete_node, and in create_link (from/to).
+- **link_id** is only needed for update_link/verify_link/delete_link; get it from create_link or open_diagram response.
 `;