# McpGraph

> MCP server that runs a directed graph of MCP servers

- **Type:** MCP server
- **Install:** `agentstack add mcp-teamsparkai-mcpgraph`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [TeamSparkAI](https://agentstack.voostack.com/s/teamsparkai)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [TeamSparkAI](https://github.com/TeamSparkAI)
- **Source:** https://github.com/TeamSparkAI/mcpGraph

## Install

```sh
agentstack add mcp-teamsparkai-mcpgraph
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcpGraph

MCP server that executes directed graphs of MCP server calls.

> **📖 Learn More:** Read [**mcpGraph: A No-Code Alternative to "Code Mode"**](docs/no-code-code-mode.md) to understand how mcpGraph provides the context efficiency and accuracy of Code Mode while maintaining the security and observability of a no-code solution.

> **🎥 Watch the Demo:** Check out the [**mcpGraph Overview and mcpGraphUX Demo**](https://youtu.be/eyC7OzuB6c4) video to see mcpGraph in action and explore the visual debugging capabilities of mcpGraphUX.

> **🎥 Watch the Demo:** Check out the [**mcpGraphToolkit Deep Dive**](https://youtu.be/gR7s0MD8Gro) video to see an agent autonomously build, test, and deploy orchestration tools—"Code Mode" without the code.

## Overview

mcpGraph is an MCP (Model Context Protocol) server that exposes tools defined by declarative YAML configurations. Each tool executes a directed graph of nodes that can call other MCP tools, transform data, and make routing decisions, all without embedding a full programming language.

**Key Features:**
- **Declarative Configuration**: Define tools and their execution graphs in YAML
- **Data Transformation**: Use [JSONata](https://jsonata.org/) expressions to transform data between nodes
- **Conditional Routing**: Use [JSON Logic](https://jsonlogic.com/) for conditional branching
- **Observable**: Every transformation and decision is traceable
- **No Embedded Code**: All logic expressed using standard expression languages ([JSONata](https://jsonata.org/), [JSON Logic](https://jsonlogic.com/))

**Related Tools:**
- **mcpGraphUX**: A visual debugging and development environment for mcpGraph. Visualize graph structures, animate through active nodes during execution, set breakpoints, and inspect node inputs and outputs. See the [mcpGraphUX repository](https://github.com/TeamSparkAI/mcpGraph-ux) for details.
- **mcpGraphToolkit**: An MCP server that provides tools for building, testing, and managing mcpGraph tools. Use it to discover available MCP servers, test expressions, and create graph tools interactively. See [mcpGraphToolkit Overview](docs/toolkit.md) for details.

## Example

Here's a simple example that counts files in a directory:

```yaml
version: "1.0"

# MCP Server Metadata
server:
  name: "fileUtils"
  version: "1.0.0"
  title: "File utilities"
  instructions: "This server provides file utility tools for counting files and calculating total file sizes in directories."

# Optional: Execution limits to prevent infinite loops
executionLimits:
  maxNodeExecutions: 1000      # Maximum total node executions (default: 1000)
  maxExecutionTimeMs: 300000   # Maximum execution time in milliseconds (default: 300000 = 5 minutes)

# MCP Servers used by the graph
mcpServers:
  filesystem:
    command: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "./tests/counting"

# 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"
    nodes:
      # Entry node: Receives tool arguments
      - id: "entry"
        type: "entry"
        next: "list_directory_node"
      
      # List directory contents
      - id: "list_directory_node"
        type: "mcp"
        server: "filesystem"
        tool: "list_directory"
        args:
          path:
            expr: "$.entry.directory"
        next: "count_files_node"
      
      # Transform and count files
      - id: "count_files_node"
        type: "transform"
        transform:
          expr: '{ "count": $count($split($.list_directory_node.content, "\n")) }'
        next: "exit"
      
      # Exit node: Returns the count
      - id: "exit"
        type: "exit"
```

This graph:
1. Receives a directory path as input
2. Calls the filesystem MCP server's `list_directory` tool
3. Transforms the result to count files using JSONata
4. Returns the count

## Node Types

- **`entry`**: Entry point for a tool's graph execution. Receives tool arguments.
  - **Output**: The tool input arguments (passed through as-is)
- **`mcp`**: Calls an MCP tool on an internal or external MCP server.
  - **Output**: The MCP tool's response (parsed from the tool's content)
- **`transform`**: Applies [JSONata](https://jsonata.org/) expressions to transform data between nodes.
  - **Output**: The result of evaluating the JSONata expression
  - **Expression Format**: The `expr` field is a string containing a JSONata expression. Use single-quoted strings for simple expressions: `expr: '{ "result": "value" }'`. Use block scalars (`|`) for complex multi-line expressions to improve readability.
- **`switch`**: Uses [JSON Logic](https://jsonlogic.com/) to conditionally route to different nodes. Note: `var` operations in JSON Logic rules are evaluated using JSONata, allowing full JSONata expression support.
  - **Output**: The node ID of the target node that was routed to (string)
- **`exit`**: Exit point that returns the final result to the MCP tool caller.
  - **Output**: The output from the previous node in the execution history

## Execution History & Debugging

mcpGraph maintains a complete execution history for each tool execution, enabling powerful debugging and introspection capabilities:

- **Execution History**: Every node execution is recorded with timing, outputs, and a unique `executionIndex` (sequential: 0, 1, 2, ...)
- **Context Structure**: Context for expressions is built from history - a flat structure where each node ID maps to its latest output
  - Simple notation: `$.node_id` accesses the latest output of a node
  - When nodes execute multiple times (loops), context shows the most recent execution
  - History functions provide access to all executions, not just the latest
- **Time-Travel Debugging**: Get the context that was available to any specific execution using `getContextForExecution(executionIndex)`
- **History Functions**: Use JSONata functions to access execution history:
  - `$previousNode()` - Get the previous node's output
  - `$previousNode(index)` - Get the node that executed N steps before current
  - `$executionCount(nodeName)` - Count how many times a node executed
  - `$nodeExecution(nodeName, index)` - Get a specific execution of a node (0 = first, -1 = last)
  - `$nodeExecutions(nodeName)` - Get all executions of a node as an array
- **Loop Support**: Nodes can execute multiple times in loops, with each execution tracked separately in history

See [docs/introspection-debugging.md](docs/introspection-debugging.md) for detailed documentation on debugging features.

**Context Access:**
- All node outputs are accessible by node ID (e.g., `$.entry.directory`, `$.list_directory_node`)
- Latest execution wins: `$.increment_node` returns the most recent output when a node executes multiple times
- History functions are available in all JSONata expressions (including those used in JSON Logic `var` operations)

### JSONata Expression Format

The `expr` field in transform nodes is a string containing a JSONata expression. In YAML, you can use either:

- **Single-quoted strings** (`'...'`) for simple, single-line expressions:
  ```yaml
  transform:
    expr: '{ "count": $count($split($.list_directory_node.content, "\n")) }'
  ```
  This keeps the expression on one line and is ideal for simple transformations.

- **Block scalars** (`|`) for complex, multi-line expressions:
  ```yaml
  transform:
    expr: |
      $executionCount("increment_node") = 0
        ? { "counter": 1, "sum": 1, "target": $.entry_sum.n }
        : { "counter": $nodeExecution("increment_node", -1).counter + 1, ... }
  ```
  This improves readability for expressions with conditional logic, nested objects, or multiple operations.

Both forms work identically - the expression is evaluated as a string by JSONata. Use single quotes for simple expressions and block scalars for complex ones to improve readability.

## For Developers

If you're interested in contributing to mcpGraph or working with the source code, see [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, development guidelines, and project structure.

## Installation

Install mcpGraph from npm:

```bash
npm install -g mcpgraph
```

Or install locally in your project:

```bash
npm install mcpgraph
```

## Configuration

### Execution Limits

mcpGraph supports cyclical graphs, which requires guardrails to prevent infinite loops. Execution limits can be configured at the graph level:

```yaml
version: "1.0"

server:
  name: "myServer"          # Required: unique identifier
  version: "1.0.0"          # Required: server version
  title: "My MCP server"    # Optional: display name (defaults to name if not provided)
  instructions: "Instructions for using this server"  # Optional: server usage instructions

# Optional: Execution limits to prevent infinite loops
executionLimits:
  maxNodeExecutions: 1000      # Maximum total node executions (default: 1000)
  maxExecutionTimeMs: 300000   # Maximum execution time in milliseconds (default: 300000 = 5 minutes)

tools:
  # ... tool definitions ...
```

**Execution Limits:**
- **`maxNodeExecutions`** (optional): Maximum number of node executions across the entire graph. Default: `1000`. If execution reaches this limit, an error is thrown.
- **`maxExecutionTimeMs`** (optional): Maximum wall-clock time for graph execution in milliseconds. Default: `300000` (5 minutes). If execution exceeds this time, an error is thrown.

Both limits are checked before each node execution. If either limit is exceeded, execution stops immediately with a clear error message indicating which limit was hit.

**Note:** These limits are optional. If not specified, the defaults apply. They can be set to higher values for long-running batch jobs or lower values for quick operations.

### As an MCP Server

To use `mcpgraph` as an MCP server in an MCP client (such as Claude Desktop), add it to your MCP client's configuration file.

#### Claude Desktop Configuration

Add `mcpgraph` to your Claude Desktop MCP configuration (typically located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "mcpgraph": {
      "command": "mcpgraph",
      "args": [
        "-g",
        "/path/to/your/config.yaml"
      ]
    }
  }
}
```

Or if not installed (run from npm):

```json
{
  "mcpServers": {
    "mcpgraph": {
      "command": "npx",
      "args": [
        "-y",
        "mcpgraph",
        "-g",
        "/path/to/your/config.yaml"
      ]
    }
  }
}
```

**Note:** Replace `/path/to/your/config.yaml` with the actual path to your YAML configuration file. The `-g` (or `--graph`) flag specifies the graph configuration file to use.

### Programmatic API

The `mcpgraph` package exports a programmatic API that can be used in your own applications (e.g., for building a UX server or other interfaces):

```typescript
import { McpGraphApi } from 'mcpgraph';

// Create an API instance (loads and validates config)
const api = new McpGraphApi('path/to/config.yaml');

// List all available tools
const tools = api.listTools();

// Execute a tool
const result = await api.executeTool('count_files', {
  directory: './tests/counting',
});

// Clean up resources
await api.close();
```

See [`examples/api-usage.ts`](examples/api-usage.ts) for a complete example.

## Documentation

- [Contributing Guide](CONTRIBUTING.md) - Setup, development, and contribution guidelines
- [Design Document](docs/design.md) - Complete design and architecture
- [Implementation](docs/implementation.md) - Implementation details and architecture
- [Introspection & Debugging](docs/introspection-debugging.md) - Guide for building visualizer applications and debuggers

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TeamSparkAI](https://github.com/TeamSparkAI)
- **Source:** [TeamSparkAI/mcpGraph](https://github.com/TeamSparkAI/mcpGraph)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-teamsparkai-mcpgraph
- Seller: https://agentstack.voostack.com/s/teamsparkai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.