mcpgraph 0.1.14 → 0.1.16

package/docs/design.md

@@ -67,6 +67,7 @@ transform:
 - Allows complex rules (e.g., "if price > 100 and status == 'active'") as pure JSON objects
 - Declarative and observable
 - No embedded code execution
+- **Note:** `var` operations in JSON Logic rules are evaluated using JSONata, allowing full JSONata expression support (including `$previousNode()` function)
 
 **Resources:** [JSON Logic Documentation](https://jsonlogic.com/)
 
@@ -74,8 +75,14 @@ transform:
 ```yaml
 condition:
   and:
-    - ">": [{ var: "price" }, 100]
-    - "==": [{ var: "status" }, "active"]
+    - ">": [{ var: "entry.price" }, 100]
+    - "==": [{ var: "entry.status" }, "active"]
+```
+
+**Advanced Example with JSONata:**
+```yaml
+condition:
+  ">": [{ var: "$previousNode().count" }, 10]
 ```
 
 ## High-Level Design: The Graph Runner
@@ -124,10 +131,15 @@ The YAML configuration centers around MCP server and tool definitions:
    - Note: Entry and exit nodes are defined in the nodes section with a `tool` field indicating which tool they belong to
 3. **Nodes**: The directed graph of nodes that execute when tools are called. Node types include:
    - **`entry`**: Entry point for a tool's graph execution. Receives tool arguments and initializes execution context.
+     - **Output**: The tool input arguments (passed through as-is)
    - **`mcp`**: Calls an MCP tool on an internal or external MCP server using `callTool`
+     - **Output**: The MCP tool's response (parsed from the tool's content)
    - **`transform`**: Applies JSONata expressions to transform data between nodes
+     - **Output**: The result of evaluating the JSONata expression
    - **`switch`**: Uses JSON Logic to conditionally route to different nodes based on data
+     - **Output**: The node ID of the target node that was routed to (string)
    - **`exit`**: Exit point for a tool's graph execution. Extracts and returns the final result to the MCP tool caller
+     - **Output**: The output from the previous node in the execution history
 
 ### Example YAML Structure: count_files Tool
 

package/docs/execution-context-redesign.md

@@ -0,0 +1,284 @@
+# Execution Context & History Redesign
+
+## Rationale
+
+The current execution context design has several limitations that become apparent when considering loops, debugging, and observability:
+
+### Current Issues
+
+1. **No execution history**: Only current context is maintained; no record of past executions
+2. **Previous node tracking is a hack**: Tracked separately (`previousNodeId`) instead of being derived from history
+3. **Loops overwrite data**: Same node executing multiple times overwrites previous outputs in context
+4. **Context structure doesn't distinguish iterations**: Using node ID as key doesn't handle multiple executions of the same node
+5. **Can't reconstruct historical context**: No way to see what context was available to a node at the time it executed (for debugging)
+
+### Goals
+
+1. **Single source of truth**: Execution history should be the authoritative record
+2. **Handle loops gracefully**: Multiple executions of the same node should be accessible
+3. **Derive previous node from history**: No separate tracking needed
+4. **Time-travel debugging**: Reconstruct context at any point in execution
+5. **Powerful JSONata access**: Access all executions, not just latest
+6. **Backward compatibility**: Existing expressions should continue to work
+
+## Current Implementation
+
+### What We Have Now
+
+- **Execution History**: `NodeExecutionRecord[]` stored in `ExecutionContext`
+  - Each record: `nodeId`, `nodeType`, `startTime`, `endTime`, `duration`, `input`, `output`, `error`
+  - Used for telemetry and debugging hooks
+
+- **Current Context**: Separate `data` object keyed by node ID
+  - `this.data[nodeId] = output` (overwrites on loops)
+  - Used for JSONata/JSON Logic evaluation
+
+- **Previous Node Tracking**: Separate `previousNodeId` variable passed around
+
+### Problems
+
+1. **Redundancy**: Both history and context store node outputs
+2. **Input storage**: Storing `input` (full context) is redundant - can be derived from history
+3. **Loop handling**: Context overwrites, history has multiple records but can't distinguish them
+4. **Previous node**: Tracked separately instead of derived from history
+
+## Proposed Design
+
+### Core Insight
+
+**If execution is sequential (no parallelism), the execution history is just an ordered array of node executions where:**
+- Each execution's input is the context built from all previous executions
+- Previous node is just `history[index - 1]`
+- Context is built from history once per node execution (when node starts)
+- History is the single source of truth
+
+### Execution History Structure
+
+**Structure:**
+```typescript
+interface NodeExecutionRecord {
+  executionIndex: number;  // Position in overall execution history (0, 1, 2, ...) - unique identifier
+  nodeId: string;
+  nodeType: string;
+  startTime: number;
+  endTime: number;
+  duration: number;
+  output: unknown;    // Only store output, derive input from history
+  error?: Error;
+}
+
+class ExecutionContext {
+  private history: NodeExecutionRecord[] = [];
+  
+  getData(): Record<string, unknown> {
+    // Build context from history - called once per node execution
+    // The context is built when the node starts and used throughout its execution
+    return this.buildContextFromHistory();
+  }
+  
+  getPreviousNode(currentIndex: number): NodeExecutionRecord | null {
+    return currentIndex > 0 ? this.history[currentIndex - 1] : null;
+  }
+}
+```
+
+**Key Points:**
+- History array is the single source of truth
+- No separate `data` object
+- No `input` field in records (derivable from history)
+- Context built fresh from history once per node execution
+- Previous node derived from history index
+
+### Context Structure for JSONata Access
+
+We use a **flat context structure** with **history access functions**:
+
+**Context Building:**
+```typescript
+private buildContextFromHistory(): Record<string, unknown> {
+  const context: Record<string, unknown> = {};
+  // Walk backwards, most recent execution of each node wins
+  for (let i = this.history.length - 1; i >= 0; i--) {
+    const record = this.history[i];
+    if (!(record.nodeId in context)) {
+      context[record.nodeId] = record.output;
+    }
+  }
+  return context;
+}
+```
+
+**Example Context Object:**
+```json
+{
+  "entry_count_files": { "directory": "/path/to/dir" },
+  "list_directory_node": "[FILE] file1.txt\n[FILE] file2.txt",
+  "count_files_node": { "count": 2 }
+}
+```
+
+**If same node executes multiple times (loop):**
+```json
+{
+  "entry_loop": { "value": 0 },
+  "increment_node": { "value": 3 }  // Only latest execution
+}
+```
+
+**JSONata Access:**
+- `$.node_name` → latest output (backward compatible, simple notation)
+- `$.node_name.foo` → property access
+
+**Custom JSONata Functions (access history directly):**
+- `$previousNode()` → previous node's output (from history)
+- `$previousNode(index)` → node that executed N steps before current
+- `$executionCount(nodeName)` → count of executions for a node
+- `$nodeExecution(nodeName, index)` → specific execution by index (0 = first, -1 = last)
+- `$nodeExecutions(nodeName)` → array of all executions for a node
+
+**Example Usage:**
+```jsonata
+// Get previous node's output
+$previousNode()
+
+// Get execution count
+$executionCount("increment_node")  // Returns 3 if executed 3 times
+
+// Get first execution
+$nodeExecution("increment_node", 0)  // Returns { "value": 1 }
+
+// Get all executions
+$nodeExecutions("increment_node")  // Returns [{ "value": 1 }, { "value": 2 }, { "value": 3 }]
+
+// Get second-to-last execution
+$nodeExecution("increment_node", -2)  // Returns { "value": 2 }
+```
+
+**Implementation Note:**
+Functions receive the execution history array and current execution index as parameters, allowing them to query history directly without exposing it in the context structure.
+
+**Benefits:**
+- Simple, flat context structure (backward compatible)
+- Fast to build
+- Clean notation: `$.node_name` for latest
+- History access is explicit and clear
+- No namespace conflicts (no special keys in context)
+- Functions can provide powerful queries beyond simple data access
+- History queries are separate from context structure
+
+## Design Decisions
+
+### Input Storage
+
+**Decision**: Don't store `input` in `NodeExecutionRecord` - derive from history when needed.
+
+**Rationale**: No redundancy, can always derive input by building context from history up to that point.
+
+### Previous Node Resolution
+
+**Decision**: `$previousNode()` is a custom JSONata function that queries the history array.
+
+**Rationale**: Cleaner, more flexible, and keeps history access explicit.
+
+### Entry Node Handling
+
+**Decision**: Entry node's input is the tool input. When building context for the entry node, tool input is available as the entry node's output (stored in history).
+
+**Rationale**: Consistent with other nodes - tool input is the input to the entry node.
+
+### Execution Index
+
+**Decision**: Add `executionIndex` field to `NodeExecutionRecord` to uniquely identify each execution.
+
+**Rationale**: 
+- Provides a unique identifier for each execution (even when same node executes multiple times)
+- Enables API endpoints to reference specific executions (e.g., "get context for execution at index 5")
+- Makes it easy for debuggers to reference and query specific executions
+- The index represents the position in the overall execution history array (0, 1, 2, ...)
+
+## Implementation Plan
+
+### Phase 1: Refactor ExecutionContext
+
+1. Remove `data` object, keep only `history`
+2. Remove `input` from `NodeExecutionRecord` (derive from history)
+3. Add `executionIndex` to `NodeExecutionRecord` (set when adding to history)
+4. Implement `buildContextFromHistory(upToIndex?: number)` method:
+   - If `upToIndex` is provided, build context from history up to that index (for debugging)
+   - If not provided, build context from entire history (for current execution)
+5. Update `getData()` to build context from history once per node execution
+
+### Phase 2: Update Node Executors
+
+1. Remove `previousNodeId` parameter from all node executors
+2. Update `addHistory()` to include `executionIndex` (current history length)
+3. Update `addHistory()` calls to not pass `input` (or derive it)
+4. Update exit node to get previous node from history instead of `previousNodeId`
+
+### Phase 3: Update Expression Evaluation
+
+1. Context stays flat - no changes needed to context structure
+2. Add custom JSONata functions that receive history and current index:
+   - `$previousNode()` - returns previous node's output (from history)
+   - `$previousNode(index)` - returns node that executed N steps before current
+   - `$executionCount(nodeName)` - count of executions for a node
+   - `$nodeExecution(nodeName, index)` - specific execution by index (0 = first, -1 = last)
+   - `$nodeExecutions(nodeName)` - array of all executions for a node
+3. Update `evaluateJsonLogic()` to work with flat context and new functions
+4. Functions need access to:
+   - Execution history array
+   - Current execution index (to determine "previous")
+
+### Phase 4: Update Hooks and Telemetry
+
+1. Update hooks to derive input from history when needed
+2. Verify telemetry still works correctly (it already uses history structure, but verify after removing `input` field)
+3. Update introspection/debugging docs
+
+### Phase 5: Add Debugging API Endpoint
+
+1. Add `getContextForExecution(executionIndex: number)` method to API:
+   - Takes an `executionIndex` to identify a specific execution
+   - Builds context from history up to that execution index
+   - Returns the context that was available to that node when it executed
+   - Useful for time-travel debugging - "what context did this node see?"
+2. Add helper method `getExecutionByIndex(executionIndex: number)` to easily access a specific record
+
+### Phase 6: Testing & Documentation
+
+1. Add tests for loop scenarios
+2. Add tests for `$previousNode()` and other custom functions
+3. Add tests for `getContextForExecution()` API endpoint
+4. Update examples to show new capabilities
+5. Update documentation
+
+## Open Questions
+
+1. **Performance**: Is building context from history too slow? (Answer: No - we build it once per node execution when the node starts, and it's a simple loop through the history array)
+
+2. **Backward Compatibility**: Do we need to support old flat context structure? (Answer: Yes - the flat context structure maintains full backward compatibility - `$.node_name` works exactly as before)
+
+3. **History Persistence**: Should history be persisted across executions? (Answer: Not in scope for this redesign, but structure supports it)
+
+4. **Parallel Execution**: If we add parallel execution later, how does this design handle it? (Answer: Would need execution IDs or iteration numbers, but structure can accommodate)
+
+## Next Steps
+
+1. **Implementation**: Phase 1 (refactor ExecutionContext)
+   - Remove `data` object
+   - Remove `input` from `NodeExecutionRecord`
+   - Add `executionIndex` to `NodeExecutionRecord`
+   - Implement `buildContextFromHistory(upToIndex?)` method
+2. **Implementation**: Phase 2 (update node executors)
+   - Remove `previousNodeId` parameter from all node executors
+   - Update `addHistory()` to include `executionIndex` (current history length)
+   - Update exit node to get previous node from history instead of `previousNodeId`
+3. **Implementation**: Phase 3 (add history functions)
+   - Design function signatures (how to pass history/index to functions)
+   - Implement `$previousNode()`, `$executionCount()`, `$nodeExecution()`, `$nodeExecutions()`
+4. **Implementation**: Phase 5 (add debugging API)
+   - Add `getContextForExecution(executionIndex: number)` to API
+   - Add `getExecutionByIndex(executionIndex: number)` helper
+5. **Testing**: Ensure all existing tests pass
+6. **Testing**: Add loop tests, new function tests, and API endpoint tests
+

package/docs/implementation.md

@@ -133,6 +133,7 @@ JSON Logic library wrapper:
 - Rule evaluation with context data
 - Boolean results for routing decisions
 - Error handling
+- **Note:** `var` operations in JSON Logic rules are pre-processed and evaluated using JSONata, providing full JSONata expression support (including `$previousNode()` function) within JSON Logic rules
 
 ### 4.3 Expression Context
 
@@ -348,7 +349,7 @@ README updated with:
 
 1. **Custom Execution Engine**: A custom execution loop was implemented to provide full control over execution flow, enable observability (execution history), and support future debugging/introspection features.
 
-2. **Expression Evaluation**: All expressions (JSONata, JSON Logic) are evaluated with a consistent context where all data is referenced by node ID. Tool input is stored as the entry node's output (e.g., `$.entry_count_files.directory`), and each node's output is stored by its node ID (e.g., `$.list_directory_node`).
+2. **Expression Evaluation**: All expressions (JSONata, JSON Logic) are evaluated with a consistent context where all data is referenced by node ID. Tool input is stored as the entry node's output (e.g., `$.entry_count_files.directory`), and each node's output is stored by its node ID (e.g., `$.list_directory_node`). The `$previousNode()` function is available in all JSONata expressions (including those used in JSON Logic `var` operations) to access the output of the node that executed immediately before the current node.
 
 3. **Data Flow**: Data flows through nodes as a JSON object where each node's output is stored by its node ID. Each node can read from previous nodes (by their node IDs) and write its own output (stored by its node ID).
 

package/docs/introspection-debugging.md

@@ -364,17 +364,19 @@ Execution history provides a complete record of all node executions with detaile
 
 ```typescript
 interface NodeExecutionRecord {
+  executionIndex: number;  // Position in overall execution history (0, 1, 2, ...) - unique identifier
   nodeId: string;           // ID of the executed node
   nodeType: string;         // Type of node (entry, exit, transform, mcp, switch)
   startTime: number;        // Timestamp when node started (milliseconds)
   endTime: number;          // Timestamp when node ended (milliseconds)
   duration: number;         // Execution duration (milliseconds)
-  input: unknown;           // Input data for the node
   output: unknown;          // Output data from the node
   error?: Error;            // Error object if node failed
 }
 ```
 
+**Note**: The `input` field has been removed. Input context can be derived by building context from history up to the execution index using `getContextForExecution(executionIndex)`.
+
 ### Accessing History
 
 ```typescript
@@ -398,6 +400,31 @@ if (state) {
 }
 ```
 
+### Time-Travel Debugging
+
+You can get the context that was available to a specific execution using `getContextForExecution()`:
+
+```typescript
+// Get context for a specific execution
+const context = api.getContextForExecution(5);
+if (context) {
+  console.log('Context available to execution #5:', context);
+}
+
+// Get a specific execution record
+const record = api.getExecutionByIndex(5);
+if (record) {
+  console.log(`Execution #5: ${record.nodeId} executed at ${record.startTime}`);
+  console.log(`Output:`, record.output);
+  
+  // Get the context that was available to this execution
+  const inputContext = api.getContextForExecution(record.executionIndex);
+  console.log('Input context:', inputContext);
+}
+```
+
+**Note**: Both methods require an active execution with a controller (hooks/breakpoints enabled). They return `null` if no execution is in progress or the index is invalid.
+
 ## Telemetry
 
 Telemetry provides aggregated performance metrics and execution statistics.

package/examples/api-usage.ts

@@ -70,7 +70,7 @@ async function introspectionExample() {
   if (result.executionHistory) {
     console.log('\nExecution History:');
     for (const record of result.executionHistory) {
-      console.log(`  ${record.nodeId} (${record.nodeType}): ${record.duration}ms`);
+      console.log(`  [${record.executionIndex}] ${record.nodeId} (${record.nodeType}): ${record.duration}ms`);
     }
   }
 
@@ -88,6 +88,57 @@ async function introspectionExample() {
   await api.close();
 }
 
+// Example: Time-travel debugging with getContextForExecution
+async function timeTravelDebuggingExample() {
+  const api = new McpGraphApi('examples/count_files.yaml');
+
+  let executionIndexToInspect: number | null = null;
+  
+  const { promise, controller } = api.executeTool('count_files', {
+    directory: './tests/files',
+  }, {
+    hooks: {
+      onNodeComplete: async (nodeId, node, input, output, duration) => {
+        // When count_files_node completes, inspect the context that was available to list_directory_node
+        if (nodeId === 'count_files_node') {
+          // Find the execution index of list_directory_node
+          const state = api.getExecutionState();
+          if (state) {
+            const listDirRecord = state.executionHistory.find(r => r.nodeId === 'list_directory_node');
+            if (listDirRecord) {
+              executionIndexToInspect = listDirRecord.executionIndex;
+            }
+          }
+        }
+      },
+    },
+  });
+  
+  await promise;
+  
+  if (executionIndexToInspect !== null && controller) {
+    // Get the context that was available to list_directory_node when it executed
+    const context = api.getContextForExecution(executionIndexToInspect);
+    if (context) {
+      console.log('\nTime-Travel Debugging:');
+      console.log(`Context available to execution #${executionIndexToInspect} (list_directory_node):`);
+      console.log(JSON.stringify(context, null, 2));
+    }
+    
+    // Get the execution record itself
+    const record = api.getExecutionByIndex(executionIndexToInspect);
+    if (record) {
+      console.log(`\nExecution Record #${executionIndexToInspect}:`);
+      console.log(`  Node: ${record.nodeId}`);
+      console.log(`  Type: ${record.nodeType}`);
+      console.log(`  Duration: ${record.duration}ms`);
+      console.log(`  Output: ${JSON.stringify(record.output).substring(0, 100)}...`);
+    }
+  }
+  
+  await api.close();
+}
+
 // Example: Validate config without creating an API instance
 function validateConfigExample() {
   const errors = McpGraphApi.validateConfig('examples/count_files.yaml');
@@ -118,6 +169,8 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   
   if (exampleToRun === 'introspection') {
     introspectionExample().catch(console.error);
+  } else if (exampleToRun === 'debugging') {
+    timeTravelDebuggingExample().catch(console.error);
   } else {
     example().catch(console.error);
   }

package/examples/loop_example.yaml

@@ -0,0 +1,84 @@
+version: "1.0"
+
+# MCP Server Metadata
+server:
+  name: "loopExample"
+  version: "1.0.0"
+  description: "Example with a loop using history functions"
+
+# Tool Definitions
+tools:
+  - name: "sum_to_n"
+    description: "Sums numbers from 1 to n using a loop"
+    inputSchema:
+      type: "object"
+      properties:
+        n:
+          type: "number"
+          description: "The number to sum to"
+      required:
+        - n
+    outputSchema:
+      type: "object"
+      properties:
+        sum:
+          type: "number"
+          description: "The sum from 1 to n"
+
+# Graph Nodes
+nodes:
+  # Entry node: Receives tool arguments
+  - id: "entry_sum"
+    type: "entry"
+    tool: "sum_to_n"
+    next: "increment_node"
+  
+  # Increment counter and add to sum
+  # Uses $nodeExecution() to get the previous iteration of this node
+  # First iteration: $executionCount("increment_node") = 0, so we initialize
+  # Subsequent iterations: $nodeExecution("increment_node", -1) gets the last execution
+  - id: "increment_node"
+    type: "transform"
+    transform:
+      expr: |
+        $executionCount("increment_node") = 0
+          ? {
+              "counter": 1,
+              "sum": 1,
+              "target": $.entry_sum.n
+            }
+          : {
+              "counter": $nodeExecution("increment_node", -1).counter + 1,
+              "sum": $nodeExecution("increment_node", -1).sum + $nodeExecution("increment_node", -1).counter + 1,
+              "target": $.entry_sum.n
+            }
+    next: "check_condition"
+  
+  # Check if we should continue looping
+  - id: "check_condition"
+    type: "switch"
+    conditions:
+      - rule:
+          "<": [{"var": "$.increment_node.counter"}, {"var": "$.increment_node.target"}]
+        target: "increment_node"
+      - target: "exit_sum"
+  
+  # Exit node: Extracts the sum from increment_node
+  # Uses $previousNode() to verify it returns the switch node's output (target node ID)
+  # The output matches the tool's outputSchema (just the sum)
+  - id: "exit_sum"
+    type: "transform"
+    transform:
+      expr: |
+        $previousNode() = "exit_sum" ? {
+          "sum": $.increment_node.sum
+        } : {
+          "sum": 0,
+          "error": "previousNode check failed"
+        }
+    next: "exit_sum_final"
+  
+  # Final exit node
+  - id: "exit_sum_final"
+    type: "exit"
+    tool: "sum_to_n"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpgraph",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "MCP server that executes directed graphs of MCP server calls",
   "main": "dist/main.js",
   "type": "module",