mcpgraph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TeamSpark, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# 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](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/))
+
+## Example
+
+Here's a simple example that counts files in a directory:
+
+```yaml
+version: "1.0"
+
+server:
+  name: "mcpGraph"
+  version: "1.0.0"
+  description: "MCP server that executes directed graphs of MCP tool calls"
+
+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"
+    entryNode: "entry_count_files"
+    exitNode: "exit_count_files"
+
+nodes:
+  - id: "entry_count_files"
+    type: "entry"
+    next: "list_directory_node"
+  
+  - id: "list_directory_node"
+    type: "mcp_tool"
+    server: "filesystem"
+    tool: "list_directory"
+    args:
+      path: "$.input.directory"
+    next: "count_files_node"
+  
+  - id: "count_files_node"
+    type: "transform"
+    transform:
+      expr: |
+        { "count": $count($split(list_directory_node, "\n")) }
+    next: "exit_count_files"
+  
+  - id: "exit_count_files"
+    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.
+- **`mcp_tool`**: Calls an MCP tool on an internal or external MCP server.
+- **`transform`**: Applies [JSONata](https://jsonata.org/) expressions to transform data between nodes.
+- **`switch`**: Uses [JSON Logic](https://jsonlogic.com/) to conditionally route to different nodes.
+- **`exit`**: Exit point that returns the final result to the MCP tool caller.
+
+## 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
+
+### 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": "node",
+      "args": [
+        "/path/to/node_modules/mcpgraph/dist/main.js",
+        "-c",
+        "/path/to/your/config.yaml"
+      ]
+    }
+  }
+}
+```
+
+Or if installed globally, you can use the global installation path:
+
+```json
+{
+  "mcpServers": {
+    "mcpgraph": {
+      "command": "node",
+      "args": [
+        "/usr/local/lib/node_modules/mcpgraph/dist/main.js",
+        "-c",
+        "/path/to/your/config.yaml"
+      ]
+    }
+  }
+}
+```
+
+**Note:** The exact path depends on your Node.js installation. You can find the global installation path by running `npm root -g` and appending `/mcpgraph/dist/main.js`.
+
+#### Using tsx for Development
+
+For development with TypeScript source files:
+
+```json
+{
+  "mcpServers": {
+    "mcpgraph": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "tsx",
+        "/path/to/mcpGraph/src/main.ts",
+        "-c",
+        "/path/to/your/config.yaml"
+      ]
+    }
+  }
+}
+```
+
+**Note:** Replace `/path/to/your/config.yaml` with the actual path to your YAML configuration file. The `-c` flag specifies the configuration file to use.
+
+## Usage
+
+After installation, you can use mcpGraph as an MCP server by providing a YAML configuration file:
+
+```bash
+mcpgraph -c path/to/config.yaml
+```
+
+Or using the long form:
+
+```bash
+mcpgraph --config path/to/config.yaml
+```
+
+## 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

package/dist/config/loader.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Configuration loader for mcpGraph
+ */
+import type { McpGraphConfig } from "../types/config.js";
+export declare function loadConfig(filePath: string): McpGraphConfig;
+//# sourceMappingURL=loader.d.ts.map

package/dist/config/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAE3D"}

package/dist/config/loader.js

@@ -0,0 +1,8 @@
+/**
+ * Configuration loader for mcpGraph
+ */
+import { parseYamlConfig } from "./parser.js";
+export function loadConfig(filePath) {
+    return parseYamlConfig(filePath);
+}
+//# sourceMappingURL=loader.js.map

package/dist/config/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,MAAM,UAAU,UAAU,CAAC,QAAgB;IACzC,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC"}

package/dist/config/parser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * YAML parser for mcpGraph configuration
+ */
+import type { McpGraphConfig } from "../types/config.js";
+export declare function parseYamlConfig(filePath: string): McpGraphConfig;
+//# sourceMappingURL=parser.d.ts.map

package/dist/config/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/config/parser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAgBhE"}

package/dist/config/parser.js

@@ -0,0 +1,24 @@
+/**
+ * YAML parser for mcpGraph configuration
+ */
+import { load } from "js-yaml";
+import { readFileSync } from "node:fs";
+import { mcpGraphConfigSchema } from "./schema.js";
+import { logger } from "../logger.js";
+export function parseYamlConfig(filePath) {
+    try {
+        const fileContents = readFileSync(filePath, "utf-8");
+        const parsed = load(fileContents);
+        // Validate against schema
+        const validated = mcpGraphConfigSchema.parse(parsed);
+        return validated;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            logger.error(`Failed to parse YAML config: ${error.message}`);
+            throw error;
+        }
+        throw new Error("Unknown error parsing YAML config");
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/config/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/config/parser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACrD,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAY,CAAC;QAE7C,0BAA0B;QAC1B,MAAM,SAAS,GAAG,oBAAoB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAErD,OAAO,SAA2B,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,MAAM,CAAC,KAAK,CAAC,gCAAgC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAC9D,MAAM,KAAK,CAAC;QACd,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;AACH,CAAC"}

package/dist/config/schema.d.ts

@@ -0,0 +1,366 @@
+/**
+ * Zod schemas for validating mcpGraph configuration
+ */
+import { z } from "zod";
+export declare const mcpGraphConfigSchema: z.ZodObject<{
+    version: z.ZodString;
+    server: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        description: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        name: string;
+        version: string;
+    }, {
+        description: string;
+        name: string;
+        version: string;
+    }>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        inputSchema: z.ZodObject<{
+            type: z.ZodString;
+            properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                type: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                type: string;
+                description?: string | undefined;
+            }, {
+                type: string;
+                description?: string | undefined;
+            }>>>;
+            required: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            type: string;
+            description?: string | undefined;
+            properties?: Record<string, {
+                type: string;
+                description?: string | undefined;
+            }> | undefined;
+            required?: string[] | undefined;
+        }, {
+            type: string;
+            description?: string | undefined;
+            properties?: Record<string, {
+                type: string;
+                description?: string | undefined;
+            }> | undefined;
+            required?: string[] | undefined;
+        }>;
+        outputSchema: z.ZodObject<{
+            type: z.ZodString;
+            properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                type: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                type: string;
+                description?: string | undefined;
+            }, {
+                type: string;
+                description?: string | undefined;
+            }>>>;
+            required: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            type: string;
+            description?: string | undefined;
+            properties?: Record<string, {
+                type: string;
+                description?: string | undefined;
+            }> | undefined;
+            required?: string[] | undefined;
+        }, {
+            type: string;
+            description?: string | undefined;
+            properties?: Record<string, {
+                type: string;
+                description?: string | undefined;
+            }> | undefined;
+            required?: string[] | undefined;
+        }>;
+        entryNode: z.ZodString;
+        exitNode: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        name: string;
+        inputSchema: {
+            type: string;
+            description?: string | undefined;
+            properties?: Record<string, {
+                type: string;
+                description?: string | undefined;
+            }> | undefined;
+            required?: string[] | undefined;
+        };
+        outputSchema: {
+            type: string;
+            description?: string | undefined;
+            properties?: Record<string, {
+                type: string;
+                description?: string | undefined;
+            }> | undefined;
+            required?: string[] | undefined;
+        };
+        entryNode: string;
+        exitNode: string;
+    }, {
+        description: string;
+        name: string;
+        inputSchema: {
+            type: string;
+            description?: string | undefined;
+            properties?: Record<string, {
+                type: string;
+                description?: string | undefined;
+            }> | undefined;
+            required?: string[] | undefined;
+        };
+        outputSchema: {
+            type: string;
+            description?: string | undefined;
+            properties?: Record<string, {
+                type: string;
+                description?: string | undefined;
+            }> | undefined;
+            required?: string[] | undefined;
+        };
+        entryNode: string;
+        exitNode: string;
+    }>, "many">;
+    nodes: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        id: z.ZodString;
+    } & {
+        type: z.ZodLiteral<"entry">;
+        next: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "entry";
+        id: string;
+        next: string;
+    }, {
+        type: "entry";
+        id: string;
+        next: string;
+    }>, z.ZodObject<{
+        id: z.ZodString;
+        next: z.ZodOptional<z.ZodString>;
+    } & {
+        type: z.ZodLiteral<"exit">;
+    }, "strip", z.ZodTypeAny, {
+        type: "exit";
+        id: string;
+        next?: string | undefined;
+    }, {
+        type: "exit";
+        id: string;
+        next?: string | undefined;
+    }>, z.ZodObject<{
+        id: z.ZodString;
+    } & {
+        type: z.ZodLiteral<"mcp_tool">;
+        server: z.ZodString;
+        tool: z.ZodString;
+        args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        next: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "mcp_tool";
+        id: string;
+        next: string;
+        server: string;
+        tool: string;
+        args: Record<string, unknown>;
+    }, {
+        type: "mcp_tool";
+        id: string;
+        next: string;
+        server: string;
+        tool: string;
+        args: Record<string, unknown>;
+    }>, z.ZodObject<{
+        id: z.ZodString;
+    } & {
+        type: z.ZodLiteral<"transform">;
+        transform: z.ZodObject<{
+            expr: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            expr: string;
+        }, {
+            expr: string;
+        }>;
+        next: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "transform";
+        id: string;
+        next: string;
+        transform: {
+            expr: string;
+        };
+    }, {
+        type: "transform";
+        id: string;
+        next: string;
+        transform: {
+            expr: string;
+        };
+    }>, z.ZodObject<{
+        id: z.ZodString;
+        next: z.ZodOptional<z.ZodString>;
+    } & {
+        type: z.ZodLiteral<"switch">;
+        conditions: z.ZodArray<z.ZodObject<{
+            rule: z.ZodOptional<z.ZodUnknown>;
+            target: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            target: string;
+            rule?: unknown;
+        }, {
+            target: string;
+            rule?: unknown;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: "switch";
+        id: string;
+        conditions: {
+            target: string;
+            rule?: unknown;
+        }[];
+        next?: string | undefined;
+    }, {
+        type: "switch";
+        id: string;
+        conditions: {
+            target: string;
+            rule?: unknown;
+        }[];
+        next?: string | undefined;
+    }>]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    server: {
+        description: string;
+        name: string;
+        version: string;
+    };
+    tools: {
+        description: string;
+        name: string;
+        inputSchema: {
+            type: string;
+            description?: string | undefined;
+            properties?: Record<string, {
+                type: string;
+                description?: string | undefined;
+            }> | undefined;
+            required?: string[] | undefined;
+        };
+        outputSchema: {
+            type: string;
+            description?: string | undefined;
+            properties?: Record<string, {
+                type: string;
+                description?: string | undefined;
+            }> | undefined;
+            required?: string[] | undefined;
+        };
+        entryNode: string;
+        exitNode: string;
+    }[];
+    nodes: ({
+        type: "entry";
+        id: string;
+        next: string;
+    } | {
+        type: "exit";
+        id: string;
+        next?: string | undefined;
+    } | {
+        type: "mcp_tool";
+        id: string;
+        next: string;
+        server: string;
+        tool: string;
+        args: Record<string, unknown>;
+    } | {
+        type: "transform";
+        id: string;
+        next: string;
+        transform: {
+            expr: string;
+        };
+    } | {
+        type: "switch";
+        id: string;
+        conditions: {
+            target: string;
+            rule?: unknown;
+        }[];
+        next?: string | undefined;
+    })[];
+}, {
+    version: string;
+    server: {
+        description: string;
+        name: string;
+        version: string;
+    };
+    tools: {
+        description: string;
+        name: string;
+        inputSchema: {
+            type: string;
+            description?: string | undefined;
+            properties?: Record<string, {
+                type: string;
+                description?: string | undefined;
+            }> | undefined;
+            required?: string[] | undefined;
+        };
+        outputSchema: {
+            type: string;
+            description?: string | undefined;
+            properties?: Record<string, {
+                type: string;
+                description?: string | undefined;
+            }> | undefined;
+            required?: string[] | undefined;
+        };
+        entryNode: string;
+        exitNode: string;
+    }[];
+    nodes: ({
+        type: "entry";
+        id: string;
+        next: string;
+    } | {
+        type: "exit";
+        id: string;
+        next?: string | undefined;
+    } | {
+        type: "mcp_tool";
+        id: string;
+        next: string;
+        server: string;
+        tool: string;
+        args: Record<string, unknown>;
+    } | {
+        type: "transform";
+        id: string;
+        next: string;
+        transform: {
+            expr: string;
+        };
+    } | {
+        type: "switch";
+        id: string;
+        conditions: {
+            target: string;
+            rule?: unknown;
+        }[];
+        next?: string | undefined;
+    })[];
+}>;
+export type McpGraphConfigSchema = z.infer<typeof mcpGraphConfigSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/config/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA8ExB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAK/B,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}