mcpGraph

MCP server that executes directed graphs of MCP server calls.

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 expressions to transform data between nodes

• Conditional Routing: Use JSON Logic for conditional branching

• Observable: Every transformation and decision is traceable

• No Embedded Code: All logic expressed using standard expression languages (JSONata, JSON Logic)

Example

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

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.

• mcp_tool: Calls an MCP tool on an internal or external MCP server.

• transform: Applies JSONata expressions to transform data between nodes.

• switch: Uses JSON Logic to conditionally route to different nodes.

• exit: Exit point that returns the final result to the MCP tool caller.

Setup

1. Install dependencies:

2. Build the project:

3. Run the project:

Or run in development mode (with hot reload):

Running Tests

See docs/test-setup.md for information on setting up the testing environment, including the filesystem MCP server configuration.

Development

• Source code is in src/

• Build output goes to dist/

• TypeScript configuration is in tsconfig.json

• Example configurations are in examples/

• Tests are in tests/

Documentation

• Design Document - Complete design and architecture

• Implementation Plan - Implementation details and phases

• Test Setup - Testing environment setup