MagicTunnel

Smart MCP Proxy - One intelligent tool that discovers the right tool for any request.

The Problem

MCP clients get overwhelmed with 50+ tools. Users can't find the right tool for their task.

The Solution

MagicTunnel provides one smart tool that:

1. Analyzes your natural language request
2. Finds the best tool automatically
3. Maps parameters and executes it
4. Returns the result

Quick Start

Full Stack Setup (Recommended)

# Clone and build
git clone https://github.com/your-org/magictunnel.git
cd magictunnel

# Quick setup with smart discovery (Ollama + development mode)
make build-release-semantic && make pregenerate-embeddings-ollama MAGICTUNNEL_ENV=development

# Run MagicTunnel with Web Dashboard & Supervisor
./magictunnel-supervisor

# Access Web Dashboard
open http://localhost:5173/dashboard

# Test smart discovery via API
curl -X POST http://localhost:3001/v1/mcp/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "smart_tool_discovery", 
    "arguments": {"request": "ping google.com"}
  }'

Lightweight Setup (MCP Server Only)

# Run standalone MCP server (no web dashboard)
./magictunnel

Setup with Smart Discovery (Recommended)

For the best experience with local semantic searc (Requires Ollama embedding model):

# Install Ollama (optional - for local semantic search)
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull nomic-embed-text

# Build with semantic search support
make build-release-semantic

# Pre-generate embeddings for faster startup
make pregenerate-embeddings-ollama

# Run with smart discovery
make run-release-ollama

📚 Complete Setup Guide - Detailed 5-minute tutorial with web dashboard and all options

Example Usage

Instead of knowing which specific tool to use:

// ❌ Before: Need to know exact tool names
{"name": "network_ping", "arguments": {"host": "google.com"}}
{"name": "filesystem_read", "arguments": {"path": "/etc/hosts"}}
{"name": "database_query", "arguments": {"sql": "SELECT * FROM users"}}

Just describe what you want:

// ✅ After: Natural language requests
{"name": "smart_tool_discovery", "arguments": {"request": "ping google.com"}}
{"name": "smart_tool_discovery", "arguments": {"request": "read the hosts file"}}  
{"name": "smart_tool_discovery", "arguments": {"request": "get all users from database"}}

Configuration

Create magictunnel-config.yaml:

server:
  host: "127.0.0.1"
  port: 8080

registry:
  paths: ["./capabilities"]

smart_discovery:
  enabled: true
  tool_selection_mode: "rule_based"  # or "llm_based"

Web Dashboard

MagicTunnel includes a comprehensive web dashboard for management and monitoring:

Access Dashboard

# Start with supervisor (includes web dashboard)
./target/release/magictunnel-supervisor

# Open in browser
open http://localhost:5173/dashboard

Dashboard Features

• 📊 Real-time Monitoring: System status, performance metrics, and uptime tracking
• 🔧 Tool Management: Browse, test, and manage all available MCP tools
• 📈 Tool Analytics: Track tool usage patterns, execution metrics, and discovery rankings
• 📋 Configuration Management: Edit configuration files with validation and backup
• 📝 Live Logs: Real-time log viewer with filtering, search, and export
• 🔍 MCP Testing: Interactive JSON-RPC command testing interface
• ⚙️ Service Control: Start, stop, and restart services via web interface

Add Your Tools

Manual Tool Creation

Create capabilities/my-tools.yaml:

tools:
  - name: "ping"
    description: "Test network connectivity to a host"
    input_schema:
      type: object
      properties:
        host:
          type: string
          description: "Hostname or IP address to ping"
    routing:
      type: "command"
      command: "ping"
      args: ["-c", "4", "{host}"]

Generate Tools from APIs

Automatically generate tools from your existing APIs:

# Generate from OpenAPI/Swagger
./target/release/openapi-generator \
  --spec https://api.example.com/openapi.json \
  --output capabilities/api-tools.yaml \
  --base-url https://api.example.com \
  --auth-type bearer --auth-token $API_TOKEN

# Generate from gRPC services  
./target/release/grpc-generator \
  --proto service.proto \
  --output capabilities/grpc-tools.yaml \
  --endpoint localhost:50051

# Generate from GraphQL schemas
./target/release/graphql-generator \
  --schema schema.graphql \
  --endpoint https://api.example.com/graphql \
  --output capabilities/graphql-tools.yaml

# Unified CLI for all formats
./target/release/magictunnel-cli openapi --spec openapi.json --base-url https://api.example.com --output tools.yaml

📖 Complete API Generation Guide - Detailed CLI documentation with all options and examples

Features

• ✅ Smart Discovery: AI-powered tool selection with natural language interface
• 🖥️ Web Dashboard: Real-time monitoring, tool management, and configuration
• 🔧 Supervisor Architecture: Process management with automatic restart and health monitoring
• ✅ MCP Compatible: Works with Claude, GPT-4, any MCP client
• 🌐 Protocol Gateway: HTTP, SSE, WebSocket protocol translation for network MCP services
• ✅ Easy Setup: Single binary, YAML configuration
• ✅ Extensible: Add tools without coding

Documentation

Core Documentation

• 🚀 Quick Start - 5-minute setup guide with all options
• 🖥️ Web Dashboard - Complete web interface guide
• 🔧 Supervisor System - Process management and monitoring
• 🧠 Smart Discovery - Intelligent tool discovery
• 🌐 Protocol Compatibility - Network MCP protocol translation

Advanced Documentation

• 📖 Full Guide - Complete documentation
• 🔧 Configuration - Configuration options
• 🛠️ Adding Tools - How to add your own tools
• 🏗️ Architecture - Technical architecture
• 🔌 API Reference - Complete API documentation
• 🧪 Testing - Testing and validation
• 🚀 Deployment - Production deployment
• 📊 Observability - Metrics and monitoring

Development Documentation

• 📋 Frontend Development - Frontend implementation roadmap
• 🔢 Version Management - Development workflow and versioning

📚 View All Documentation

License

MIT License - see LICENSE for details.

More Images