mcpgraph-ux 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,106 @@
+# mcpGraph UX
+
+A Next.js application that provides a visual interface for the [mcpGraph](https://github.com/TeamSparkAI/mcpGraph) npm module. This application allows you to:
+
+- **Visualize graphs**: View your mcpGraph configuration as an interactive graph using React Flow
+- **List tools**: See all available MCP tools defined in your graph configuration
+- **Test tools**: Execute tools with custom parameters and view results from the exit node
+
+## Features
+
+- 🎨 **Graph Visualization**: Interactive graph visualization using React Flow, showing all nodes and their connections
+- 🔧 **Tool Testing**: Test each MCP tool with a user-friendly form interface
+- 📊 **Real-time Results**: View execution results directly in the UI
+- 🎯 **Tool Filtering**: Filter graph visualization by selected tool
+
+## Prerequisites
+
+- Node.js >= 20.0.0
+- The mcpGraph module (should be in `../mcpGraph` relative to this project)
+
+## Installation
+
+1. Install dependencies:
+
+```bash
+npm install
+```
+
+2. Ensure the mcpGraph module is built and available at `../mcpGraph`
+
+## Usage
+
+Start the server with a port and path to your mcpGraph YAML configuration file:
+
+```bash
+npm run server <port> <config-path>
+```
+
+### Examples
+
+```bash
+# Run on port 3000 with example config
+npm run server 3000 ../mcpGraph/examples/count_files.yaml
+
+# Run on port 8080 with custom config
+npm run server 8080 /path/to/your/graph.yaml
+```
+
+The server will:
+1. Load and validate the mcpGraph configuration
+2. Start the Next.js server on the specified port
+3. Make the configuration available through API routes
+
+Once running, open your browser to `http://localhost:<port>` to access the UI.
+
+## Development
+
+For development with hot-reloading:
+
+```bash
+npm run dev
+```
+
+Note: In development mode, you'll need to set the `MCPGRAPH_CONFIG_PATH` environment variable:
+
+```bash
+MCPGRAPH_CONFIG_PATH=/path/to/config.yaml npm run dev
+```
+
+## Project Structure
+
+```
+.
+├── app/                    # Next.js app directory
+│   ├── api/               # API routes
+│   │   ├── tools/         # Tool listing and execution endpoints
+│   │   └── graph/         # Graph data endpoint
+│   ├── layout.tsx         # Root layout
+│   ├── page.tsx           # Main page
+│   └── globals.css        # Global styles
+├── components/            # React components
+│   ├── GraphVisualization.tsx  # React Flow graph component
+│   ├── ToolList.tsx       # Tool sidebar component
+│   └── ToolTester.tsx    # Tool testing form component
+├── server.ts             # Custom server entry point
+└── package.json          # Dependencies and scripts
+```
+
+## API Endpoints
+
+- `GET /api/tools` - List all available tools
+- `GET /api/tools/[toolName]` - Get information about a specific tool
+- `POST /api/tools/[toolName]` - Execute a tool with provided arguments
+- `GET /api/graph` - Get graph structure (nodes and edges) for visualization
+
+## Design
+
+This application follows the design recommendations from the mcpGraph project:
+
+- **React Flow** for graph visualization (as recommended in the design docs)
+- **Next.js** for the web framework
+- **TypeScript** for type safety
+
+## License
+
+MIT

package/app/api/graph/route.ts

@@ -0,0 +1,114 @@
+import { NextResponse } from 'next/server';
+import { McpGraphApi } from 'mcpgraph';
+
+// Infer NodeDefinition type from the API
+type NodeDefinition = ReturnType<McpGraphApi['getConfig']>['nodes'][number];
+
+let apiInstance: McpGraphApi | null = null;
+
+function getApi(): McpGraphApi {
+  const configPath = process.env.MCPGRAPH_CONFIG_PATH;
+  if (!configPath) {
+    throw new Error('MCPGRAPH_CONFIG_PATH environment variable is not set');
+  }
+
+  if (!apiInstance) {
+    apiInstance = new McpGraphApi(configPath);
+  }
+
+  return apiInstance;
+}
+
+export async function GET() {
+  try {
+    const api = getApi();
+    const config = api.getConfig();
+    
+    // Transform nodes into React Flow format
+    const nodes = config.nodes.map((node: NodeDefinition) => {
+      const baseNode = {
+        id: node.id,
+        type: node.type,
+        data: {
+          label: node.id,
+          nodeType: node.type,
+          ...node,
+        },
+        position: { x: 0, y: 0 }, // Will be calculated by layout algorithm
+      };
+
+      // Add specific data based on node type
+      if (node.type === 'entry' || node.type === 'exit') {
+        return {
+          ...baseNode,
+          data: {
+            ...baseNode.data,
+            tool: (node as any).tool,
+          },
+        };
+      } else if (node.type === 'mcp') {
+        return {
+          ...baseNode,
+          data: {
+            ...baseNode.data,
+            server: (node as any).server,
+            tool: (node as any).tool,
+            args: (node as any).args,
+          },
+        };
+      } else if (node.type === 'transform') {
+        return {
+          ...baseNode,
+          data: {
+            ...baseNode.data,
+            transform: (node as any).transform,
+          },
+        };
+      } else if (node.type === 'switch') {
+        return {
+          ...baseNode,
+          data: {
+            ...baseNode.data,
+            conditions: (node as any).conditions,
+          },
+        };
+      }
+
+      return baseNode;
+    });
+
+    // Create edges from node.next and switch conditions
+    const edges: Array<{ id: string; source: string; target: string; label?: string }> = [];
+    
+    config.nodes.forEach((node: NodeDefinition) => {
+      if ('next' in node && node.next) {
+        edges.push({
+          id: `${node.id}-${node.next}`,
+          source: node.id,
+          target: node.next,
+        });
+      }
+      
+      if (node.type === 'switch' && 'conditions' in node) {
+        const switchNode = node as any;
+        switchNode.conditions.forEach((condition: any, index: number) => {
+          edges.push({
+            id: `${node.id}-${condition.target}-${index}`,
+            source: node.id,
+            target: condition.target,
+            label: condition.rule ? JSON.stringify(condition.rule) : 'default',
+          });
+        });
+      }
+    });
+
+    return NextResponse.json({ nodes, edges, tools: config.tools });
+  } catch (error) {
+    console.error('Error getting graph:', error);
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : 'Unknown error' },
+      { status: 500 }
+    );
+  }
+}
+

package/app/api/tools/[toolName]/route.ts

@@ -0,0 +1,64 @@
+import { NextResponse } from 'next/server';
+import { McpGraphApi } from 'mcpgraph';
+
+let apiInstance: McpGraphApi | null = null;
+
+function getApi(): McpGraphApi {
+  const configPath = process.env.MCPGRAPH_CONFIG_PATH;
+  if (!configPath) {
+    throw new Error('MCPGRAPH_CONFIG_PATH environment variable is not set');
+  }
+
+  if (!apiInstance) {
+    apiInstance = new McpGraphApi(configPath);
+  }
+
+  return apiInstance;
+}
+
+export async function GET(
+  request: Request,
+  { params }: { params: { toolName: string } }
+) {
+  try {
+    const api = getApi();
+    const tool = api.getTool(params.toolName);
+    
+    if (!tool) {
+      return NextResponse.json(
+        { error: `Tool '${params.toolName}' not found` },
+        { status: 404 }
+      );
+    }
+
+    return NextResponse.json({ tool });
+  } catch (error) {
+    console.error('Error getting tool:', error);
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : 'Unknown error' },
+      { status: 500 }
+    );
+  }
+}
+
+export async function POST(
+  request: Request,
+  { params }: { params: { toolName: string } }
+) {
+  try {
+    const api = getApi();
+    const body = await request.json();
+    const args = body.args || {};
+
+    const result = await api.executeTool(params.toolName, args);
+    
+    return NextResponse.json({ result });
+  } catch (error) {
+    console.error('Error executing tool:', error);
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : 'Unknown error' },
+      { status: 500 }
+    );
+  }
+}
+

package/app/api/tools/route.ts

@@ -0,0 +1,32 @@
+import { NextResponse } from 'next/server';
+import { McpGraphApi } from 'mcpgraph';
+
+let apiInstance: McpGraphApi | null = null;
+
+function getApi(): McpGraphApi {
+  const configPath = process.env.MCPGRAPH_CONFIG_PATH;
+  if (!configPath) {
+    throw new Error('MCPGRAPH_CONFIG_PATH environment variable is not set');
+  }
+
+  if (!apiInstance) {
+    apiInstance = new McpGraphApi(configPath);
+  }
+
+  return apiInstance;
+}
+
+export async function GET() {
+  try {
+    const api = getApi();
+    const tools = api.listTools();
+    return NextResponse.json({ tools });
+  } catch (error) {
+    console.error('Error listing tools:', error);
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : 'Unknown error' },
+      { status: 500 }
+    );
+  }
+}
+

package/app/globals.css

@@ -0,0 +1,26 @@
+* {
+  box-sizing: border-box;
+  padding: 0;
+  margin: 0;
+}
+
+html,
+body {
+  max-width: 100vw;
+  overflow-x: hidden;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+    sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+  background-color: #f5f5f5;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+

package/app/layout.tsx

@@ -0,0 +1,20 @@
+import type { Metadata } from 'next'
+import './globals.css'
+
+export const metadata: Metadata = {
+  title: 'mcpGraph UX',
+  description: 'Visual interface for mcpGraph',
+}
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}
+

package/app/page.module.css

@@ -0,0 +1,94 @@
+.container {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.header {
+  background-color: #fff;
+  border-bottom: 1px solid #e0e0e0;
+  padding: 1.5rem 2rem;
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+}
+
+.header h1 {
+  font-size: 1.5rem;
+  font-weight: 600;
+  margin-bottom: 0.25rem;
+  color: #333;
+}
+
+.header p {
+  color: #666;
+  font-size: 0.9rem;
+}
+
+.main {
+  flex: 1;
+  display: flex;
+  overflow: hidden;
+}
+
+.sidebar {
+  width: 300px;
+  background-color: #fff;
+  border-right: 1px solid #e0e0e0;
+  overflow-y: auto;
+}
+
+.content {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.graphSection {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  border-bottom: 1px solid #e0e0e0;
+  background-color: #fafafa;
+}
+
+.graphSection h2 {
+  padding: 1rem 1.5rem;
+  font-size: 1.1rem;
+  font-weight: 600;
+  color: #333;
+  border-bottom: 1px solid #e0e0e0;
+  background-color: #fff;
+}
+
+.testerSection {
+  background-color: #fff;
+  padding: 1.5rem;
+  overflow-y: auto;
+  max-height: 400px;
+}
+
+.testerSection h2 {
+  font-size: 1.1rem;
+  font-weight: 600;
+  margin-bottom: 1rem;
+  color: #333;
+}
+
+.loading,
+.error {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  min-height: 100vh;
+  padding: 2rem;
+}
+
+.error {
+  color: #d32f2f;
+}
+
+.error h1 {
+  margin-bottom: 1rem;
+}
+

package/app/page.tsx

@@ -0,0 +1,110 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import GraphVisualization from '@/components/GraphVisualization';
+import ToolList from '@/components/ToolList';
+import ToolTester from '@/components/ToolTester';
+import styles from './page.module.css';
+
+interface Tool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+}
+
+export default function Home() {
+  const [tools, setTools] = useState<Tool[]>([]);
+  const [selectedTool, setSelectedTool] = useState<string | null>(null);
+  const [graphData, setGraphData] = useState<{ nodes: any[]; edges: any[] } | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Load tools and graph data
+    Promise.all([
+      fetch('/api/tools').then(res => res.json()),
+      fetch('/api/graph').then(res => res.json()),
+    ])
+      .then(([toolsRes, graphRes]) => {
+        if (toolsRes.error) {
+          setError(toolsRes.error);
+          return;
+        }
+        if (graphRes.error) {
+          setError(graphRes.error);
+          return;
+        }
+        setTools(toolsRes.tools);
+        setGraphData({ nodes: graphRes.nodes, edges: graphRes.edges });
+        if (toolsRes.tools.length > 0) {
+          setSelectedTool(toolsRes.tools[0].name);
+        }
+      })
+      .catch(err => {
+        setError(err.message);
+      })
+      .finally(() => {
+        setLoading(false);
+      });
+  }, []);
+
+  if (loading) {
+    return (
+      <div className={styles.container}>
+        <div className={styles.loading}>Loading...</div>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className={styles.container}>
+        <div className={styles.error}>
+          <h1>Error</h1>
+          <p>{error}</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={styles.container}>
+      <header className={styles.header}>
+        <h1>mcpGraph UX</h1>
+        <p>Visual interface for mcpGraph execution</p>
+      </header>
+
+      <div className={styles.main}>
+        <div className={styles.sidebar}>
+          <ToolList
+            tools={tools}
+            selectedTool={selectedTool}
+            onSelectTool={setSelectedTool}
+          />
+        </div>
+
+        <div className={styles.content}>
+          <div className={styles.graphSection}>
+            <h2>Graph Visualization</h2>
+            {graphData && (
+              <GraphVisualization
+                nodes={graphData.nodes}
+                edges={graphData.edges}
+                selectedTool={selectedTool}
+              />
+            )}
+          </div>
+
+          {selectedTool && (
+            <div className={styles.testerSection}>
+              <h2>Test Tool: {selectedTool}</h2>
+              <ToolTester toolName={selectedTool} />
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+

package/components/GraphVisualization.module.css

@@ -0,0 +1,6 @@
+.container {
+  width: 100%;
+  height: 100%;
+  flex: 1;
+}
+