nodestorm-mcp 0.1.0

package/README.md

@@ -0,0 +1,151 @@
+# nodestorm-mcp
+
+MCP (Model Context Protocol) server for NodeStorm workflow automation.
+
+## Installation
+
+```bash
+npx nodestorm-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g nodestorm-mcp
+```
+
+## Configuration
+
+### Claude Code / Claude Desktop
+
+Add to your Claude configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "nodestorm": {
+      "command": "npx",
+      "args": ["-y", "nodestorm-mcp"],
+      "env": {
+        "NODESTORM_API_KEY": "ns_your_access_token_here"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `NODESTORM_API_KEY` | Yes | Access token from NodeStorm Settings |
+| `NODESTORM_API_URL` | No | API base URL (default: `https://nodestorm.ai`) |
+
+## Getting Your Access Token
+
+1. Log in to [NodeStorm](https://nodestorm.ai)
+2. Go to Settings → Access Tokens
+3. Click "Generate New Token"
+4. Copy the token (you won't see it again!)
+
+Note: Access tokens require an active NodeStorm subscription.
+
+## Available Tools
+
+### create_flow
+Create a new workflow from a natural language description.
+
+```
+Input: { prompt: "Scrape 5 URLs and summarize each page" }
+Output: { id, name, nodes, edges, url }
+```
+
+### get_flow
+Retrieve an existing workflow by ID.
+
+```
+Input: { id: "abc123" }
+Output: { id, name, nodes, edges, url, updated_at }
+```
+
+### update_flow
+Modify an existing workflow.
+
+```
+Input: { id: "abc123", flow: { name, nodes, edges } }
+Output: { id, name, nodes, edges, url, updated_at }
+```
+
+### delete_flow
+Delete a workflow.
+
+```
+Input: { id: "abc123" }
+Output: { success: true }
+```
+
+### list_flows
+List all your workflows.
+
+```
+Input: { limit: 20, offset: 0 }
+Output: { flows: [...], total }
+```
+
+### validate_flow
+Check if a workflow is valid before saving.
+
+```
+Input: { flow: { nodes, edges } }
+Output: { valid: true } or { valid: false, errors: [...] }
+```
+
+### describe_nodes
+Get node type definitions (no API call).
+
+```
+Input: { types: ["prompt", "list"] } // optional filter
+Output: { nodes: [{ type, description, category, config_schema, handles }] }
+```
+
+## 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
+
+## Example Usage
+
+```
+User: Create a flow that scrapes competitor websites and analyzes pricing
+
+Claude: [Uses create_flow with prompt]
+Created "Competitor Pricing Analysis"
+→ https://nodestorm.ai/flows/abc123
+
+User: Add 3 more URLs to the list
+
+Claude: [Uses get_flow, modifies nodes, uses update_flow]
+Updated flow with 3 additional URLs.
+```
+
+## Error Codes
+
+| Code | Meaning |
+|------|---------|
+| `unauthorized` | Invalid or missing API key |
+| `forbidden` | Not authorized for this resource |
+| `not_found` | Resource doesn't exist |
+| `invalid` | Validation failed |
+| `rate_limited` | Too many requests |
+| `server_error` | Server error |
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,170 @@
+/**
+ * NodeStorm API Client
+ * Handles communication with the NodeStorm backend
+ */
+export interface Flow {
+    id: string;
+    name: string;
+    nodes: any[];
+    edges: any[];
+    url: string;
+    updated_at?: string;
+}
+export interface FlowListItem {
+    id: string;
+    name: string;
+    url: string;
+    updated_at: string;
+}
+export interface FlowListResponse {
+    flows: FlowListItem[];
+    total: number;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors?: string[];
+}
+export interface FlowRun {
+    id: number;
+    flow_id: number;
+    flow_title: string;
+    user_id?: number;
+    status: 'success' | 'error' | 'pending' | 'running';
+    node_count: number;
+    duration_seconds: number | null;
+    result?: {
+        node_executions?: Array<{
+            node_id: string;
+            node_type: string;
+            result: any;
+            success?: boolean;
+            error?: string;
+            started_at?: string;
+            completed_at?: string;
+        }>;
+    };
+    created_at: string;
+    updated_at: string;
+}
+export interface FlowRunListItem {
+    id: number;
+    flow_id: number;
+    flow_title: string;
+    status: 'success' | 'error' | 'pending' | 'running';
+    node_count: number;
+    duration_seconds: number | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface FlowRunListResponse {
+    flow_runs: FlowRunListItem[];
+    pagination: {
+        current_page: number;
+        per_page: number;
+        total_count: number;
+        total_pages: number;
+    };
+}
+export interface CreateFlowResponse extends Flow {
+    valid: boolean;
+    errors?: string[];
+}
+export interface ApiError {
+    error: string;
+    code: 'unauthorized' | 'forbidden' | 'not_found' | 'invalid' | 'rate_limited' | 'server_error';
+    errors?: string[];
+}
+export declare class NodeStormClient {
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey: string, baseUrl?: string);
+    private request;
+    /**
+     * Create a new flow from a prompt or directly from JSON (admin-only).
+     */
+    createFlow(params: {
+        prompt?: string;
+        name?: string;
+        workflow_json?: {
+            nodes: unknown[];
+            edges: unknown[];
+        };
+        description?: string;
+    }): Promise<CreateFlowResponse>;
+    /**
+     * Get a flow by ID
+     */
+    getFlow(id: string): Promise<Flow>;
+    /**
+     * Update flow metadata. For structural changes (nodes/edges), use updateFlowStructure.
+     */
+    updateFlow(id: string, flow: {
+        name?: string;
+        description?: string;
+        schedule_enabled?: boolean;
+        schedule_cron?: string;
+        schedule_timezone?: string;
+    }): Promise<Flow>;
+    /**
+     * Apply atomic structural operations (edit/add/remove nodes and edges) to an existing flow.
+     * All ops apply in one transaction; the whole batch rolls back if any op fails or the final
+     * state is invalid. See update_flow_structure tool docs for op shapes.
+     */
+    updateFlowStructure(flowId: string, operations: any[]): Promise<any>;
+    /**
+     * Delete a flow
+     */
+    deleteFlow(id: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * List or search user's flows. Pass `query` to filter by title/description.
+     * scope='user' (default) searches user's own flows; scope='public' searches
+     * published community/official entries.
+     */
+    listFlows(opts?: {
+        query?: string;
+        scope?: string;
+        limit?: number;
+    }): Promise<FlowListResponse>;
+    /**
+     * Get a flow run by ID
+     */
+    getFlowRun(id: string): Promise<FlowRun>;
+    /**
+     * List flow runs with optional filters
+     */
+    listFlowRuns(options?: {
+        flowId?: number;
+        status?: 'success' | 'error' | 'pending' | 'running';
+        page?: number;
+        perPage?: number;
+    }): Promise<FlowRunListResponse>;
+    /**
+     * Search chat message history using semantic search
+     */
+    searchChatHistory(options: {
+        query: string;
+        limit?: number;
+        role?: 'user' | 'assistant';
+        source?: 'chat' | 'heartbeat' | 'telegram';
+        from?: string;
+        to?: string;
+    }): Promise<ChatSearchResponse>;
+}
+export interface ChatSearchResult {
+    content: string;
+    role: string;
+    source: string;
+    relevance: number;
+    created_at: string;
+}
+export interface ChatSearchResponse {
+    results: ChatSearchResult[];
+}
+export declare class NodeStormApiError extends Error {
+    code: string;
+    statusCode: number;
+    errors?: string[];
+    constructor(message: string, code: string, statusCode: number, errors?: string[]);
+}

package/dist/client.js

@@ -0,0 +1,143 @@
+/**
+ * NodeStorm API Client
+ * Handles communication with the NodeStorm backend
+ */
+export class NodeStormClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl = 'https://nodestorm.ai') {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    async request(path, options = {}) {
+        const url = `${this.baseUrl}/api/v1${path}`;
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+                ...options.headers,
+            },
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            const error = data;
+            throw new NodeStormApiError(error.error, error.code, response.status, error.errors);
+        }
+        return data;
+    }
+    /**
+     * Create a new flow from a prompt or directly from JSON (admin-only).
+     */
+    async createFlow(params) {
+        return this.request('/flows', {
+            method: 'POST',
+            body: JSON.stringify(params),
+        });
+    }
+    /**
+     * Get a flow by ID
+     */
+    async getFlow(id) {
+        return this.request(`/flows/${id}`);
+    }
+    /**
+     * Update flow metadata. For structural changes (nodes/edges), use updateFlowStructure.
+     */
+    async updateFlow(id, flow) {
+        return this.request(`/flows/${id}`, {
+            method: 'PUT',
+            body: JSON.stringify({ flow }),
+        });
+    }
+    /**
+     * Apply atomic structural operations (edit/add/remove nodes and edges) to an existing flow.
+     * All ops apply in one transaction; the whole batch rolls back if any op fails or the final
+     * state is invalid. See update_flow_structure tool docs for op shapes.
+     */
+    async updateFlowStructure(flowId, operations) {
+        return this.request(`/flows/${flowId}/structure`, {
+            method: 'PATCH',
+            body: JSON.stringify({ operations }),
+        });
+    }
+    /**
+     * Delete a flow
+     */
+    async deleteFlow(id) {
+        return this.request(`/flows/${id}`, {
+            method: 'DELETE',
+        });
+    }
+    /**
+     * List or search user's flows. Pass `query` to filter by title/description.
+     * scope='user' (default) searches user's own flows; scope='public' searches
+     * published community/official entries.
+     */
+    async listFlows(opts = {}) {
+        const { query, scope = 'user', limit = 20 } = opts;
+        if (query || scope === 'public') {
+            const params = new URLSearchParams();
+            if (query)
+                params.set('query', query);
+            params.set('scope', scope);
+            params.set('limit', String(limit));
+            return this.request(`/flows/search?${params.toString()}`);
+        }
+        return this.request(`/flows?limit=${limit}`);
+    }
+    /**
+     * Get a flow run by ID
+     */
+    async getFlowRun(id) {
+        return this.request(`/flow-runs/${id}`);
+    }
+    /**
+     * List flow runs with optional filters
+     */
+    async listFlowRuns(options = {}) {
+        const params = new URLSearchParams();
+        if (options.flowId)
+            params.append('flow_id', options.flowId.toString());
+        if (options.status)
+            params.append('status', options.status);
+        if (options.page)
+            params.append('page', options.page.toString());
+        if (options.perPage)
+            params.append('per_page', options.perPage.toString());
+        const queryString = params.toString();
+        const path = queryString ? `/flow-runs?${queryString}` : '/flow-runs';
+        return this.request(path);
+    }
+    /**
+     * Search chat message history using semantic search
+     */
+    async searchChatHistory(options) {
+        const params = new URLSearchParams();
+        params.append('q', options.query);
+        if (options.limit)
+            params.append('limit', options.limit.toString());
+        if (options.role)
+            params.append('role', options.role);
+        if (options.source)
+            params.append('source', options.source);
+        if (options.from)
+            params.append('from', options.from);
+        if (options.to)
+            params.append('to', options.to);
+        return this.request(`/chat/search?${params.toString()}`);
+    }
+}
+export class NodeStormApiError extends Error {
+    code;
+    statusCode;
+    errors;
+    constructor(message, code, statusCode, errors) {
+        super(message);
+        this.name = 'NodeStormApiError';
+        this.code = code;
+        this.statusCode = statusCode;
+        this.errors = errors;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * NodeStorm MCP Server
+ *
+ * Provides tools for AI agents to create, read, update, and delete NodeStorm workflows.
+ *
+ * Environment variables:
+ * - NODESTORM_API_KEY (required): API key for authentication
+ * - NODESTORM_API_URL (optional): API base URL (default: https://nodestorm.ai)
+ */
+export {};