nodestorm-mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,27 +1,26 @@
 # nodestorm-mcp
 
-MCP (Model Context Protocol) server for NodeStorm workflow automation.
+MCP (Model Context Protocol) server for [NodeStorm](https://nodestorm.ai) workflow automation.
 
 ## Installation
 
-```bash
-npx nodestorm-mcp
-```
-
-Or install globally:
+No install step needed — MCP clients run it via `npx`:
 
 ```bash
-npm install -g nodestorm-mcp
+npx -y nodestorm-mcp
 ```
 
 ## Configuration
 
-### Claude Code / Claude Desktop
+### Claude Code
 
-Add to your Claude configuration file:
+From your project directory:
 
-**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+```bash
+claude mcp add nodestorm -e NODESTORM_API_KEY=ns_your_access_token_here -- npx -y nodestorm-mcp
+```
+
+Or add to a `.mcp.json` in your project root (or `~/.claude.json` for all projects):
 
 ```json
 {
@@ -37,6 +36,13 @@ Add to your Claude configuration file:
 }
 ```
 
+### Claude Desktop
+
+Add the same `mcpServers` block to:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
 ### Environment Variables
 
 | Variable | Required | Description |
@@ -55,6 +61,8 @@ Note: Access tokens require an active NodeStorm subscription.
 
 ## Available Tools
 
+At connect the server sends short instructions (0.1.2): what NodeStorm is, which tool a nodestorm.ai link maps to (`/files/N`, `/flows/N`, `/flow-runs/N`, `/help/slug`), and to read a node's doc with `get_doc` before `execute_node`. MCP clients such as Claude Code show them to the model at session start.
+
 ### create_flow
 Create a new workflow from a natural language description.
 
@@ -72,10 +80,18 @@ Output: { id, name, nodes, edges, url, updated_at }
 ```
 
 ### update_flow
-Modify an existing workflow.
+Update workflow **metadata** (name, description, schedule). Does not modify nodes or edges — use `update_flow_structure` for that.
 
 ```
-Input: { id: "abc123", flow: { name, nodes, edges } }
+Input: { id: "abc123", flow: { name, description, schedule_enabled, ... } }
+Output: { id, name, nodes, edges, url, updated_at }
+```
+
+### update_flow_structure
+Apply a list of structural operations (add/update/remove nodes and edges) atomically to an existing workflow.
+
+```
+Input: { flow_id: "abc123", operations: [{ op: "add_node", ... }, ...] }
 Output: { id, name, nodes, edges, url, updated_at }
 ```
 
@@ -88,37 +104,75 @@ Output: { success: true }
 ```
 
 ### list_flows
-List all your workflows.
+List or search your workflows (`scope: "public"` searches published community entries).
 
 ```
-Input: { limit: 20, offset: 0 }
+Input: { query: "pricing", scope: "user", limit: 20 }
 Output: { flows: [...], total }
 ```
 
-### validate_flow
-Check if a workflow is valid before saving.
+### get_flow_run
+Get details of a specific flow run, including execution results and node outputs.
+
+```
+Input: { id: "run123" }
+Output: { id, flow_id, status, node_results, started_at, finished_at }
+```
+
+### list_flow_runs
+List flow runs with optional filters, for debugging and monitoring.
+
+```
+Input: { flow_id: "abc123", status: "failed", limit: 20 }
+Output: { runs: [...], total }
+```
+
+### search_chat_history
+Semantic (meaning-based) search over your past NodeStorm chat messages.
+
+```
+Input: { query: "how did I set up the scraper flow", limit: 10 }
+Output: { messages: [...] }
+```
+
+### execute_node
+Run one node directly, without a flow. `config` is the node's `data` as in a flow; read the node's doc with `get_doc` first. Each call counts as one node execution against the monthly quota and is capped at about 90 seconds. Nodes that send or write take effect at once.
+
+```
+Input: { node_type: "file", config: { mode: "read", file_id: 123 } }      // read a file (nodestorm.ai/files/123)
+Input: { node_type: "folder", config: { folder_id: "top" } }              // list the files in a folder ("top" = no folder)
+Input: { node_type: "prompt", config: { input: "Summarize" }, input: "..." }
+Output: { success, node_type, output }
+```
+
+### list_docs
+List NodeStorm product documentation pages. Pass `category` to filter (e.g. `"node"` for the node catalog).
+
+```
+Input: { category: "node" } // optional filter
+Output: { pages: [{ slug, title, category, description }] }
+```
+
+### get_doc
+Get a documentation page by slug, including its full markdown body. Node pages use kebab-case slugs like `node-prompt` and `node-http-request`.
 
 ```
-Input: { flow: { nodes, edges } }
-Output: { valid: true } or { valid: false, errors: [...] }
+Input: { slug: "workflow-execution" }
+Output: { page: { slug, title, category, description, body, updated_at } }
 ```
 
-### describe_nodes
-Get node type definitions (no API call).
+### search_docs
+Semantic (meaning-based) search over the NodeStorm documentation.
 
 ```
-Input: { types: ["prompt", "list"] } // optional filter
-Output: { nodes: [{ type, description, category, config_schema, handles }] }
+Input: { query: "how does iteration work" }
+Output: { results: [{ slug, title, category, chunk_content, relevance }] }
 ```
 
 ## Resources
 
 ### workflow-guide
-Complete guide for building NodeStorm workflows. Read this resource to understand:
-- Node types and their configurations
-- Edge connection rules
-- Iteration patterns
-- Validation requirements
+Pointer to the live NodeStorm docs. The bundled guide was replaced by the docs tools above — start with `get_doc("workflow-execution")` and `list_docs({ category: "node" })`.
 
 ## Example Usage
 
@@ -131,7 +185,7 @@ Created "Competitor Pricing Analysis"
 
 User: Add 3 more URLs to the list
 
-Claude: [Uses get_flow, modifies nodes, uses update_flow]
+Claude: [Uses update_flow_structure with add_node/add_edge operations]
 Updated flow with 3 additional URLs.
 ```
 

package/dist/client.d.ts

@@ -29,7 +29,7 @@ export interface FlowRun {
     flow_id: number;
     flow_title: string;
     user_id?: number;
-    status: 'success' | 'error' | 'pending' | 'running';
+    status: 'success' | 'partial' | 'error' | 'pending' | 'running';
     node_count: number;
     duration_seconds: number | null;
     result?: {
@@ -50,7 +50,7 @@ export interface FlowRunListItem {
     id: number;
     flow_id: number;
     flow_title: string;
-    status: 'success' | 'error' | 'pending' | 'running';
+    status: 'success' | 'partial' | 'error' | 'pending' | 'running';
     node_count: number;
     duration_seconds: number | null;
     created_at: string;
@@ -104,6 +104,10 @@ export declare class NodeStormClient {
         schedule_enabled?: boolean;
         schedule_cron?: string;
         schedule_timezone?: string;
+        settings?: {
+            on_step_failure?: 'continue' | 'stop';
+            notify_on_failure?: boolean;
+        };
     }): Promise<Flow>;
     /**
      * Apply atomic structural operations (edit/add/remove nodes and edges) to an existing flow.
@@ -136,10 +140,24 @@ export declare class NodeStormClient {
      */
     listFlowRuns(options?: {
         flowId?: number;
-        status?: 'success' | 'error' | 'pending' | 'running';
+        status?: 'success' | 'partial' | 'error' | 'pending' | 'running';
         page?: number;
         perPage?: number;
     }): Promise<FlowRunListResponse>;
+    /**
+     * List documentation pages, optionally filtered by category
+     */
+    listDocs(options?: {
+        category?: string;
+    }): Promise<DocListResponse>;
+    /**
+     * Get a documentation page by slug, including its full markdown body
+     */
+    getDoc(slug: string): Promise<DocPageResponse>;
+    /**
+     * Search documentation using semantic search
+     */
+    searchDocs(query: string): Promise<DocSearchResponse>;
     /**
      * Search chat message history using semantic search
      */
@@ -151,6 +169,42 @@ export declare class NodeStormClient {
         from?: string;
         to?: string;
     }): Promise<ChatSearchResponse>;
+    /**
+     * Execute a single node directly, outside any flow. Capped at ~90s server-side;
+     * long-running work belongs in a real flow.
+     */
+    executeNode(params: {
+        node_type: string;
+        config?: object;
+        input?: unknown;
+    }): Promise<ExecuteNodeResponse>;
+}
+export interface DocListItem {
+    slug: string;
+    title: string;
+    category: string;
+    visibility: string;
+    description: string | null;
+}
+export interface DocListResponse {
+    pages: DocListItem[];
+}
+export interface DocPage extends DocListItem {
+    body: string;
+    updated_at: string;
+}
+export interface DocPageResponse {
+    page: DocPage;
+}
+export interface DocSearchResult {
+    slug: string;
+    title: string;
+    category: string;
+    chunk_content: string;
+    relevance: number;
+}
+export interface DocSearchResponse {
+    results: DocSearchResult[];
 }
 export interface ChatSearchResult {
     content: string;
@@ -162,6 +216,12 @@ export interface ChatSearchResult {
 export interface ChatSearchResponse {
     results: ChatSearchResult[];
 }
+export interface ExecuteNodeResponse {
+    success: boolean;
+    node_type: string;
+    /** The worker's result (NodeResult shape: { data, data_type, success, error?, metadata? }) */
+    output: unknown;
+}
 export declare class NodeStormApiError extends Error {
     code: string;
     statusCode: number;

package/dist/client.js

@@ -110,6 +110,31 @@ export class NodeStormClient {
         const path = queryString ? `/flow-runs?${queryString}` : '/flow-runs';
         return this.request(path);
     }
+    /**
+     * List documentation pages, optionally filtered by category
+     */
+    async listDocs(options = {}) {
+        const params = new URLSearchParams();
+        if (options.category)
+            params.append('category', options.category);
+        const queryString = params.toString();
+        const path = queryString ? `/docs?${queryString}` : '/docs';
+        return this.request(path);
+    }
+    /**
+     * Get a documentation page by slug, including its full markdown body
+     */
+    async getDoc(slug) {
+        return this.request(`/docs/${encodeURIComponent(slug)}`);
+    }
+    /**
+     * Search documentation using semantic search
+     */
+    async searchDocs(query) {
+        const params = new URLSearchParams();
+        params.append('q', query);
+        return this.request(`/docs/search?${params.toString()}`);
+    }
     /**
      * Search chat message history using semantic search
      */
@@ -128,6 +153,16 @@ export class NodeStormClient {
             params.append('to', options.to);
         return this.request(`/chat/search?${params.toString()}`);
     }
+    /**
+     * Execute a single node directly, outside any flow. Capped at ~90s server-side;
+     * long-running work belongs in a real flow.
+     */
+    async executeNode(params) {
+        return this.request('/nodes/execute', {
+            method: 'POST',
+            body: JSON.stringify(params),
+        });
+    }
 }
 export class NodeStormApiError extends Error {
     code;

package/dist/index.js

@@ -8,17 +8,15 @@
  * - NODESTORM_API_KEY (required): API key for authentication
  * - NODESTORM_API_URL (optional): API base URL (default: https://nodestorm.ai)
  */
+import { createRequire } from 'node:module';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { NodeStormClient, NodeStormApiError } from './client.js';
-import { getNodeDefinitions } from './tools/describe.js';
-import { readFileSync } from 'fs';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-// Get the directory of this file
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+import { DOCS_TOOL_DEFINITIONS } from './tools/docs.js';
+import { EXECUTE_NODE_DESCRIPTION, SERVER_INSTRUCTIONS } from './instructions.js';
+// One version string: package.json's. Before 0.1.2 this was hard-coded and drifted.
+const { version: VERSION } = createRequire(import.meta.url)('../package.json');
 // Read environment variables
 const apiKey = process.env.NODESTORM_API_KEY;
 const apiUrl = process.env.NODESTORM_API_URL || 'https://nodestorm.ai';
@@ -28,25 +26,29 @@ if (!apiKey) {
 }
 // Initialize client
 const client = new NodeStormClient(apiKey, apiUrl);
-// Load workflow guide (bundled with package)
-function loadWorkflowGuide() {
-    try {
-        const guidePath = join(__dirname, 'workflow-guide.md');
-        return readFileSync(guidePath, 'utf-8');
-    }
-    catch {
-        return '# Workflow Guide\n\nGuide file not found. Please reinstall the package.';
-    }
-}
+// The bundled workflow guide was retired in favor of the live docs (see the docs tools).
+// This pointer keeps the resource URI working for existing clients.
+const WORKFLOW_GUIDE_POINTER = [
+    '# Workflow Guide',
+    '',
+    'The workflow guide moved into the live NodeStorm docs.',
+    'Use the `list_docs` / `get_doc` / `search_docs` tools instead of this resource.',
+    '',
+    "Start with `get_doc('workflow-execution')` for the execution model, and",
+    "`list_docs({ category: 'node' })` for the node catalog (slugs are kebab-case,",
+    'e.g. `node-prompt`, `node-http-request`).',
+].join('\n');
 // Create MCP server
 const server = new Server({
     name: 'nodestorm-mcp',
-    version: '0.1.0',
+    version: VERSION,
 }, {
     capabilities: {
         tools: {},
         resources: {},
     },
+    // 099.9: shown to the model at session start (URL → tool map, read docs first).
+    instructions: SERVER_INSTRUCTIONS,
 });
 // Tool definitions
 server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -97,8 +99,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'update_flow',
-                description: 'Update flow METADATA: name, description, schedule_*. Does NOT modify nodes or edges. ' +
-                    'For any structural change use update_flow_structure.',
+                description: 'Update flow METADATA: name, description, schedule_*, and the flow settings ' +
+                    '(settings.on_step_failure: "continue" | "stop"; settings.notify_on_failure: boolean). ' +
+                    'Does NOT modify nodes or edges. For any structural change use update_flow_structure.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -114,7 +117,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                                 description: { type: 'string' },
                                 schedule_enabled: { type: 'boolean' },
                                 schedule_cron: { type: 'string' },
-                                schedule_timezone: { type: 'string' },
+                                schedule_timezone: { type: 'string', description: 'IANA name, e.g. America/New_York' },
+                                settings: {
+                                    type: 'object',
+                                    description: 'Flow settings; keys sent are merged into the stored ones',
+                                    properties: {
+                                        on_step_failure: { type: 'string', enum: ['continue', 'stop'] },
+                                        notify_on_failure: { type: 'boolean' },
+                                    },
+                                },
                             },
                         },
                     },
@@ -177,7 +188,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                                                 description: 'Node payload. Server generates id if not provided.',
                                                 properties: {
                                                     id: { type: 'string' },
-                                                    type: { type: 'string', description: 'Node type — see describe_nodes for the catalog' },
+                                                    type: {
+                                                        type: 'string',
+                                                        description: "Node type — see list_docs({category: 'node'}) for the catalog and get_doc for each node's schema",
+                                                    },
                                                     data: { type: 'object' },
                                                     position: {
                                                         type: 'object',
@@ -265,20 +279,6 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     },
                 },
             },
-            {
-                name: 'describe_nodes',
-                description: 'Get node type definitions for building flows',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        types: {
-                            type: 'array',
-                            items: { type: 'string' },
-                            description: "Filter to specific node types (e.g., ['prompt', 'list'])",
-                        },
-                    },
-                },
-            },
             {
                 name: 'get_flow_run',
                 description: 'Get details of a specific flow run by ID, including execution results and node outputs',
@@ -341,7 +341,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         },
                         status: {
                             type: 'string',
-                            enum: ['success', 'error', 'pending', 'running'],
+                            enum: ['success', 'partial', 'error', 'pending', 'running'],
                             description: 'Filter by status',
                         },
                         page: {
@@ -355,6 +355,28 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     },
                 },
             },
+            {
+                name: 'execute_node',
+                description: EXECUTE_NODE_DESCRIPTION,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        node_type: {
+                            type: 'string',
+                            description: "Node type to run — see list_docs({category: 'node'}) for the catalog",
+                        },
+                        config: {
+                            type: 'object',
+                            description: "Node configuration, same shape as the node's `data` in a flow",
+                        },
+                        input: {
+                            description: 'Optional input passed as the parent node result (any JSON value)',
+                        },
+                    },
+                    required: ['node_type'],
+                },
+            },
+            ...DOCS_TOOL_DEFINITIONS,
         ],
     };
 });
@@ -435,18 +457,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
-            case 'describe_nodes': {
-                const { types } = args;
-                const nodes = getNodeDefinitions(types);
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({ nodes }, null, 2),
-                        },
-                    ],
-                };
-            }
             case 'get_flow_run': {
                 const { id } = args;
                 const result = await client.getFlowRun(id);
@@ -488,6 +498,54 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'execute_node': {
+                const { node_type, config, input } = args;
+                const result = await client.executeNode({ node_type, config, input });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'list_docs': {
+                const { category } = args;
+                const result = await client.listDocs({ category });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'get_doc': {
+                const { slug } = args;
+                const result = await client.getDoc(slug);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'search_docs': {
+                const { query } = args;
+                const result = await client.searchDocs(query);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
             default:
                 return {
                     content: [
@@ -537,7 +595,7 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
             {
                 uri: 'nodestorm://workflow-guide',
                 name: 'Workflow Builder Guide',
-                description: 'Complete guide for building NodeStorm flows: node types, edge rules, iteration semantics, validation, patterns, and examples',
+                description: 'Pointer to the live NodeStorm docs — use the list_docs / get_doc / search_docs tools instead',
                 mimeType: 'text/markdown',
             },
         ],
@@ -547,13 +605,12 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
 server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     const { uri } = request.params;
     if (uri === 'nodestorm://workflow-guide') {
-        const guide = loadWorkflowGuide();
         return {
             contents: [
                 {
                     uri,
                     mimeType: 'text/markdown',
-                    text: guide,
+                    text: WORKFLOW_GUIDE_POINTER,
                 },
             ],
         };

package/dist/instructions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What the server tells a client at connect (099.9). Shown to the model at
+ * session start, so it reaches the right tool first try instead of trying
+ * curl or a hosting dashboard on a nodestorm.ai link. Kept here, outside
+ * index.ts, so tests can import it without starting the server.
+ */
+export declare const SERVER_INSTRUCTIONS = "NodeStorm runs recurring reports and tasks as flows of nodes (LLM prompts, search, scraping, files, tables, email, integrations). You act on one user's account through their access token.\n\nLinks from nodestorm.ai map to tools:\n- /files/N: execute_node {node_type: \"file\", config: {mode: \"read\", file_id: N}} returns the file's text.\n- /flows/N: get_flow {id: N}. /flows/N/runs: list_flow_runs {flow_id: N}. /flow-runs/N: get_flow_run {id: N}.\n- /help/SLUG: get_doc {slug: SLUG}.\nThere is no HTTP download for files or flows; do not fetch nodestorm.ai URLs directly.\n\nBefore execute_node or update_flow_structure, read the node's doc with get_doc (list_docs {category: \"node\"} lists them): the config keys come from there. Each execute_node call counts as one node execution against the user's monthly quota and is capped at about 90 seconds. Nodes that send or write (email, integrations, file create or update) take effect at once; confirm with the user first.";
+export declare const EXECUTE_NODE_DESCRIPTION: string;

package/dist/instructions.js

@@ -0,0 +1,23 @@
+/**
+ * What the server tells a client at connect (099.9). Shown to the model at
+ * session start, so it reaches the right tool first try instead of trying
+ * curl or a hosting dashboard on a nodestorm.ai link. Kept here, outside
+ * index.ts, so tests can import it without starting the server.
+ */
+export const SERVER_INSTRUCTIONS = `NodeStorm runs recurring reports and tasks as flows of nodes (LLM prompts, search, scraping, files, tables, email, integrations). You act on one user's account through their access token.
+
+Links from nodestorm.ai map to tools:
+- /files/N: execute_node {node_type: "file", config: {mode: "read", file_id: N}} returns the file's text.
+- /flows/N: get_flow {id: N}. /flows/N/runs: list_flow_runs {flow_id: N}. /flow-runs/N: get_flow_run {id: N}.
+- /help/SLUG: get_doc {slug: SLUG}.
+There is no HTTP download for files or flows; do not fetch nodestorm.ai URLs directly.
+
+Before execute_node or update_flow_structure, read the node's doc with get_doc (list_docs {category: "node"} lists them): the config keys come from there. Each execute_node call counts as one node execution against the user's monthly quota and is capped at about 90 seconds. Nodes that send or write (email, integrations, file create or update) take effect at once; confirm with the user first.`;
+export const EXECUTE_NODE_DESCRIPTION = 'Run a single NodeStorm node directly, without creating a flow — any node type. ' +
+    "config is identical to the node's `data` in a flow (see the node's doc via get_doc); " +
+    'optional `input` is passed to the node as its parent result. ' +
+    'Recipes: read a file (a nodestorm.ai/files/N link): {node_type: "file", config: {mode: "read", file_id: N}}. ' +
+    'List the files in a folder: {node_type: "folder", config: {folder_id: ID}}, with folder_id "top" for files in no folder. ' +
+    'Each call counts as one node execution against the monthly quota. ' +
+    'Runs that send or write take effect immediately; confirm with your user first. ' +
+    'Capped at ~90 seconds — long-running work belongs in a real flow instead.';

package/dist/tools/docs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Docs tool definitions for the docs endpoints
+ * NodeStorm product documentation — node behavior, workflow mechanics, guides.
+ * These wrap the backend's v1 docs endpoints via NodeStormClient.
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const DOCS_TOOL_DEFINITIONS: Tool[];