mcpgraph 0.1.23 → 0.1.25

package/dist/toolkit/expression-testers.js

@@ -0,0 +1,48 @@
+/**
+ * Expression testers for JSONata and JSON Logic
+ *
+ * Provides functionality to test expressions with context
+ */
+import { evaluateJsonata, validateJsonataSyntax } from '../expressions/jsonata.js';
+import { evaluateJsonLogic } from '../expressions/json-logic.js';
+/**
+ * Test a JSONata expression with context
+ */
+export async function testJSONata(expression, context) {
+    try {
+        // Validate syntax first
+        validateJsonataSyntax(expression);
+        // Evaluate with context (no history needed for testing)
+        const result = await evaluateJsonata(expression, context, [], 0);
+        return { result };
+    }
+    catch (error) {
+        return {
+            result: null,
+            error: {
+                message: error instanceof Error ? error.message : String(error),
+                details: error,
+            },
+        };
+    }
+}
+/**
+ * Test a JSON Logic expression with context
+ */
+export async function testJSONLogic(expression, context) {
+    try {
+        // Evaluate JSON Logic with context (no history needed for testing)
+        const result = await evaluateJsonLogic(expression, context, [], 0);
+        return { result };
+    }
+    catch (error) {
+        return {
+            result: null,
+            error: {
+                message: error instanceof Error ? error.message : String(error),
+                details: error,
+            },
+        };
+    }
+}
+//# sourceMappingURL=expression-testers.js.map

package/dist/toolkit/expression-testers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression-testers.js","sourceRoot":"","sources":["../../src/toolkit/expression-testers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAWjE;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,UAAkB,EAClB,OAAgC;IAEhC,IAAI,CAAC;QACH,wBAAwB;QACxB,qBAAqB,CAAC,UAAU,CAAC,CAAC;QAElC,wDAAwD;QACxD,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAEjE,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,KAAK,EAAE;gBACL,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC/D,OAAO,EAAE,KAAK;aACf;SACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAAmB,EACnB,OAAgC;IAEhC,IAAI,CAAC;QACH,mEAAmE;QACnE,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAEnE,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,KAAK,EAAE;gBACL,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC/D,OAAO,EAAE,KAAK;aACf;SACF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/toolkit/mcp-discovery.d.ts

@@ -0,0 +1,54 @@
+/**
+ * MCP Server Discovery for toolkit
+ *
+ * Provides functionality to discover and introspect MCP servers and their tools
+ */
+export interface McpServerInfo {
+    name: string;
+    title?: string;
+    instructions?: string;
+    version?: string;
+}
+export interface McpToolInfo {
+    name: string;
+    description: string;
+    server: string;
+}
+export interface McpToolDetails {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
+export declare class McpDiscovery {
+    private mcpFilePath;
+    private clientManager;
+    private serverConfigs;
+    private clients;
+    constructor(mcpFilePath: string | null);
+    /**
+     * Load MCP servers from mcp.json file
+     */
+    loadServers(): Promise<void>;
+    /**
+     * List all available MCP servers
+     */
+    listServers(): Promise<McpServerInfo[]>;
+    /**
+     * List tools from MCP servers
+     */
+    listTools(serverName?: string): Promise<McpToolInfo[]>;
+    /**
+     * Get full details of an MCP server tool
+     */
+    getTool(serverName: string, toolName: string): Promise<McpToolDetails>;
+    /**
+     * Get or create MCP client for a server
+     */
+    private getClient;
+    /**
+     * Clean up all clients
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=mcp-discovery.d.ts.map

package/dist/toolkit/mcp-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-discovery.d.ts","sourceRoot":"","sources":["../../src/toolkit/mcp-discovery.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,aAAa,CAAmB;IACxC,OAAO,CAAC,aAAa,CAAoC;IACzD,OAAO,CAAC,OAAO,CAAkC;gBAErC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKtC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAalC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IA4B7C;;OAEG;IACG,SAAS,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA+B5D;;OAEG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAwB5E;;OAEG;YACW,SAAS;IAYvB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAW7B"}

package/dist/toolkit/mcp-discovery.js

@@ -0,0 +1,140 @@
+/**
+ * MCP Server Discovery for toolkit
+ *
+ * Provides functionality to discover and introspect MCP servers and their tools
+ */
+import { loadMcpServers } from '../config/mcp-loader.js';
+import { McpClientManager } from '../mcp/client-manager.js';
+import { logger } from '../logger.js';
+export class McpDiscovery {
+    mcpFilePath;
+    clientManager;
+    serverConfigs = {};
+    clients = new Map();
+    constructor(mcpFilePath) {
+        this.mcpFilePath = mcpFilePath;
+        this.clientManager = new McpClientManager();
+    }
+    /**
+     * Load MCP servers from mcp.json file
+     */
+    async loadServers() {
+        if (!this.mcpFilePath) {
+            return;
+        }
+        try {
+            this.serverConfigs = loadMcpServers(this.mcpFilePath) || {};
+        }
+        catch (error) {
+            logger.error(`Failed to load MCP servers: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
+        }
+    }
+    /**
+     * List all available MCP servers
+     */
+    async listServers() {
+        await this.loadServers();
+        const servers = [];
+        for (const [serverName, serverConfig] of Object.entries(this.serverConfigs)) {
+            try {
+                const client = await this.getClient(serverName, serverConfig);
+                const serverVersion = client.getServerVersion();
+                servers.push({
+                    name: serverName,
+                    title: serverVersion?.title,
+                    instructions: client.getInstructions(),
+                    version: serverVersion?.version,
+                });
+            }
+            catch (error) {
+                logger.warn(`Failed to get info for server "${serverName}": ${error instanceof Error ? error.message : String(error)}`);
+                // Still include server even if we can't get full info
+                servers.push({
+                    name: serverName,
+                });
+            }
+        }
+        return servers;
+    }
+    /**
+     * List tools from MCP servers
+     */
+    async listTools(serverName) {
+        await this.loadServers();
+        const tools = [];
+        const serversToQuery = serverName
+            ? (this.serverConfigs[serverName] ? [serverName] : [])
+            : Object.keys(this.serverConfigs);
+        for (const name of serversToQuery) {
+            const serverConfig = this.serverConfigs[name];
+            try {
+                const client = await this.getClient(name, serverConfig);
+                const toolsResult = await client.listTools();
+                if (toolsResult.tools) {
+                    for (const tool of toolsResult.tools) {
+                        tools.push({
+                            name: tool.name,
+                            description: tool.description || '',
+                            server: name,
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                logger.warn(`Failed to list tools for server "${name}": ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        return tools;
+    }
+    /**
+     * Get full details of an MCP server tool
+     */
+    async getTool(serverName, toolName) {
+        await this.loadServers();
+        const serverConfig = this.serverConfigs[serverName];
+        if (!serverConfig) {
+            throw new Error(`Server "${serverName}" not found`);
+        }
+        const client = await this.getClient(serverName, serverConfig);
+        const toolsResult = await client.listTools();
+        const tool = toolsResult.tools?.find(t => t.name === toolName);
+        if (!tool) {
+            throw new Error(`Tool "${toolName}" not found in server "${serverName}"`);
+        }
+        return {
+            name: tool.name,
+            description: tool.description || '',
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+        };
+    }
+    /**
+     * Get or create MCP client for a server
+     */
+    async getClient(serverName, serverConfig) {
+        if (this.clients.has(serverName)) {
+            return this.clients.get(serverName);
+        }
+        // Use clientManager to get or create client
+        const client = await this.clientManager.getClient(serverName, serverConfig);
+        this.clients.set(serverName, client);
+        return client;
+    }
+    /**
+     * Clean up all clients
+     */
+    async close() {
+        for (const client of this.clients.values()) {
+            try {
+                await client.close();
+            }
+            catch (error) {
+                logger.warn(`Error closing client: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        this.clients.clear();
+        await this.clientManager.closeAll();
+    }
+}
+//# sourceMappingURL=mcp-discovery.js.map

package/dist/toolkit/mcp-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-discovery.js","sourceRoot":"","sources":["../../src/toolkit/mcp-discovery.ts"],"names":[],"mappings":"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"}

package/dist/toolkit-main.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * mcpGraphToolkit - MCP server for building, testing, and running mcpGraph tools
+ */
+export {};
+//# sourceMappingURL=toolkit-main.d.ts.map

package/dist/toolkit-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolkit-main.d.ts","sourceRoot":"","sources":["../src/toolkit-main.ts"],"names":[],"mappings":";AACA;;GAEG"}

package/dist/toolkit-main.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * mcpGraphToolkit - MCP server for building, testing, and running mcpGraph tools
+ */
+import { logger } from './logger.js';
+import { McpGraphApi } from './api.js';
+import { ToolkitApi } from './toolkit/api.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { parseArgs } from 'node:util';
+import { loadMcpServers } from './config/mcp-loader.js';
+const { values } = parseArgs({
+    options: {
+        graph: {
+            type: 'string',
+            short: 'g',
+            default: 'config.yaml',
+        },
+        mcp: {
+            type: 'string',
+            short: 'm',
+        },
+    },
+});
+let toolkitApi = null;
+async function main() {
+    try {
+        const configPath = values.graph || 'config.yaml';
+        // Load mcpServers from MCP JSON file if provided
+        let mcpServersFromFile;
+        if (values.mcp) {
+            try {
+                mcpServersFromFile = loadMcpServers(values.mcp);
+            }
+            catch (error) {
+                logger.error(`Failed to load MCP file: ${error instanceof Error ? error.message : String(error)}`);
+                throw error;
+            }
+        }
+        // Create API instance (loads and validates config, merging mcpServers)
+        const api = new McpGraphApi(configPath, mcpServersFromFile);
+        toolkitApi = new ToolkitApi(api, values.mcp || null);
+        // Initialize MCP server
+        const server = new Server({
+            name: 'mcpgraphtoolkit',
+            version: '1.0.0',
+            title: 'mcpGraph Toolkit',
+        }, {
+            capabilities: {
+                tools: {},
+            },
+            instructions: 'Tools for building, testing, and running mcpGraph tools',
+        });
+        // Register tools
+        server.setRequestHandler(ListToolsRequestSchema, async () => {
+            const tools = toolkitApi.listTools().map(tool => {
+                const mapped = {
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                    outputSchema: tool.outputSchema,
+                };
+                // Log if outputSchema is undefined or invalid
+                if (tool.outputSchema === undefined) {
+                    logger.warn(`Tool ${tool.name} has undefined outputSchema`);
+                }
+                return mapped;
+            });
+            logger.debug(`Returning ${tools.length} tools from listTools`);
+            return { tools };
+        });
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const toolName = request.params.name;
+            logger.info(`Toolkit tool called: ${toolName}`);
+            try {
+                const result = await toolkitApi.callTool(toolName, request.params.arguments || {});
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                // Convert errors to MCP error responses
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                throw new McpError(-32603, errorMessage, error);
+            }
+        });
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        logger.info('mcpGraphToolkit MCP server running on stdio');
+        // Handle cleanup on process termination
+        process.on('SIGINT', async () => {
+            logger.info('Shutting down...');
+            if (toolkitApi) {
+                await toolkitApi.close();
+            }
+            process.exit(0);
+        });
+        process.on('SIGTERM', async () => {
+            logger.info('Shutting down...');
+            if (toolkitApi) {
+                await toolkitApi.close();
+            }
+            process.exit(0);
+        });
+    }
+    catch (error) {
+        logger.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        if (error instanceof Error && error.stack) {
+            logger.error(error.stack);
+        }
+        process.exit(1);
+    }
+}
+main().catch(async (error) => {
+    logger.error(`Fatal error: ${error instanceof Error ? error.message : String(error)}`);
+    if (error instanceof Error && error.stack) {
+        logger.error(error.stack);
+    }
+    process.exit(1);
+});
+//# sourceMappingURL=toolkit-main.js.map

package/dist/toolkit-main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolkit-main.js","sourceRoot":"","sources":["../src/toolkit-main.ts"],"names":[],"mappings":"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"}

package/dist/types/execution.d.ts

@@ -4,6 +4,7 @@
 import type { NodeDefinition } from "./config.js";
 import type { ExecutionContext as ExecutionContextClass } from "../execution/context.js";
 import type { ExecutionContext as DataContext } from "../expressions/context.js";
+import type { LogEntry } from "../logger.js";
 export type ExecutionStatus = "not_started" | "running" | "paused" | "finished" | "error" | "stopped";
 export interface NodeExecutionRecord {
     executionIndex: number;
@@ -110,6 +111,11 @@ export interface ExecutionOptions {
      * When true, execution will pause at the entry node, allowing step-through debugging from the start.
      */
     startPaused?: boolean;
+    /**
+     * Enable log collection during execution.
+     * When true, all log entries during execution will be collected and included in ExecutionResult.
+     */
+    enableLogging?: boolean;
 }
 export interface ExecutionTelemetry {
     totalDuration: number;
@@ -121,5 +127,6 @@ export interface ExecutionResult {
     result: unknown;
     executionHistory: NodeExecutionRecord[];
     telemetry?: ExecutionTelemetry;
+    logs?: LogEntry[];
 }
 //# sourceMappingURL=execution.d.ts.map

package/dist/types/execution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../src/types/execution.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../src/types/execution.ts"],"names":[],"mappings":"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"}

package/docs/building.md

@@ -4,73 +4,97 @@ NOTE: This file is design notes only - do not implement anything here unless spe
 
 To build an agent graph you need:
 
+What an mpcGraph is, what it does, when and why you should use one
+
 Basic knowledge of the mcpGraph file structure
 - Assumes understanding of standard MCP data structures: MCP server metadata, tool description, mcpServers config
 
 Understanding of graph structure, flow, nodes, and node types/details
 - Including JSONata and JSON logic (both genrally, and as used in various nodes)
 
-All relevant MCP servers and their configurations
-- Including all tools provided with tool definitions
-
-Testing tools
-- In agent dev of our own examples, used primarily log output (which included error details)
-- We have a full runtime harness with debugging, etc, that we could expose if needed
-
 ## SKILL.md
 
 We can provide file / data structure defintion and context in a skill
 
-If we provide tooling (add, run, etc), we can describe that in the skill as well (what it is and how to use it)
-- It will also be in the tooling tool descriptions
+Probably the main skill will have all of the overview and format stuff
+- It can reference detailed documentation of JSONata and JSON Logic in separate files in the skill that we reference from the main skill
 
-## mcpGraphBuilder
+Later: If we provide tooling (mcpGraphBuilder), we can describe that in the skill as well (what it is and how to use it)
+- This information will also be in the mcpGraphBuidler tooling server instructions and tool descriptions
 
-Get all mcp servers and their configurations, and all tools they provide (search, progressive disclosure?)
-- To support agents building graphs so they understand what tools they have and can access server config (which they usually couldn't)
+## Tooling
 
-Run a graph
-- Would structured logging be enough to validate/debug (show each node, with context, output)
+Run, manage, and build mcpGraphs - Is this one program with multiple modes, or multiple programs?
 
-Do we want to use this to manage a set of graphs?
-- Get tools (find tool)
-- Run tool (debugging?  log output, step, etc?)
-- Add tool (fully implemented and tested tool, add by yaml file)
-- Edit/remove tool?
+### mcpGraph
 
-For add/edit, this implies we can serialize them somehow
-- Do we manage a directory of graph files with a shared mcp.json?
-  - Assumes we have write access to a directory
-- Do we just use a single graph file with mcpServers defined inline and manage all of our tools/graphs in that file?
-  - Assumes we have write access to our graph file
+Graph runner - exposes mcpGraph server as MCP server where each tool runs a graph
 
-If we're managing the tools as a set of graphs under this mcpGraph builder/manager, we're not really using the "server" part of the graph
-- Are the name/title/instructions relevant, can we just ignore them and assume the tool description (and contents) will suffice?
-- Would we want customizable metadata (esp instructions) for the builder/manager
-  - Maybe to distinguish them from each other, focus on set domain/tools available
+- -g / --graph specifies the graph configuration file to use
+- -m / --mcp if provided, parse mcpServers from referenced mcp.json file (jsonc support?), add to graph
+  - If mcpServers provided in graph, add them (overiding any passed-in MCP server with the same name)
 
-## Issues
+### mcpGraphToolkit
 
-Do we want to expose the mcpServers config to the graphs themselves?
+mcpGraphToolkit is a set of tools for building, testing, and running mcpGraph tools specified in a single mcpGraph server (file)
 
-What if we had a master mcpServers (mcp.json) that had all mcpServer configs used by any graph (basically everything the agent has access to)
-- Graph builder has access to all servers (without access to their config details)
-- Graphs have access to the servers they need (without access to their config details)
-  - Pass path to mcp.json as arg
-- For config details that are secret, this makes sense, but for others, maybe less so (like a directory path or other kind of scope)
+Will have it's own corresponding skill (separate from mcpGraph)
 
-What about MCP servers that require a secret or OAuth (where the agent can talk to the MCP server)
-- How can we talk to that MCP server securely without doing an agent tool call (which would defeat our purpose)
-- This is where being an agent gateway (especially a "smart" on that is managing tool disclosure/aggregation/etc) would be handy
+Same params as mcpGraph (-m/--mcp, -g/-graph)
+- Future: If graph file doesn't exist, create it from template?
 
-mcpGraphBuilder
-- m / --mcp is path to mcp.json with all tools
-- d / --dir is directory where graphs live?
+Setup:
+- Create (or reference existing) mcp.json
+- Create mcpgraph.yaml file (can use generic template, doesn't need any mcpServers or tools, just "server" block)
+- Install mcpGraphToolkit as MCP server in agent pointing to mcp and graph files
 
-mcpGraph
-- -g / --graph specifies the graph configuration file to use
-- -m / --mcp if provided, parse mcpServers from referenced mcp.json file (jsonc support?), add to graph
-  - If mcpServers provided in graph, add them (overiding any passed-in MCP server with the same name)
+Use case:
+- Agent can discover existing tools and call them
+- Agent can create new tools (with support for testing)
+- Agent can manage tools in the mcpGraph (add/update/delete)
+
+Tools:
+- getGraphServer - return full details of mcpGraph server
+- listMcpServers - return list of available mcpServer servers (name, title, instructions, version)
+- listMcpServerTools - return list of tools (name/description only), optionally filtered by MCP server name
+- getMcpServerTool - return full MCP server tool details (including input and output)
+- listGraphTools - return a list of exported tools from the mcpGraph (name, description)
+- getGraphTool - return full detail of an exported tool from the mcpGraph
+- addGraphTool, updateGraphTool, deleteGraphTool - crud for exported mcpGraph tools
+- runGraphTool - run an exported tool from the mcpGraph
+  - can specify existing tool name, or run a tool definition supplied in payload
+  - input includes tool input (arbitrary JSON)
+  - output inclides tool result payload (or error)
+  - can specify logging, in which case logging will also be returned with payload
+  - Future: optionally return detailed results (execution history, node-level)
+  - Future: runtime debugging - step through graph, etc?
+- testJSONata - test a JSONata expression
+  - provide context object, JSONata string, returns result object or error)
+  - Future: validate-only mode?
+- testJSONLogic - test a JSON Logic expression
+  - provide context object, JSON Logic object, return result or error)
+  - Future: validate-only mode?
+
+
+### mcpGraphManager
+
+Manage a collection of graphs / graph tools
 
-Maybe it's one MCP server that requires either --dir ("builder" mode) or --graph ("runner" mode)
+- m / --mcp is path to mcp.json with all tools
+- d / --dir is directory where graphs live (assumes we have read or read/write access - write tools only available if write access?)
+  - Would we want a mode where we pass a single -g / --graph and only expose tools relevant a single graph server, and also whether we have write access to it?
+
+Manage a set of graphs and their tools
+- list graph servers, list tools, list tools by graph server
+- find graph server/tool
+- list by graph server/tool name/description, get graph server / tool for details?
+- add/edit/delete graph server
+- add/edit/delete graph server tool?
+- run graph server tool (basic running, no debugging, just results as when running as MCP server)
+- tool names will be graph server.name + "__" + tool.name (so we can dereference on run tool)
+
+## Issues
 
+What about MCP servers that require a secret or OAuth (where the agent can talk to the MCP server)
+- How can we talk to that MCP server securely without doing an agent tool call (which would defeat our purpose)
+- This is where being an agent gateway (especially a "smart" on that is managing tool disclosure/aggregation/etc) would be handy

package/docs/design.md

@@ -173,7 +173,7 @@ server:
   name: "fileUtils"
   version: "1.0.0"
   title: "File utilities"
-  instructions: "This server provides file utility tools for counting files in directories."
+  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: