# 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](../skills/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:

```json
{
  "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