@shirbarzur/planform-mcp-server 1.0.5 → 1.0.7

package/.mcpregistry_github_token

@@ -1 +1 @@
-ghu_YuVjEsZEU5H77mRApssrqCwO8RHTrg20IR0O
+ghu_qVZZlzCmVSDhuDFh5A3HOIVmkdSZUk3d4nYb

package/.mcpregistry_registry_token

@@ -1 +1 @@
-{"token":"eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtY3AtcmVnaXN0cnkiLCJleHAiOjE3NzE3MDQxMzAsIm5iZiI6MTc3MTcwMzgzMCwiaWF0IjoxNzcxNzAzODMwLCJhdXRoX21ldGhvZCI6ImdpdGh1Yi1hdCIsImF1dGhfbWV0aG9kX3N1YiI6IlNoaXJCYXJadXIiLCJwZXJtaXNzaW9ucyI6W3siYWN0aW9uIjoicHVibGlzaCIsInJlc291cmNlIjoiaW8uZ2l0aHViLlNoaXJCYXJadXIvKiJ9XX0.HGeyUKW2wCkdbtImEDCFQL2NGNCYAR34ruiOqfii50BsUnIGAa4KkDaWv0fS2hOXFaxD3zXyxjeVzaGQEK0HCQ","expires_at":1771704130}
+{"token":"eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtY3AtcmVnaXN0cnkiLCJleHAiOjE3NzIwODY5MzksIm5iZiI6MTc3MjA4NjYzOSwiaWF0IjoxNzcyMDg2NjM5LCJhdXRoX21ldGhvZCI6ImdpdGh1Yi1hdCIsImF1dGhfbWV0aG9kX3N1YiI6IlNoaXJCYXJadXIiLCJwZXJtaXNzaW9ucyI6W3siYWN0aW9uIjoicHVibGlzaCIsInJlc291cmNlIjoiaW8uZ2l0aHViLlNoaXJCYXJadXIvKiJ9XX0.06x9V-YNUNoTi4TbIuLartAhQ3Q8RvRD-R--r3fCD7ga00EJIZZm1aLJM0g5bLtNYH4m0S_OiBgS6HwhMyD3CQ","expires_at":1772086939}

package/MCP_CONNECTION_GUIDE.md

@@ -109,7 +109,7 @@ After adding the configuration, restart Cursor or VS Code to load the MCP server
 
 The MCP server uses device code authentication. When you first use the MCP tools:
 
-1. **Start Device Flow**: Use the `device_start` tool in Cursor/Copilot
+1. **Start Device Flow**: Use the `sign_in` tool in Cursor/Copilot
    - This will return a `user_code` (e.g., "ABCD-EFGH") and `verification_uri`
    - **The browser will automatically open** with the verification page
 
@@ -126,15 +126,25 @@ The MCP server uses device code authentication. When you first use the MCP tools
    - Once you approve in the browser, the token will be received automatically
    - You'll see log messages indicating polling status
    - The access token is valid for 7 days and is stored automatically
-   - **Note**: `device_token_poll` is available as an optional/advanced tool if you need to manually check status, but it's usually not needed
+   - **Note**: `poll_auth_token` is available as an optional/advanced tool if you need to manually check status, but it's usually not needed
+
+## After first sign-in (no IDs to pass)
+
+Once you have signed in with `sign_in`, the server **remembers your session**. You do not pass or copy any user IDs:
+
+- **`list_diagrams`** – No arguments needed; the server uses your stored session.
+- **`create_diagram`** – Pass only `title` and `type`; the new diagram becomes the "current" one.
+- **`open_diagram`** – Pass a **diagram title** (e.g. `"My class diagram"`) to open it by name, or omit to refresh the current diagram. The opened diagram becomes current.
+- **`create_node`** and **`create_link`** – Use the **current diagram** automatically (the one you just created or opened). For links, use **node names** for `from` and `to` (e.g. `"User"`, `"Account"`); the server resolves them. No diagram or node UUIDs needed.
+- **`update_node`** / **`delete_node`** – Refer to nodes by **name** (e.g. `"User"`). **`update_link`** / **`delete_link`** need `link_id` from the response when you created the link or from `open_diagram`.
 
 ## Step 6: Verify Connection
 
 Test the connection by using MCP tools in Cursor:
 
 - `health_check` - Check MCP server status
-- `backend_health_check` - Check backend API status
-- `diagrams_list` - List your diagrams (requires authentication)
+- `check_backend_health` - Check backend API status
+- `list_diagrams` - List your diagrams (uses your session; no arguments needed)
 
 ## Troubleshooting
 
@@ -161,7 +171,7 @@ Test the connection by using MCP tools in Cursor:
    curl http://localhost:8000/healthz
    ```
 
-2. **Token expired**: If your token expires (after 7 days), restart the device flow by calling `device_start` again
+2. **Token expired**: If your token expires (after 7 days), restart the device flow by calling `sign_in` again
 
 3. **User code expired**: Device codes expire after 10 minutes. Start a new flow if needed
 
@@ -220,11 +230,11 @@ This means the server wasn't built with the latest code. **Solution**:
 
 Once connected, you can use these tools in Cursor/Copilot:
 
-- **Authentication**: `device_start` (required), `device_token_poll` (optional/advanced)
-- **Health**: `health_check`, `backend_health_check`
-- **Diagrams**: `diagram_create`, `diagram_get`, `diagrams_list`
-- **Nodes**: `nodes_create`, `node_update`, `node_verify`, `node_delete`
-- **Links**: `links_create`, `link_update`, `link_verify`, `link_delete`
+- **Authentication**: `sign_in` (required), `poll_auth_token` (optional/advanced)
+- **Health**: `health_check`, `check_backend_health`
+- **Diagrams**: `create_diagram`, `open_diagram`, `list_diagrams`
+- **Nodes**: `create_node`, `update_node`, `verify_node`, `delete_node`
+- **Links**: `create_link`, `update_link`, `verify_link`, `delete_link`
 
 ## Development Mode
 

package/README.md

@@ -126,7 +126,7 @@ You can omit the `env` block to use the built-in defaults (production Planform A
 
 The server loads `.env` only from the **package directory** (next to the executable), not from your workspace, so your project’s `.env` does not override the default (production) backend URL.
 
-**First use:** When you use the MCP, the `device_start` tool will give you a link and code to sign in at [planform.io](https://www.planform.io) and authorize the connection.
+**First use:** When you use the MCP, the `sign_in` tool will give you a link and code to sign in at [planform.io](https://www.planform.io) and authorize the connection. The access token is stored on disk (`~/.planform/mcp-token.json`) so it persists across tool calls even if the MCP server is restarted each time.
 
 ## VS Code Integration
 
@@ -134,54 +134,42 @@ To use this MCP server with VS Code (with an MCP extension):
 
 1. Add the server configuration to your MCP settings (same structure as above, under the key your extension expects, e.g. `mcp.servers`).
 2. The server runs via stdio transport.
-3. Use the device flow authentication to get access tokens.
+3. Call `sign_in` once to authenticate; the server then remembers your session and current diagram—no IDs to pass to other tools.
 
 ## Available Tools
 
-### `health_check`
-Check the health status of the Planform MCP server.
+Tools are listed in recommended flow order: authenticate first, then diagrams, then nodes, then links. All use verb_noun names; the server handles session and current diagram—no UUIDs to pass.
 
-### `device_start`
-Start device code flow for MCP authentication. Returns device_code, user_code, and verification URLs.
+### Discovery and health
 
-### `device_token_poll` (Optional/Advanced)
-Manually poll for MCP JWT after user approves. Usually not needed since `device_start` polls automatically. Useful for edge cases or debugging.
+- **`health_check`** – Check the health status of the Planform MCP server.
+- **`get_usage_guide`** – Get step-by-step instructions and recommended flow. Call when unsure how to use the server.
+- **`check_backend_health`** – Check the health status of the Planform backend API.
 
-### `backend_health_check`
-Check the health status of the Planform backend API.
+### Authentication (required first)
 
-### `diagram_create`
-Create a new diagram (MCP is allowed). Requires user_uuid and title.
+- **`sign_in`** – **Call this first**. Opens browser for you to approve; the server remembers your session. No IDs to pass to other tools.
+- **`poll_auth_token`** (optional/advanced) – Manually poll for auth token after user approves. Usually not needed since `sign_in` polls automatically.
 
-### `diagram_get`
-Fetch full diagram (nodes + links) to mirror state locally.
+### Diagrams
 
-### `diagrams_list`
-List all diagrams of the bound user with pagination support.
+- **`list_diagrams`** – List your diagrams. Uses your session; no arguments required (optional: status, page, page_size).
+- **`create_diagram`** – Create a new diagram (title, type). Becomes the current diagram for node/link tools.
+- **`open_diagram`** – Open a diagram by title or ID; omit to refresh the current diagram. Opened diagram becomes current.
 
-### `nodes_create`
-Create UML node with immutable grid placement.
+### Nodes
 
-### `node_update`
-Update structural fields (MCP authoritative).
+- **`create_node`** – Add a node (class, interface, enum) to the current diagram. Refer to nodes by name elsewhere.
+- **`update_node`** – Update a node's fields, methods, or name. Use node name (e.g. "User"); uses current diagram.
+- **`verify_node`** – Mark a node as verified. Use node name.
+- **`delete_node`** – Delete a node. Use node name.
 
-### `node_verify`
-Mark a node as verified by MCP after confirming structure in code.
+### Links
 
-### `node_delete`
-Delete node with status-based logic.
-
-### `links_create`
-Create link between nodes (never moves nodes).
-
-### `link_update`
-Update link fields (MCP authoritative).
-
-### `link_verify`
-Mark a link as verified by MCP after confirming relationship in code.
-
-### `link_delete`
-Delete link with status-based logic.
+- **`create_link`** – Create a link between two nodes. Use **node names** for `from` and `to` (e.g. "User", "Account"); server resolves them.
+- **`update_link`** – Update a link's label, direction, etc. Use `link_id` from `create_link` or `open_diagram` response.
+- **`verify_link`** – Mark a link as verified. Use `link_id` from response.
+- **`delete_link`** – Delete a link. Use `link_id` from response.
 
 ## Architecture
 
@@ -191,12 +179,12 @@ The server is built with:
 - **Axios**: HTTP client for API communication
 - **Modular Design**: Separate concerns for server, API client, and logging
 
-## Development Roadmahe health stp
+## Development Roadmap
 
 This implements steps D22, D23, and D24 of the Planform implementation plan. Completed:
 - ✅ D22: Scaffold minimal MCP server (Node.js + MCP SDK)
-- ✅ D23: Implement diagram_create, diagrams_list, diagram_get tools
-- ✅ D24: Implement nodes_create, links_create tools with full CRUD operations
+- ✅ D23: Implement create_diagram, list_diagrams, open_diagram tools
+- ✅ D24: Implement create_node, create_link tools with full CRUD operations
 
 Future steps will add:
 - D25: Diagram rearrangement capabilities

package/dist/server.d.ts

@@ -4,7 +4,19 @@ export declare class PlanformMCPServer {
     private apiClient;
     private logger;
     private activePolling;
+    /** Set after successful sign_in; used for list_diagrams and create_diagram so callers need not pass user_uuid */
+    private sessionUserUuid;
+    /** Set after create_diagram or open_diagram; used for node/link tools so callers need not pass diagram_uuid */
+    private currentDiagramUuid;
     constructor();
+    /**
+     * Load token and user UUID from disk and apply to apiClient and sessionUserUuid.
+     * Call at server init and at the start of each tool call so auth persists across process restarts.
+     * If user_uuid is missing from storage, we try to read it from the JWT "sub" claim (many backends put user id there).
+     */
+    private restoreSessionFromDisk;
+    /** Decode JWT payload and return "sub" claim if present (no signature verification). */
+    private decodeJwtSub;
     private setupHandlers;
     private handleHealthCheck;
     private handleGetUsageExamples;
@@ -14,6 +26,19 @@ export declare class PlanformMCPServer {
      * Returns a promise that resolves when polling completes
      */
     private pollUntilApproved;
+    /**
+     * 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 getCurrentDiagramData;
+    /**
+     * Resolve node_identifier (name or UUID) to node UUID using the current diagram.
+     */
+    private resolveNodeToUuid;
+    /**
+     * Resolve node reference (name or label like n-1) to node label for create_link.
+     */
+    private resolveNodeToLabel;
     /**
      * Start automatic background polling for device token (kept for backward compatibility)
      * @deprecated Use pollUntilApproved for synchronous polling

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAajF,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAA0C;;IAsB/D,OAAO,CAAC,aAAa;YA+bP,iBAAiB;YAoBjB,sBAAsB;YAatB,iBAAiB;IA8F/B;;;OAGG;YACW,iBAAiB;IA2E/B;;;OAGG;IACH,OAAO,CAAC,qBAAqB;YAmEf,qBAAqB;YAyBrB,wBAAwB;YAqBxB,mBAAmB;YAyCnB,gBAAgB;YAyChB,kBAAkB;YA4ClB,iBAAiB;YA4CjB,gBAAgB;YA4BhB,gBAAgB;YAyBhB,gBAAgB;YAyBhB,iBAAiB;YAiDjB,gBAAgB;YA4BhB,gBAAgB;YAyBhB,gBAAgB;IAyBxB,KAAK,CAAC,SAAS,EAAE,oBAAoB;CAI5C"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAmBjF,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAA0C;IAC/D,iHAAiH;IACjH,OAAO,CAAC,eAAe,CAAuB;IAC9C,+GAA+G;IAC/G,OAAO,CAAC,kBAAkB,CAAuB;;IAuBjD;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAY9B,wFAAwF;IACxF,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,aAAa;YAsZP,iBAAiB;YAoBjB,sBAAsB;YAatB,iBAAiB;IAqG/B;;;OAGG;YACW,iBAAiB;IA2E/B;;;OAGG;YACW,qBAAqB;IAanC;;OAEG;YACW,iBAAiB;IAiB/B;;OAEG;YACW,kBAAkB;IAiBhC;;;OAGG;IACH,OAAO,CAAC,qBAAqB;YAmEf,qBAAqB;YAyBrB,wBAAwB;YAqBxB,mBAAmB;YA6CnB,gBAAgB;YA2DhB,kBAAkB;YA4ClB,iBAAiB;YA8CjB,gBAAgB;YAoChB,gBAAgB;YAiChB,gBAAgB;YA8BhB,iBAAiB;YAoDjB,gBAAgB;YA+BhB,gBAAgB;YA4BhB,gBAAgB;IA4BxB,KAAK,CAAC,SAAS,EAAE,oBAAoB;CAI5C"}