Skip to content

toolkit.md

Latest commit

 

History

History
301 lines (242 loc) · 12.3 KB

toolkit.md

File metadata and controls

301 lines (242 loc) · 12.3 KB

mcpGraphToolkit Overview

Overview

mcpGraphToolkit is an MCP server that provides tools for building, testing, and running mcpGraph tools. It is implemented as an alternate executable alongside the main mcpgraph executable, called mcpgraphtoolkit.

Architecture

Entry Point

  • File: src/toolkit-main.ts
  • Binary: mcpgraphtoolkit (in package.json bin)
  • CLI Arguments: Same as mcpGraph (-g/--graph, -m/--mcp)

Core Components

  1. Core Graph API Extensions (src/api.ts - extends McpGraphApi)

    • Methods for graph manipulation:
      • addTool(tool: ToolDefinition) - add tool to graph
      • updateTool(toolName: string, tool: ToolDefinition) - update existing tool
      • deleteTool(toolName: string) - remove tool from graph
      • save(filePath?: string) - serialize and write graph to file
    • These methods manipulate the in-memory config and can save to file

  2. YAML Serializer (src/config/serializer.ts)

    • Deserializes: parseYamlConfig() - reads file and parses YAML to McpGraphConfig
    • Serializes: serializeYamlConfig() - converts McpGraphConfig to YAML string
    • Uses js-yaml's load() and dump() functions
    • Handles proper YAML formatting (indentation, block scalars, etc.)
    • Keeps bidirectional YAML operations together

  3. ToolkitApi (src/toolkit/api.ts)

    • Thin wrapper that exposes McpGraphApi methods as MCP tools
    • Handles MCP tool request/response formatting
    • No core graph logic - just exposes existing functionality
    • Includes close() method to clean up MCP discovery resources

  4. MCP Server Discovery (src/toolkit/mcp-discovery.ts)

    • Loads and manages MCP servers from mcp.json
    • Provides methods to list servers and tools
    • Handles MCP client connections for tool introspection
    • Uses loadMcpServers() from config/mcp-loader.ts to load servers

  5. Expression Testers (src/toolkit/expression-testers.ts)

    • JSONata expression testing with context
    • JSON Logic expression testing with context
    • Error handling and validation
    • Returns ExpressionTestResult with result and optional error object

Tools

mcpGraphToolkit provides 12 tools organized into the following categories:

📖 For Agents: If you're an AI agent using mcpGraphToolkit to build graph tools, see mcpGraphToolkit SKILL.md for comprehensive guidance on using these tools effectively.

Graph Discovery Tools

getGraphServer

Returns full server metadata (name, version, title, instructions).

  • Input: None
  • Output: Server metadata object

listGraphTools

Returns list of tools in graph (name, description).

  • Input: None
  • Output: Array of tool summaries

getGraphTool

Returns complete tool definition with nodes.

  • Input: toolName (string)
  • Output: Complete tool definition with nodes

MCP Server Discovery Tools

listMcpServers

Returns list of available MCP servers.

  • Input: None
  • Output: Array of server summaries (name, title, instructions, version)
  • Note: Returns error if MCP file not provided (requires -m flag)

listMcpServerTools

Returns list of tools from MCP servers.

  • Input: serverName (optional string) - filter by server
  • Output: Array of tool summaries (name, description, server)
  • Note: Returns error if MCP file not provided (requires -m flag)

getMcpServerTool

Returns full MCP tool definition.

  • Input: serverName (string), toolName (string)
  • Output: Complete tool definition (name, description, inputSchema, outputSchema)
  • Note: Returns error if MCP file not provided (requires -m flag)

Graph Tool Management (CRUD)

addGraphTool

Adds a new tool to the graph.

  • Input: tool (object) - complete tool definition
  • Output: { success: true, message: "Tool 'name' added successfully" }
  • Automatically saves the graph file after addition

updateGraphTool

Updates an existing tool in the graph.

  • Input: toolName (string), tool (object) - updated tool definition
  • Output: { success: true, message: "Tool 'name' updated successfully" }
  • Automatically saves the graph file after update

deleteGraphTool

Removes a tool from the graph.

  • Input: toolName (string)
  • Output: { success: true, message: "Tool 'name' deleted successfully" }
  • Automatically saves the graph file after deletion

Note: All graph manipulation logic is in core McpGraphApi. Toolkit just exposes these methods as MCP tools. Since we're serializing a valid McpGraphConfig object (which was loaded and validated), the serialized YAML is valid by definition.

Tool Execution

runGraphTool

Executes a graph tool, either from the graph or inline.

  • Input:
    • toolName (string, optional) - name of existing tool
    • toolDefinition (object, optional) - tool definition to run inline
    • arguments (object) - tool input arguments
    • logging (boolean, optional) - include execution logging
  • Output:
    • result (any) - tool execution result
    • error (object, optional) - error details if failed
    • logging (array, optional) - execution logs if requested
    • executionHistory (array, optional) - execution history for debugging
  • Behavior:
    • If toolName provided: executes existing tool from graph
    • If toolDefinition provided: executes inline tool definition
    • Inline tool definitions run in graph context:
      • Access to graph's MCP servers (via shared clientManager)
      • Uses graph's execution limits
      • Tool doesn't need to be saved to graph first (for testing/development)
    • Logging collection:
      • When logging: true, collects all log entries during execution
      • Logs include: debug, info, warn, error messages from all execution phases
  • Note: Returns error if both toolName and toolDefinition provided, or if neither provided

Expression Testing

testJSONata

Tests a JSONata expression with context.

  • Input:
    • expression (string) - JSONata expression
    • context (object) - context object for evaluation
  • Output:
    • result (any) - evaluation result
    • error (object, optional) - error details if failed
  • Behavior: Validates syntax first using validateJsonataSyntax(), then evaluates

testJSONLogic

Tests a JSON Logic expression with context.

  • Input:
    • expression (object) - JSON Logic expression object
    • context (object) - context object for evaluation
  • Output:
    • result (any) - evaluation result (boolean for conditions)
    • error (object, optional) - error details if failed

testMcpTool

Tests an MCP tool call directly to understand its output structure and behavior.

  • Input:
    • server (string) - name of the MCP server
    • tool (string) - name of the tool to call
    • args (object) - tool arguments (objects with { "expr": "..." } are evaluated as JSONata recursively; if context is provided, expressions in args are evaluated)
    • context (object, optional) - context object for JSONata expression evaluation in args
  • Output:
    • output (any) - tool execution output (matches what would be available in a graph node's execution context)
    • evaluatedArgs (object, optional) - evaluated arguments (present if JSONata expressions were used)
    • executionTime (number) - execution time in milliseconds
    • error (object, optional) - error details if call failed
  • Behavior:
    • Calls the MCP tool directly without creating a graph
    • Evaluates JSONata expressions in args if context is provided (using recursive { "expr": "..." } syntax)
    • Returns the same output structure that would be available in a graph node's execution context
    • Useful for understanding tool behavior and output structure before building graph tools

File Structure

src/
  api.ts                   # McpGraphApi extended with graph manipulation methods
  toolkit-main.ts          # Entry point for mcpgraphtoolkit
  config/
    serializer.ts          # YAML deserialization (load/parse) and serialization (save/dump)
  toolkit/
    api.ts                 # ToolkitApi class (thin wrapper exposing McpGraphApi as MCP tools)
    mcp-discovery.ts       # MCP server discovery and tool introspection
    expression-testers.ts  # JSONata and JSON Logic testing

Design Principles

Core vs Toolkit Separation

  • Core (McpGraphApi): All graph manipulation logic (load, add/update/delete tools, save)
  • Toolkit: Exposes core functionality as MCP tools, handles request/response formatting
  • Toolkit does NOT implement core graph functionality - it leverages it

Graph Object Model

Core API works with McpGraphConfig objects in memory:

  • Load graph using existing loadConfig() function (in constructor)
  • Manipulate the config object via methods (addTool, updateTool, deleteTool)
  • Serialize config object to YAML using serializeYamlConfig() function
  • Write YAML string to file via save() method
  • Executor is recreated after each config manipulation to ensure consistency

Inline Tool Execution

executeToolDefinition() method allows running tools that aren't in the graph yet:

  • Creates temporary config with inline tool added (doesn't modify main config)
  • Uses same clientManager instance (shares MCP server connections)
  • Uses graph's execution limits from main config
  • Tool runs in full graph context without needing to be saved first
  • Enables testing/development workflow: test tool → add to graph if it works
  • Validates temporary config before execution

Error Handling

  • Toolkit server catches errors from callTool() and converts to McpError for proper MCP error responses
  • All tools return structured error responses
  • File I/O errors are caught and returned as tool errors
  • Validation errors are returned with detailed messages
  • MCP connection errors are handled gracefully

Dependencies

Core Modules (Extended)

  • McpGraphApi - extended with graph manipulation methods (addTool, updateTool, deleteTool, save)
  • McpClientManager - for MCP server connections
  • loadConfig - for config loading (returns McpGraphConfig)
  • Expression evaluators from expressions/ directory

Extended Core Module

  • serializer.ts - provides serializeYamlConfig() function
    • Uses js-yaml's dump() for serialization (complements existing load() for deserialization)

Toolkit Modules (Toolkit-Specific)

  • MCP discovery functionality
  • Expression testers (utility functions)

Usage

Installation

mcpGraphToolkit is installed as part of the mcpGraph package. If you've installed mcpGraph from npm, you already have mcpGraphToolkit available.

Configuration

To use mcpGraphToolkit in your agent, add it to your MCP client's configuration file:

{
  "mcpServers": {
    "mcpgraphtoolkit": {
      "command": "mcpgraphtoolkit",
      "args": ["-g", "/path/to/your/graph.yaml", "-m", "/path/to/mcp.json"]
    }
  }
}

When using mcpGraphToolkit, you pass:

  • A path to your mcpGraph file (via -g flag)
  • A path to an mcp.json file containing mcpServers (via -m flag)

The mcp.json file can be any name and can be the same file your agent uses if you want access to the full set of tools your agent has.

Requirements

  • Toolkit requires write access to graph file for CRUD operations
  • MCP servers must be accessible for discovery tools (requires -m flag)
  • Expression testers use the same evaluators as graph execution
  • All file operations are atomic where possible

Testing

The toolkit includes comprehensive test coverage:

Unit/Integration Tests

  • File: tests/toolkit-api.test.ts
  • Tests graph manipulation methods (addTool, updateTool, deleteTool, save)
  • Tests MCP server discovery functionality
  • Tests expression testers (JSONata, JSON Logic)
  • Tests file I/O operations
  • Tests inline tool execution

MCP Client Integration Tests

  • File: tests/toolkit-mcp-server.test.ts
  • Tests all 12 toolkit tools via MCP protocol
  • Uses MCP SDK Client to connect to toolkit server via stdio
  • Tests error handling and edge cases
  • Tests logging collection functionality
  • Uses test fixtures (graph files, MCP configs)
  • Verifies end-to-end functionality through MCP protocol

Future Enhancements

  • Graph file creation from template if missing
  • Validate-only mode for expression testers
  • Detailed execution history in runGraphTool
  • Runtime debugging capabilities (step through graph)
  • Support for multiple graph files management