mcpgraph 0.1.6 → 0.1.7

package/docs/design.md

@@ -0,0 +1,220 @@
+# mcpGraph Design Document
+
+## Overview
+
+This document memorializes the high-level design and tooling recommendations for mcpGraph, a product similar to n8n that surfaces an MCP interface and internally implements a directed graph of MCP server calls. The system enables filtering and reformatting data between nodes, makes routing decisions based on node output, and maintains a declarative, observable configuration without embedding a full programming language.
+
+## Core Architecture: The Orchestrator
+
+### Recommended Platform: TypeScript (Node.js)
+
+**Rationale:**
+- The MCP SDK is most mature in TypeScript
+- Frontend tools for visual graph editing (like React Flow) are industry standard
+- Strong ecosystem for both backend orchestration and frontend visualization
+
+### Graph Execution Engine
+
+The system implements a custom graph execution engine that orchestrates the directed graph of MCP server calls.
+
+**Design Approach:**
+- **Custom Execution Loop**: A lightweight, sequential execution loop that provides full control over execution flow
+- **Simple Architecture**: Direct mapping from YAML node definitions to execution, avoiding abstraction layers
+- **Data Flow**: Execution context maintains state and data flow between nodes
+- **Control Flow**: Supports conditional routing via switch nodes; cycles are supported for future loop constructs
+- **Observability**: Built-in execution history tracking for debugging and introspection
+
+**Implementation:**
+The YAML configuration is parsed into a graph structure (`Graph` class) and executed by a custom `GraphExecutor` that:
+- Starts at the tool's entry node
+- Executes nodes sequentially based on the graph structure
+- Tracks execution state and history
+- Routes conditionally via switch nodes
+- Continues until the exit node is reached
+
+### MCP Integration
+
+- Use `@modelcontextprotocol/sdk`
+- The system exposes an MCP server interface
+- The YAML configuration defines the MCP server metadata and the tools it exposes
+- Each tool definition includes standard MCP tool metadata (name, description, input/output parameters)
+- Each tool's graph has an explicit entry node that receives tool arguments and initializes execution
+- Each tool's graph has an explicit exit node that returns the final result to the MCP tool caller
+- Execution flows through the graph from entry node to exit node
+
+## Declarative Logic & Data Transformation
+
+To avoid embedding a full programming language while maintaining declarative, observable configurations, the system uses standardized expression engines.
+
+### Data Reformatting: JSONata
+
+**Why JSONata:**
+- Declarative query and transformation language for JSON
+- Single string expression enables clear observability
+- Can log input, expression, and output to debug transformations
+
+**Resources:** [JSONata Documentation](https://jsonata.org/)
+
+**YAML Example:**
+```yaml
+transform:
+  expr: "$merge([payload, {'timestamp': $now()}])"
+```
+
+### Routing Decisions: JSON Logic
+
+**Why JSON Logic:**
+- Allows complex rules (e.g., "if price > 100 and status == 'active'") as pure JSON objects
+- Declarative and observable
+- No embedded code execution
+
+**Resources:** [JSON Logic Documentation](https://jsonlogic.com/)
+
+**YAML Example:**
+```yaml
+condition:
+  and:
+    - ">": [{ var: "price" }, 100]
+    - "==": [{ var: "status" }, "active"]
+```
+
+## High-Level Design: The Graph Runner
+
+The system exposes an MCP server that reads a YAML configuration file. When a tool is called on this MCP server, it executes the corresponding graph starting at the tool's entry node and continuing until the exit node is reached.
+
+### The Workflow Lifecycle
+
+1. **Parse**: Read the YAML configuration into a structure containing MCP server metadata, tool definitions, and the directed graph of nodes
+2. **Initialize MCP Server**: Expose the MCP server with the tools defined in the configuration
+3. **Tool Invocation**: When a tool is called:
+   - Receive tool arguments from the MCP client
+   - Start graph execution at the tool's entry node
+   - Entry node receives tool arguments and initializes the execution context
+4. **Execute Node**:
+   - **Entry Node**: Receives tool arguments, initializes execution context, passes to next node
+   - **Pre-transform**: Apply JSONata to the incoming data to format the tool arguments (if node is an MCP tool call)
+   - **Call Tool**: Use the MCP SDK to `callTool` on the target server (if node is an MCP tool call)
+   - **Transform**: Apply JSONata expressions to transform data (if node is a transform node)
+   - **Route**: Evaluate JSON Logic against the current data state to decide which edge to follow next (if node is a switch/conditional)
+   - **Track History**: Record node execution with inputs and outputs for observability
+5. **Exit Node**: When execution reaches the exit node, extract the final result and return it to the MCP tool caller
+
+## Visual Tooling & Observability
+
+### Component Recommendations
+
+| Component | Tooling Recommendation |
+|-----------|----------------------|
+| **Visual Editor** | **React Flow** - Industry standard for node-based UIs, used by companies like Stripe and Typeform. Provides customizable nodes, edges, zooming, panning, and built-in components like MiniMap and Controls. [React Flow Documentation](https://reactflow.dev/) |
+| **Observability** | OpenTelemetry - wrap each node execution in a "Span" to see the "Trace" of data through the graph in tools like Jaeger |
+
+## Implementation Strategy: The YAML Standard
+
+Graph definitions should feel like Kubernetes manifests or GitHub Actions - declarative and version-controlled.
+
+### Configuration Structure
+
+The YAML configuration centers around MCP server and tool definitions:
+
+1. **MCP Server Metadata**: Defines the MCP server information (name, version, description)
+2. **Tools**: Array of tool definitions, each containing:
+   - Standard MCP tool metadata (name, description)
+   - Input parameters schema (MCP tool parameter definitions)
+   - Output schema (what the tool returns)
+   - 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.
+   - **`mcp`**: Calls an MCP tool on an internal or external MCP server using `callTool`
+   - **`transform`**: Applies JSONata expressions to transform data between nodes
+   - **`switch`**: Uses JSON Logic to conditionally route to different nodes based on data
+   - **`exit`**: Exit point for a tool's graph execution. Extracts and returns the final result to the MCP tool caller
+
+### Example YAML Structure: count_files Tool
+
+This example defines a `count_files` tool that takes a directory, lists its contents using the filesystem MCP server, counts the files, and returns the count:
+
+```yaml
+version: "1.0"
+
+# MCP Server Metadata
+server:
+  name: "fileUtils"
+  version: "1.0.0"
+  description: "File utilities"
+
+# Tool Definitions
+tools:
+  - name: "count_files"
+    description: "Counts the number of files in a directory"
+    inputSchema:
+      type: "object"
+      properties:
+        directory:
+          type: "string"
+          description: "The directory path to count files in"
+      required:
+        - directory
+    outputSchema:
+      type: "object"
+      properties:
+        count:
+          type: "number"
+          description: "The number of files in the directory"
+
+# MCP Servers used by the graph
+servers:
+  filesystem:
+    command: "npx"
+    args:
+      - "-y"
+      - "@modelcontextprotocol/server-filesystem"
+      - "./tests/files"
+
+# Graph Nodes
+nodes:
+  # Entry node: Receives tool arguments
+  - id: "entry_count_files"
+    type: "entry"
+    tool: "count_files"
+    next: "list_directory_node"
+  
+  # List directory contents
+  - id: "list_directory_node"
+    type: "mcp"
+    server: "filesystem"
+    tool: "list_directory"
+    args:
+      path: "$.input.directory"
+    next: "count_files_node"
+  
+  # Transform and count files
+  - id: "count_files_node"
+    type: "transform"
+    transform:
+      expr: |
+        { "count": $count($split(list_directory_node, "\n")) }
+    next: "exit_count_files"
+  
+  # Exit node: Returns the count
+  - id: "exit_count_files"
+    type: "exit"
+    tool: "count_files"
+```
+
+## Key Design Principles
+
+1. **Declarative Configuration**: All logic expressed in YAML using standard expression languages (JSONata, JSON Logic)
+2. **Observability**: Every transformation and decision is traceable and loggable
+3. **No Embedded Code**: Avoid full programming languages to maintain clarity and safety
+4. **Standard-Based**: Favor existing standards (JSONata, JSON Logic) over custom solutions
+5. **Visual First**: Graph should be viewable and editable through a visual interface
+6. **Execution Transparency**: Ability to observe graph execution in real-time
+
+## System Components
+
+1. **Executable**: Exposes an MCP server to run the graph (`mcpgraph` CLI)
+2. **Programmatic API**: Exports `McpGraphApi` class for programmatic use (e.g., by visualizer applications)
+3. **Graph Executor**: Core orchestration engine that executes the directed graph sequentially
+4. **Execution Context**: Tracks execution state, data flow, and history
+5. **Visual Editor**: Tools to visually view and edit the graph (future)
+6. **Execution Observer**: Ability to observe and debug graph execution (future - see `docs/future-introspection-debugging.md`)

package/docs/implementation.md

@@ -0,0 +1,377 @@
+# mcpGraph Implementation
+
+This document describes the implementation of the mcpGraph MCP server with graph execution capabilities. The visual editor/UX is deferred to a later phase.
+
+## Overview
+
+The implementation creates a working MCP server that can:
+1. Parse YAML configuration files
+2. Expose MCP tools defined in the configuration
+3. Execute directed graphs of nodes when tools are called
+4. Handle data transformation and routing between nodes
+
+## Phase 1: Foundation & Configuration Parsing
+
+### 1.1 Project Setup & Dependencies
+
+**Implemented:**
+- TypeScript project initialized
+- Logger (stderr only) implemented in `src/logger.ts`
+- All dependencies added:
+  - `@modelcontextprotocol/sdk` - MCP SDK
+  - `jsonata` - Data transformation
+  - `json-logic-js` - Conditional routing
+  - `js-yaml` - YAML parsing
+  - `zod` - Schema validation
+
+**Note:** A custom execution loop was implemented to provide full control over execution flow and enable future introspection/debugging capabilities.
+
+### 1.2 Type Definitions
+
+**File: `src/types/config.ts`**
+
+All TypeScript interfaces defined:
+- `McpGraphConfig` - Root configuration structure
+- `ServerMetadata` - MCP server metadata
+- `ToolDefinition` - Tool definition with input/output schemas (entry/exit nodes are defined in nodes with `tool` field)
+- `NodeDefinition` - Base node interface
+- `EntryNode` - Entry point node that receives tool arguments
+- `ExitNode` - Exit point node that returns final result
+- `McpNode` - MCP tool call node
+- `TransformNode` - JSONata transformation node
+- `SwitchNode` - JSON Logic routing node
+
+### 1.3 YAML Schema & Validation
+
+**File: `src/config/schema.ts`**
+
+Zod schemas implemented to validate YAML structure on load with clear error messages for invalid configurations.
+
+### 1.4 YAML Parser
+
+**File: `src/config/parser.ts`**
+
+YAML file parsing into structured configuration with validation against schema. Handles file I/O errors gracefully.
+
+### 1.5 Configuration Loader
+
+**File: `src/config/loader.ts`**
+
+Loads configuration from file path and returns parsed and validated configuration object.
+
+## Phase 2: Graph Structure & Representation
+
+### 2.1 Graph Data Structure
+
+**File: `src/graph/graph.ts`**
+
+Directed graph implementation from node definitions:
+- Node adjacency (edges) storage
+- Graph traversal utilities
+- Support for cycles
+
+### 2.2 Node Registry
+
+**Note:** Not implemented as separate file - functionality integrated into `Graph` class and `validator.ts`:
+- Node ID to node definition mapping
+- Node reference validation (tool references in entry/exit nodes, next, switch targets)
+- Orphaned node detection
+- Graph connectivity validation
+
+### 2.3 Graph Validator
+
+**File: `src/graph/validator.ts`**
+
+Graph structure validation:
+- All referenced nodes exist
+- All tools have exactly one entry and one exit node
+- Entry nodes are only referenced as tool entry points
+- Exit nodes are only referenced as tool exit points
+- Exit nodes are reachable from entry nodes
+- Detailed validation error messages
+
+## Phase 3: MCP Server Foundation
+
+### 3.1 MCP Server Setup
+
+**Note:** Not implemented as separate file - functionality integrated into `src/main.ts`:
+- MCP server initialization using `@modelcontextprotocol/sdk`
+- Stdio transport setup
+- Server lifecycle management
+
+### 3.2 Tool Registration
+
+**Note:** Not implemented as separate file - functionality integrated into `src/main.ts`:
+- Tool definitions converted to MCP tool schemas
+- Tools registered with MCP server
+- Tool names mapped to execution handlers
+
+### 3.3 Tool Execution Handler
+
+**Note:** Not implemented as separate file - functionality integrated into `src/main.ts`:
+- Tool invocation request handling
+- Tool argument extraction
+- Graph execution initiation at tool's entry node
+- Result return to MCP client
+
+## Phase 4: Expression Engines Integration
+
+### 4.1 JSONata Integration
+
+**File: `src/expressions/jsonata.ts`**
+
+JSONata library wrapper:
+- Expression evaluation with context data
+- Error handling
+- Support for JSONata references (e.g., `$.input.directory`)
+
+### 4.2 JSON Logic Integration
+
+**File: `src/expressions/json-logic.ts`**
+
+JSON Logic library wrapper:
+- Rule evaluation with context data
+- Boolean results for routing decisions
+- Error handling
+
+### 4.3 Expression Context
+
+**File: `src/execution/context.ts`**
+
+Expression evaluation context building:
+- Tool input arguments
+- Previous node outputs
+- Execution state
+- Data access for expressions
+
+**Note:** `src/expressions/context.ts` exists but functionality is primarily in `src/execution/context.ts`.
+
+## Phase 5: Node Execution
+
+### 5.1 Node Executor Base
+
+**Note:** Not implemented as separate base class - each executor is standalone with consistent execution pattern:
+- Pre-execution validation
+- Execute node logic
+- Post-execution processing
+- Determine next node(s)
+
+### 5.2 MCP Tool Node Executor
+
+**File: `src/execution/nodes/mcp-tool-executor.ts`**
+
+MCP tool node execution:
+- Pre-transform: Apply JSONata to format tool arguments
+- Call MCP tool using MCP client
+- Handle MCP call errors
+- Return output and next node
+
+### 5.3 Transform Node Executor
+
+**File: `src/execution/nodes/transform-executor.ts`**
+
+Transform node execution:
+- Apply JSONata transformation expression
+- Pass through data with transformation
+- Return transformed output and next node
+
+### 5.4 Switch Node Executor
+
+**File: `src/execution/nodes/switch-executor.ts`**
+
+Switch node execution:
+- Evaluate JSON Logic conditions in order
+- Select target node based on first matching condition
+- Handle default/fallback case (conditions without rules)
+- Return next node based on condition result
+
+### 5.5 Entry Node Executor
+
+**File: `src/execution/nodes/entry-executor.ts`**
+
+Entry node execution:
+- Receive tool arguments from MCP client
+- Initialize execution context with tool arguments
+- Make tool arguments available to subsequent nodes (e.g., `$.input.*`)
+- Pass execution to next node
+
+### 5.6 Exit Node Executor
+
+**File: `src/execution/nodes/exit-executor.ts`**
+
+Exit node execution:
+- Extract final result from execution context
+- Signal execution completion
+- Return final result to MCP tool caller
+
+## Phase 6: Graph Execution Engine
+
+### 6.1 Execution Context
+
+**File: `src/execution/context.ts`**
+
+Execution state management:
+- Current node tracking
+- Data context (tool inputs, node outputs)
+- Execution history
+- Error state
+- Data access for expressions
+
+### 6.2 Graph Executor
+
+**File: `src/execution/executor.ts`**
+
+Main graph execution orchestrator:
+- Custom sequential execution loop
+- Start at tool's entry node
+- Execute current node based on type (entry, mcp, transform, switch, exit)
+- Move to next node based on node's `next` field or switch routing
+- Continue until exit node is reached
+- Track execution history (node inputs/outputs)
+- Handle errors with context
+
+**Note:** The execution loop supports cycles (directed graphs with cycles), but infinite loops are prevented by the exit node check. Future loop node types can leverage this cycle support.
+
+### 6.3 Execution Flow
+
+**Note:** Not implemented as separate file - functionality integrated into `executor.ts`:
+- Node execution sequence coordination
+- Data flow between nodes
+- Branching (switch nodes)
+- Parallel execution support deferred
+
+## Phase 7: MCP Client for External Servers
+
+### 7.1 MCP Client Manager
+
+**File: `src/mcp/client-manager.ts`**
+
+MCP client connection management:
+- Connections to external MCP servers
+- Client connection caching
+- Connection lifecycle handling
+- Support for multiple concurrent servers
+
+### 7.2 MCP Client Factory
+
+**Note:** Not implemented as separate file - client creation functionality is in `client-manager.ts`:
+- MCP client creation for different server types
+- Stdio transport support
+- Client configuration
+
+### 7.3 Tool Call Handler
+
+**Note:** Not implemented as separate file - tool calling functionality is in `mcp-tool-executor.ts`:
+- `callTool` request execution to external MCP servers
+- Tool argument handling
+- Tool response processing
+- Error and timeout handling
+
+## Phase 8: Error Handling & Observability
+
+### 8.1 Error Types
+
+**Note:** Not implemented - using standard Error types:
+- Basic error handling works with standard Error
+- Custom error types (ConfigError, GraphError, ExecutionError, NodeError, McpError) would improve developer experience but are not required
+
+### 8.2 Error Handling
+
+**Note:** Basic error handling implemented throughout - centralized handler not implemented:
+- Error logging with context (via logger)
+- Error propagation through execution
+- Basic user-friendly error messages
+- Centralized error handler would be a nice-to-have enhancement
+
+### 8.3 Execution Logging
+
+**Note:** Basic logging implemented - structured execution logger not implemented:
+- Node execution events logged via basic logger
+- Structured logging would be valuable for debugging but basic logger works
+
+## Phase 9: Integration & Testing
+
+### 9.1 Main Entry Point
+
+**File: `src/main.ts`**
+
+Main entry point implementation:
+- Command-line argument parsing (config file path)
+- Configuration loading
+- Graph validation
+- MCP server startup
+- Tool registration
+- Tool execution handling
+- Graceful shutdown handling
+
+### 9.2 Integration Tests
+
+**Files: `tests/files.test.ts`, `tests/mcp-server.test.ts`, `tests/switch.test.ts`**
+
+Integration tests implemented:
+- Full execution flow with sample configs
+- Different node types tested
+- MCP client integration tested
+- Switch node conditional routing tested
+
+### 9.3 Sample Configurations
+
+**File: `examples/count_files.yaml`**
+
+Sample configuration implemented demonstrating:
+- Tool definition
+- Entry/exit nodes
+- MCP tool node
+- Transform node with JSONata
+
+## Phase 10: Polish & Documentation
+
+### 10.1 Code Documentation
+
+Basic JSDoc comments present on key functions. Comprehensive documentation would be a nice-to-have enhancement.
+
+### 10.2 Error Messages
+
+Basic error messages implemented. More helpful suggestions and context would improve developer experience.
+
+### 10.3 README Updates
+
+**File: `README.md`**
+
+README updated with:
+- Usage instructions
+- Installation from npm
+- MCP server configuration examples
+- Examples and configuration format documentation
+
+## Implementation Decisions
+
+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 that includes tool inputs and previous node outputs.
+
+3. **Data Flow**: Data flows through nodes as a JSON object that accumulates results. Each node can read from and write to this context.
+
+4. **Error Handling**: Errors at any node are caught, logged, and propagated. Basic error handling works; custom error types would be an enhancement.
+
+5. **MCP Client Management**: External MCP servers are managed as separate clients. The system maintains a registry of available MCP servers and their tools.
+
+6. **Code Organization**: Some planned separate files were integrated into existing files (e.g., server setup in main.ts, tool registration in main.ts). This works well and keeps the codebase simpler.
+
+## Future Considerations
+
+See `docs/future-introspection-debugging.md` for planned introspection and debugging features.
+
+Other future enhancements:
+- Visual editor/UX
+- Hot-reload of configuration
+- Loop node types (for, while, foreach)
+- Parallel node execution
+- Retry logic for failed nodes
+- Execution history persistence
+- Performance monitoring/metrics
+- OpenTelemetry integration
+- Custom error types
+- Structured execution logging
+- Centralized error handler
+

package/docs/introspection-debugging.md

@@ -0,0 +1,651 @@
+# Graph Introspection & Debugging
+
+This document explains how to use mcpGraph's introspection and debugging features to build visualizer applications, debuggers, and observability tools.
+
+## Overview
+
+mcpGraph provides comprehensive introspection and debugging capabilities that allow you to:
+
+- **Observe execution in real-time** using execution hooks
+- **Control execution flow** with pause, resume, and step operations
+- **Set breakpoints** on specific nodes
+- **Collect telemetry** including timing and performance metrics
+- **Inspect execution state** at any point during execution
+- **Access execution history** with detailed timing information
+
+All debugging features are **non-intrusive** - they only activate when explicitly enabled, ensuring normal execution remains unaffected.
+
+## Quick Start
+
+```typescript
+import { McpGraphApi, type ExecutionHooks } from 'mcpgraph';
+
+const api = new McpGraphApi('config.yaml');
+
+// Execute with debugging enabled
+const result = await api.executeTool('count_files', {
+  directory: './tests/files'
+}, {
+  hooks: {
+    onNodeStart: async (nodeId, node) => {
+      console.log(`Starting node: ${nodeId} (${node.type})`);
+    },
+    onNodeComplete: async (nodeId, node, input, output, duration) => {
+      console.log(`Node ${nodeId} completed in ${duration}ms`);
+    }
+  },
+  enableTelemetry: true
+});
+
+// Access execution history and telemetry
+console.log('History:', result.executionHistory);
+console.log('Telemetry:', result.telemetry);
+```
+
+## Execution Hooks
+
+Execution hooks allow you to observe and control execution at key points. All hooks are optional and are async functions. If you don't need to perform async operations, you can simply not use `await` - the function will still work correctly.
+
+### Available Hooks
+
+All hooks are async functions that return Promises:
+
+```typescript
+interface ExecutionHooks {
+  /**
+   * Called before a node executes
+   * Return false to pause execution (acts as a breakpoint)
+   */
+  onNodeStart?: (
+    nodeId: string,
+    node: NodeDefinition,
+    context: ExecutionContext
+  ) => Promise<boolean>;
+  
+  /**
+   * Called after a node completes successfully
+   */
+  onNodeComplete?: (
+    nodeId: string,
+    node: NodeDefinition,
+    input: unknown,
+    output: unknown,
+    duration: number
+  ) => Promise<void>;
+  
+  /**
+   * Called when a node encounters an error
+   */
+  onNodeError?: (
+    nodeId: string,
+    node: NodeDefinition,
+    error: Error,
+    context: ExecutionContext
+  ) => Promise<void>;
+  
+  /**
+   * Called when execution pauses (breakpoint hit or manual pause)
+   */
+  onPause?: (nodeId: string, context: ExecutionContext) => Promise<void>;
+  
+  /**
+   * Called when execution resumes
+   */
+  onResume?: () => Promise<void>;
+}
+```
+
+### Example: Real-time UI Updates
+
+All hooks are async functions. If you don't need async operations, you can simply not use `await`:
+
+```typescript
+const hooks: ExecutionHooks = {
+  // Async function - no await needed if you don't have async operations
+  onNodeStart: async (nodeId, node, context) => {
+    // Update UI synchronously
+    updateNodeStatus(nodeId, 'running');
+    highlightNode(nodeId);
+    return true; // Continue execution
+  },
+  
+  // Async function - can use await if needed
+  onNodeComplete: async (nodeId, node, input, output, duration) => {
+    // Update UI synchronously
+    updateNodeResult(nodeId, {
+      input,
+      output,
+      duration,
+      status: 'completed'
+    });
+    updateNodeVisualization(nodeId, output);
+    
+    // Or perform async operations if needed
+    // await logToServer(nodeId, output);
+  },
+  
+  onNodeError: async (nodeId, node, error, context) => {
+    // Error handling
+    showError(nodeId, error);
+    updateNodeStatus(nodeId, 'error');
+  }
+};
+
+await api.executeTool('my_tool', {}, { hooks });
+```
+
+## Execution Controller
+
+The execution controller provides programmatic control over execution flow. It's available during execution when hooks or breakpoints are enabled.
+
+### Getting the Controller
+
+```typescript
+// Start execution with hooks/breakpoints
+const executionPromise = api.executeTool('my_tool', {}, {
+  hooks: { /* ... */ },
+  breakpoints: ['node_1', 'node_2']
+});
+
+// Get controller (available during execution)
+const controller = api.getController();
+if (controller) {
+  // Use controller methods
+  controller.pause();
+  controller.resume();
+  await controller.step();
+}
+```
+
+### Controller Methods
+
+```typescript
+interface ExecutionController {
+  /**
+   * Pause execution at the next node boundary
+   * Only valid when status is "running"
+   */
+  pause(): void;
+  
+  /**
+   * Resume execution
+   * Only valid when status is "paused"
+   */
+  resume(): void;
+  
+  /**
+   * Step to the next node (step over)
+   * Only valid when status is "paused"
+   */
+  step(): Promise<void>;
+  
+  /**
+   * Get current execution state
+   */
+  getState(): ExecutionState;
+  
+  /**
+   * Set breakpoints
+   */
+  setBreakpoints(nodeIds: string[]): void;
+  
+  /**
+   * Clear breakpoints
+   */
+  clearBreakpoints(): void;
+}
+```
+
+### Example: Step-through Debugging
+
+```typescript
+const hooks: ExecutionHooks = {
+  onPause: async (nodeId, context) => {
+    console.log(`Paused at node: ${nodeId}`);
+    // Show debugger UI
+    showDebuggerUI();
+  },
+  onResume: async () => {
+    console.log('Resuming execution');
+    hideDebuggerUI();
+  }
+};
+
+// Start execution
+const executionPromise = api.executeTool('my_tool', {}, {
+  hooks,
+  breakpoints: ['entry_node'] // Start paused
+});
+
+// In your UI event handlers:
+function handleStep() {
+  const controller = api.getController();
+  if (controller) {
+    await controller.step();
+  }
+}
+
+function handlePause() {
+  const controller = api.getController();
+  if (controller) {
+    controller.pause();
+  }
+}
+
+function handleResume() {
+  const controller = api.getController();
+  if (controller) {
+    controller.resume();
+  }
+}
+```
+
+## Breakpoints
+
+Breakpoints allow you to pause execution at specific nodes. You can set breakpoints in two ways:
+
+### 1. Via Execution Options
+
+```typescript
+await api.executeTool('my_tool', {}, {
+  breakpoints: ['node_1', 'node_2', 'node_3']
+});
+```
+
+### 2. Via Execution Controller
+
+```typescript
+const controller = api.getController();
+if (controller) {
+  // Set breakpoints dynamically
+  controller.setBreakpoints(['node_1', 'node_2']);
+  
+  // Clear all breakpoints
+  controller.clearBreakpoints();
+}
+```
+
+### 3. Via onNodeStart Hook
+
+```typescript
+const hooks: ExecutionHooks = {
+  onNodeStart: async (nodeId, node, context) => {
+    // Conditional breakpoint logic
+    if (shouldBreak(nodeId, context)) {
+      return false; // Pause execution
+    }
+    return true; // Continue
+  }
+};
+```
+
+## Execution State
+
+The execution state provides a snapshot of the current execution status, including:
+
+- **Status**: Current execution status (`not_started`, `running`, `paused`, `finished`, `error`)
+- **Current Node**: The node currently executing (or null)
+- **Execution History**: Complete history of all executed nodes
+- **Context**: The current execution context with all data
+
+### Getting Execution State
+
+```typescript
+// During execution
+const state = api.getExecutionState();
+if (state) {
+  console.log('Status:', state.status);
+  console.log('Current Node:', state.currentNodeId);
+  console.log('History:', state.executionHistory);
+  console.log('Context:', state.context.getData());
+}
+
+// Or via controller
+const controller = api.getController();
+if (controller) {
+  const state = controller.getState();
+  // Same state object
+}
+```
+
+### Execution Status
+
+```typescript
+type ExecutionStatus = 
+  | "not_started"  // Execution hasn't begun
+  | "running"      // Execution is actively running
+  | "paused"       // Execution is paused (can resume/step)
+  | "finished"     // Execution completed successfully
+  | "error";       // Execution failed with an error
+```
+
+### Execution State Interface
+
+```typescript
+interface ExecutionState {
+  status: ExecutionStatus;
+  currentNodeId: string | null;
+  executionHistory: NodeExecutionRecord[];
+  context: ExecutionContext;
+  error?: Error; // Present when status is "error"
+}
+```
+
+## Execution History
+
+Execution history provides a complete record of all node executions with detailed timing information.
+
+### History Record Structure
+
+```typescript
+interface NodeExecutionRecord {
+  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
+}
+```
+
+### Accessing History
+
+```typescript
+// From execution result
+const result = await api.executeTool('my_tool', {}, {
+  enableTelemetry: true
+});
+
+for (const record of result.executionHistory || []) {
+  console.log(`${record.nodeId}: ${record.duration}ms`);
+  if (record.error) {
+    console.error(`Error: ${record.error.message}`);
+  }
+}
+
+// From execution state (during execution)
+const state = api.getExecutionState();
+if (state) {
+  const history = state.executionHistory;
+  // Access history during execution
+}
+```
+
+## Telemetry
+
+Telemetry provides aggregated performance metrics and execution statistics.
+
+### Telemetry Structure
+
+```typescript
+interface ExecutionTelemetry {
+  totalDuration: number;              // Total execution time (milliseconds)
+  nodeDurations: Map<string, number>; // Total duration per node type
+  nodeCounts: Map<string, number>;     // Execution count per node type
+  errorCount: number;                  // Total number of errors
+}
+```
+
+### Collecting Telemetry
+
+```typescript
+const result = await api.executeTool('my_tool', {}, {
+  enableTelemetry: true // Enable telemetry collection
+});
+
+if (result.telemetry) {
+  console.log(`Total duration: ${result.telemetry.totalDuration}ms`);
+  console.log(`Errors: ${result.telemetry.errorCount}`);
+  
+  // Node type statistics
+  for (const [nodeType, duration] of result.telemetry.nodeDurations) {
+    const count = result.telemetry.nodeCounts.get(nodeType) || 0;
+    console.log(`${nodeType}: ${count} executions, ${duration}ms total`);
+  }
+}
+```
+
+### Example: Performance Analysis
+
+```typescript
+function analyzePerformance(telemetry: ExecutionTelemetry) {
+  const avgDurations = new Map<string, number>();
+  
+  for (const [nodeType, totalDuration] of telemetry.nodeDurations) {
+    const count = telemetry.nodeCounts.get(nodeType) || 1;
+    const avgDuration = totalDuration / count;
+    avgDurations.set(nodeType, avgDuration);
+  }
+  
+  // Find slowest node types
+  const sorted = Array.from(avgDurations.entries())
+    .sort((a, b) => b[1] - a[1]);
+  
+  console.log('Slowest node types:');
+  for (const [nodeType, avgDuration] of sorted) {
+    console.log(`  ${nodeType}: ${avgDuration.toFixed(2)}ms average`);
+  }
+}
+```
+
+## Complete Example: Visualizer Application
+
+Here's a complete example of how to build a visualizer application:
+
+```typescript
+import { McpGraphApi, type ExecutionHooks, type ExecutionState } from 'mcpgraph';
+
+class GraphVisualizer {
+  private api: McpGraphApi;
+  private executionPromise: Promise<any> | null = null;
+  
+  constructor(configPath: string) {
+    this.api = new McpGraphApi(configPath);
+  }
+  
+  async executeWithVisualization(toolName: string, args: Record<string, unknown>) {
+    const hooks: ExecutionHooks = {
+      onNodeStart: async (nodeId, node, context) => {
+        this.updateNodeStatus(nodeId, 'running');
+        this.highlightNode(nodeId);
+        return true;
+      },
+      
+      onNodeComplete: async (nodeId, node, input, output, duration) => {
+        this.updateNodeStatus(nodeId, 'completed');
+        this.updateNodeData(nodeId, { input, output, duration });
+        this.unhighlightNode(nodeId);
+      },
+      
+      onNodeError: async (nodeId, node, error, context) => {
+        this.updateNodeStatus(nodeId, 'error');
+        this.showError(nodeId, error);
+      },
+      
+      onPause: async (nodeId, context) => {
+        this.showDebuggerControls();
+        this.updateExecutionStatus('paused');
+      },
+      
+      onResume: async () => {
+        this.hideDebuggerControls();
+        this.updateExecutionStatus('running');
+      }
+    };
+    
+    this.executionPromise = this.api.executeTool(toolName, args, {
+      hooks,
+      enableTelemetry: true
+    });
+    
+    const result = await this.executionPromise;
+    this.executionPromise = null;
+    
+    // Display results
+    this.displayHistory(result.executionHistory || []);
+    this.displayTelemetry(result.telemetry);
+    
+    return result;
+  }
+  
+  pause() {
+    const controller = this.api.getController();
+    if (controller) {
+      controller.pause();
+    }
+  }
+  
+  resume() {
+    const controller = this.api.getController();
+    if (controller) {
+      controller.resume();
+    }
+  }
+  
+  async step() {
+    const controller = this.api.getController();
+    if (controller) {
+      await controller.step();
+    }
+  }
+  
+  setBreakpoints(nodeIds: string[]) {
+    const controller = this.api.getController();
+    if (controller) {
+      controller.setBreakpoints(nodeIds);
+    }
+  }
+  
+  getCurrentState(): ExecutionState | null {
+    return this.api.getExecutionState();
+  }
+  
+  // UI update methods (implement based on your UI framework)
+  private updateNodeStatus(nodeId: string, status: string) { /* ... */ }
+  private highlightNode(nodeId: string) { /* ... */ }
+  private unhighlightNode(nodeId: string) { /* ... */ }
+  private updateNodeData(nodeId: string, data: any) { /* ... */ }
+  private showError(nodeId: string, error: Error) { /* ... */ }
+  private showDebuggerControls() { /* ... */ }
+  private hideDebuggerControls() { /* ... */ }
+  private updateExecutionStatus(status: string) { /* ... */ }
+  private displayHistory(history: any[]) { /* ... */ }
+  private displayTelemetry(telemetry: any) { /* ... */ }
+}
+```
+
+## API Reference
+
+### McpGraphApi Methods
+
+```typescript
+class McpGraphApi {
+  /**
+   * Execute a tool with optional debugging options
+   */
+  async executeTool(
+    toolName: string,
+    toolArguments: Record<string, unknown>,
+    options?: ExecutionOptions
+  ): Promise<ExecutionResult>;
+  
+  /**
+   * Get the execution controller (available during execution)
+   */
+  getController(): ExecutionController | null;
+  
+  /**
+   * Get the current execution state (if execution is in progress)
+   */
+  getExecutionState(): ExecutionState | null;
+  
+  /**
+   * Get the graph structure
+   */
+  getGraph(): Graph;
+  
+  /**
+   * Get the full configuration
+   */
+  getConfig(): McpGraphConfig;
+}
+```
+
+### ExecutionOptions
+
+```typescript
+interface ExecutionOptions {
+  hooks?: ExecutionHooks;      // Execution hooks for observation/control
+  breakpoints?: string[];      // Node IDs to pause at
+  enableTelemetry?: boolean;   // Enable telemetry collection
+}
+```
+
+### ExecutionResult
+
+```typescript
+interface ExecutionResult {
+  result: unknown;                          // The tool's result
+  structuredContent?: Record<string, unknown>; // Structured result (for MCP)
+  executionHistory?: NodeExecutionRecord[];    // Execution history
+  telemetry?: ExecutionTelemetry;              // Performance telemetry
+}
+```
+
+## Type Exports
+
+All types are exported from the main package:
+
+```typescript
+import {
+  McpGraphApi,
+  type ExecutionHooks,
+  type ExecutionController,
+  type ExecutionState,
+  type ExecutionStatus,
+  type ExecutionOptions,
+  type ExecutionResult,
+  type NodeExecutionRecord,
+  type ExecutionTelemetry,
+  type NodeDefinition,
+  type McpGraphConfig
+} from 'mcpgraph';
+```
+
+## Best Practices
+
+1. **Enable telemetry only when needed**: Telemetry collection adds overhead, so only enable it when you need performance metrics.
+
+2. **Use hooks for real-time updates**: Hooks are perfect for updating UI in real-time as execution progresses.
+
+3. **All hooks are async**: All hooks are async functions. If you don't need to perform async operations, you can simply not use `await` - the function will still work correctly. This provides consistency and allows you to add async operations later without changing the function signature.
+
+4. **Clean up after execution**: The controller is automatically cleaned up after execution completes, but you should check for `null` when accessing it.
+
+5. **Check execution state before operations**: Always verify that execution is in the correct state before calling controller methods (e.g., don't call `resume()` when status is `"running"`).
+
+6. **Use breakpoints for debugging**: Breakpoints are more efficient than conditional logic in hooks for simple pause-on-node scenarios.
+
+## Limitations
+
+- **Controller availability**: The controller is only available during execution when hooks or breakpoints are enabled. After execution completes, it's cleaned up.
+
+
+- **State modification**: You cannot modify execution context during paused execution (this may be added in future versions).
+
+- **Concurrent executions**: Each `McpGraphApi` instance supports one execution at a time. For concurrent executions, create multiple instances.
+
+## Future Enhancements
+
+Planned enhancements include:
+
+- Conditional breakpoints (break when expression evaluates to true)
+- Watch expressions (monitor specific values during execution)
+- State modification during paused execution
+- Execution replay from history
+- Execution comparison (compare multiple runs)
+- OpenTelemetry integration for distributed tracing
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpgraph",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "MCP server that executes directed graphs of MCP server calls",
   "main": "dist/main.js",
   "type": "module",
@@ -16,6 +16,7 @@
   "files": [
     "dist",
     "examples",
+    "docs",
     "README.md",
     "LICENSE"
   ],