nodestorm-mcp 0.1.1 → 0.1.2

package/README.md

@@ -61,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.
 
@@ -109,14 +111,6 @@ Input: { query: "pricing", scope: "user", limit: 20 }
 Output: { flows: [...], total }
 ```
 
-### describe_nodes
-Get node type definitions (no API call).
-
-```
-Input: { types: ["prompt", "list"] } // optional filter
-Output: { nodes: [{ type, description, category, config_schema, handles }] }
-```
-
 ### get_flow_run
 Get details of a specific flow run, including execution results and node outputs.
 
@@ -141,14 +135,44 @@ 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: { slug: "workflow-execution" }
+Output: { page: { slug, title, category, description, body, updated_at } }
+```
+
+### search_docs
+Semantic (meaning-based) search over the NodeStorm documentation.
+
+```
+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
 

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[];

package/dist/tools/docs.js

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+export const DOCS_TOOL_DEFINITIONS = [
+    {
+        name: 'list_docs',
+        description: 'List NodeStorm product documentation pages — node behavior, workflow mechanics, guides. ' +
+            'Returns slug, title, category, and description for each page. Pass `category` to filter.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                category: {
+                    type: 'string',
+                    description: "Filter to a single category (e.g., 'node', 'guide', 'help')",
+                },
+            },
+        },
+    },
+    {
+        name: 'get_doc',
+        description: 'Get a NodeStorm documentation page by slug, including its full markdown body. ' +
+            'Use list_docs or search_docs to find slugs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: {
+                    type: 'string',
+                    description: 'Page slug (from list_docs or search_docs results)',
+                },
+            },
+            required: ['slug'],
+        },
+    },
+    {
+        name: 'search_docs',
+        description: 'Search NodeStorm product documentation using semantic (meaning-based) search. ' +
+            'Returns matching content chunks ranked by relevance to the query.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Natural language search query',
+                },
+            },
+            required: ['query'],
+        },
+    },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodestorm-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "MCP server for NodeStorm workflow automation",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc && cp src/workflow-guide.md dist/",
+    "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
     "test": "vitest run",

package/dist/tools/describe.d.ts

@@ -1,18 +0,0 @@
-/**
- * Node definitions for the describe_nodes tool
- * These are bundled statically to avoid API calls
- */
-export interface NodeDefinition {
-    type: string;
-    description: string;
-    category: string;
-    config_schema: Record<string, any>;
-    handles: {
-        inputs: string[];
-        outputs: string[];
-    };
-}
-/**
- * Get node definitions, optionally filtered by type
- */
-export declare function getNodeDefinitions(types?: string[]): NodeDefinition[];