Vivgrid Tool Debugger

A powerful debugging tool for Vivgrid tools, allowing you to call tools, view real-time logs, and manage tool execution.

🚀 Quick Start

The easiest way to use Vivgrid Tool Debugger is to run it directly with npx:

npx viv-tool-debugger

This will automatically download and start the debugger, no installation required!

Features

• Connect to MCP (Model Context Protocol) endpoints
• View available tools from the connected endpoint
• Call tools with custom parameters
• View real-time logs for each tool
• Clear logs for individual tools
• Automatic cleanup of idle log connections
• yc CLI installation check
• Responsive design for better usability

Prerequisites

Before using this application, ensure you have the following:

• Node.js 20.9.0+ installed (required for Next.js 16)
• yc CLI installed (required for logs functionality)
  • Install via: curl "https://bina.egoist.dev/vivgrid/yc" | sh
  • For more information: yc CLI Documentation

Getting Started

Option 1: Run with npx (Recommended)

npx viv-tool-debugger

This will:

1. Automatically download the latest version
2. Build the project if needed
3. Start the server
4. Open your browser to the debugger interface

Option 2: Clone and Run Locally

1. Clone the repository
2. Install dependencies:

npm install
# or
yarn install
# or
pnpm install
# or
bun install

Running the Development Server

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

Build for Production

npm run build
# or
yarn build
# or
pnpm build
# or
bun build

Usage

1. Connect to MCP Endpoint

1. Navigate to http://localhost:3000
2. Enter your MCP endpoint URL and secret
3. Click "Connect" to establish the connection

2. View Available Tools

• After successful connection, you'll see a list of available tools
• Each tool displays its name, description, and required parameters

3. Call a Tool

1. Click on a tool from the list to select it
2. Fill in the required parameters in the form
3. Click "Call Tool" to execute the tool
4. The tool's execution result will be displayed below the form
5. If the tool call takes longer than 5 seconds, a "Cancel" button will appear
6. The tool call will automatically timeout after 30 seconds

4. View Tool Logs

1. Ensure you have the yc CLI installed
2. Select a tool from the list
3. Click "Start Tail Logs" to begin streaming logs for that tool
4. Logs will appear in the right-hand panel, with the latest logs at the top
5. Each log entry is tagged with the tool name
6. Click "Clear Logs" to remove all logs for the selected tool
7. Log streaming will automatically stop after 5 minutes of inactivity

5. Manage Logs

• Logs are separated by tool, so you only see relevant logs when a tool is selected
• Click "Clear Logs" to remove all logs for the current tool
• Log connections are automatically managed to prevent resource leaks

Project Structure

├── src/
│   ├── app/
│   │   ├── api/
│   │   │   └── tools/
│   │   │       ├── route.ts          # Tool list endpoint
│   │   │       ├── call/route.ts     # Tool execution endpoint
│   │   │       └── logs/route.ts     # Log streaming endpoint
│   │   ├── tools/
│   │   │   └── page.tsx             # Main tools page
│   │   ├── layout.tsx                # Root layout
│   │   └── page.tsx                  # Login/connection page
│   └── components/                   # Reusable components
├── package.json
├── next.config.js
└── README.md

Technical Stack

• Next.js 16.1.1
• React 18
• TypeScript
• Model Context Protocol (MCP) SDK
• Server-Sent Events (SSE) for real-time logs
• Tailwind CSS for styling

Troubleshooting

yc CLI Not Installed

If you see the error "yc command not found", follow these steps:

1. Install yc CLI using: curl "https://bina.egoist.dev/vivgrid/yc" | sh
2. Verify installation with: yc --help
3. Refresh the page and try again

Connection Issues

• Ensure your MCP endpoint URL and secret are correct
• Check if the endpoint is accessible from your network
• Verify that the endpoint is running and accepting connections

Logs Not Showing

• Check that yc CLI is installed and accessible
• Verify that the secret provided has permission to access logs
• Ensure the tool name exists on the connected endpoint

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.