flowspec-mcp 4.1.0 → 4.2.0

package/README.md

@@ -2,21 +2,6 @@
 
 MCP (Model Context Protocol) server for [FlowSpec](https://flowspec.app) — exposes project specifications to Claude Code and other MCP-compatible AI tools.
 
-## v4.1.0 - What's New
-
-- **Subviews Support** (NEW): Create, manage, and export focused mini-canvases showing node subsets
-- **Selection Resource**: Read currently selected nodes/edges from FlowSpec desktop editor
-- **"current" Alias**: Use `nodeId: "current"` or `edgeId: "current"` in update/delete tools
-- **Context-Aware Commands**: Enable natural language like "move this node" or "change the edge handle"
-
-### v4.0.0 Changes
-
-- **JSON Export**: `flowspec_get_json` tool for faster parsing (100x) and smaller files (40%)
-- **YAML Export** (Deprecated): `flowspec_get_yaml` still available for backwards compatibility
-- **Performance**: Aligned with FlowSpec v4 normalized schema (8000x faster updates)
-
-**Migration**: Replace `flowspec_get_yaml` with `flowspec_get_json` in your workflows.
-
 ## Quick Start
 
 Add to your `~/.claude.json`:
@@ -68,8 +53,7 @@ Local mode connects to the FlowSpec desktop server at `http://localhost:3456`.
 
 ### Read Tools
 - **`flowspec_list_projects`** — List all projects with names and dates
-- **`flowspec_get_json`** — Get full JSON spec for a project (v4.0.0+, recommended)
-- **`flowspec_get_yaml`** — Get full YAML spec for a project (deprecated, use get_json)
+- **`flowspec_get_yaml`** — Get full YAML spec for a project (optimised for Claude Code)
 - **`flowspec_get_project`** — Get raw canvas_state JSON
 - **`flowspec_search_nodes`** — Search nodes by label across all projects
 - **`flowspec_get_screen_context`** — Get screen/region/element structure
@@ -79,151 +63,12 @@ Local mode connects to the FlowSpec desktop server at `http://localhost:3456`.
 - **`flowspec_update_project`** — Update project name or canvas state
 - **`flowspec_delete_project`** — Delete a project
 - **`flowspec_create_node`** — Add a node (datapoint, component, transform, table)
-- **`flowspec_update_node`** — Update node data or position (supports `nodeId: "current"`)
-- **`flowspec_delete_node`** — Remove a node and connected edges (supports `nodeId: "current"`)
+- **`flowspec_update_node`** — Update node data or position
+- **`flowspec_delete_node`** — Remove a node and connected edges
 - **`flowspec_create_edge`** — Connect two nodes with an edge type
-- **`flowspec_update_edge`** — Update edge type, label, or handle positions (supports `edgeId: "current"`)
-- **`flowspec_delete_edge`** — Remove an edge (supports `edgeId: "current"`)
+- **`flowspec_delete_edge`** — Remove an edge
 - **`flowspec_analyse_project`** — Run orphan node and duplicate label analysis
 
-### Subview Tools (v4.1.0+)
-- **`flowspec_list_subviews`** — List all subviews in a project
-- **`flowspec_create_subview`** — Create a focused mini-canvas with selected nodes
-- **`flowspec_update_subview`** — Update subview name, description, or node positions
-- **`flowspec_delete_subview`** — Delete a subview
-
-### Resources
-- **`flowspec://selection/current`** — Currently selected nodes, edges, and viewport in FlowSpec desktop editor (local mode only)
-
-## Context-Aware Commands (v4.1.0+)
-
-The selection resource enables natural language commands that reference "this node" or "these edges".
-
-### Reading Current Selection
-
-```typescript
-// In Claude Code, use ReadMcpResourceTool:
-ReadMcpResourceTool({ uri: "flowspec://selection/current" })
-
-// Returns:
-{
-  type: "selection",
-  projectId: "...",
-  projectName: "My App",
-  selectedNodes: [{ id: "...", label: "User Email", type: "datapoint", ... }],
-  selectedEdges: [{ id: "...", source: "...", target: "...", ... }],
-  viewport: { x: 150.5, y: -200.3, zoom: 1.2 }
-}
-```
-
-### Using "current" Alias
-
-Instead of copying UUIDs, use `"current"` to reference the selected node/edge:
-
-```typescript
-// Update the selected node
-flowspec_update_node({ projectId, nodeId: "current", position: { x: 500, y: 300 } })
-
-// Delete the selected edge
-flowspec_delete_edge({ projectId, edgeId: "current" })
-
-// Change edge handle
-flowspec_update_edge({ projectId, edgeId: "current", targetHandle: "target-left" })
-```
-
-**Requirements:**
-- Desktop app must be running (local mode)
-- Exactly one node/edge must be selected (multi-selection returns error)
-- Selection must be less than 60 seconds old
-
-**Multi-selection:**
-- User holds Shift and clicks multiple nodes to select them
-- Selection resource returns all selected items
-- "current" alias does not work with multi-selection (use explicit IDs instead)
-
-### Example Workflow
-
-```
-User: (clicks node "User Email" in FlowSpec)
-User: "Move this node to the right"
-
-Claude:
-1. ReadMcpResourceTool("flowspec://selection/current")
-   → { selectedNodes: [{ id: "abc-123", label: "User Email", position: {x:100, y:200} }] }
-2. flowspec_update_node({ projectId, nodeId: "current", position: {x:400, y:200} })
-   → "Updated currently selected node (abc-123)"
-```
-
-## Subviews (v4.1.0+)
-
-Subviews are focused mini-canvases that show a subset of nodes from the main canvas. They're useful for:
-- **Focused workflows**: "Auth Flow", "Payment Processing", "Data Validation"
-- **Documentation**: Export specific flows as standalone diagrams
-- **Collaboration**: Share relevant subsets without overwhelming stakeholders
-
-### Creating Subviews
-
-```typescript
-// Create a subview for authentication flow
-flowspec_create_subview({
-  projectId,
-  name: "Auth Flow",
-  description: "User authentication and session management",
-  nodePositions: [
-    { nodeId: "node-login-form", x: 100, y: 100 },
-    { nodeId: "node-user-email", x: 300, y: 100 },
-    { nodeId: "node-auth-token", x: 500, y: 100 }
-  ]
-})
-```
-
-### Managing Subviews
-
-```typescript
-// List all subviews
-flowspec_list_subviews({ projectId })
-
-// Update subview name or add more nodes
-flowspec_update_subview({
-  projectId,
-  subviewId: "subview-abc123",
-  name: "Authentication & Authorization",
-  nodePositions: [...existingNodes, { nodeId: "node-permissions", x: 700, y: 100 }]
-})
-
-// Delete a subview
-flowspec_delete_subview({ projectId, subviewId: "subview-abc123" })
-```
-
-### Subviews in Exports
-
-Subviews are automatically included in `flowspec_get_json` exports:
-
-```json
-{
-  "version": "1.3.0",
-  "metadata": { ... },
-  "dataPoints": [ ... ],
-  "components": [ ... ],
-  "subviews": [
-    {
-      "id": "subview-abc123",
-      "name": "Auth Flow",
-      "description": "User authentication and session management",
-      "nodes": [
-        {
-          "nodeId": "node-login-form",
-          "nodeLabel": "Login Form",
-          "nodeType": "component",
-          "x": 100,
-          "y": 100
-        }
-      ]
-    }
-  ]
-}
-```
-
 ## Development
 
 ```bash

package/dist/db.d.ts

@@ -113,29 +113,3 @@ export declare function bulkImportCanvasState(projectId: string, canvasState: {
     edgeCount: number;
     screenCount: number;
 }>;
-export declare function createSubviewViaApi(projectId: string, name: string, description?: string, nodePositions?: Array<{
-    nodeId: string;
-    x: number;
-    y: number;
-}>): Promise<{
-    id: string;
-    name: string;
-    description?: string;
-    nodePositions: Array<{
-        nodeId: string;
-        x: number;
-        y: number;
-    }>;
-} | null>;
-export declare function updateSubviewViaApi(projectId: string, subviewId: string, updates: Partial<{
-    name: string;
-    description: string;
-    nodePositions: Array<{
-        nodeId: string;
-        x: number;
-        y: number;
-    }>;
-}>): Promise<{
-    id: string;
-} | null>;
-export declare function deleteSubviewViaApi(projectId: string, subviewId: string): Promise<boolean>;