### Frontend Development Setup

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/web-dashboard.md

Instructions for setting up the frontend development environment for the MagicTunnel Web Dashboard. This includes installing dependencies, starting the development server with hot reloading, building for production, and performing type checking.

```bash
cd frontend
npm install
npm run dev
npm run build
npm run check
```

--------------------------------

### Install Python MCP Servers with uv

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Installs Python libraries for MCP servers using 'uv', a fast Python package installer, for filesystem, git, and sqlite interactions.

```python
# Option 2: Using uv (recommended - faster)
uv pip install mcp-filesystem mcp-git mcp-sqlite
```

--------------------------------

### Basic MagicTunnel Configuration Example

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Provides a sample YAML configuration file for MagicTunnel, detailing settings for the server, capability registry, external MCP integration, authentication, and logging.

```yaml
# Basic MagicTunnel Configuration
server:
  host: "0.0.0.0"
  port: 3000
  websocket: true
  timeout: 30

# Capability registry (where your API tools are defined)
registry:
  type: "file"
  paths:
    - "./capabilities"
  hot_reload: true

# External MCP server integration (optional)
external_mcp:
  enabled: false
  config_file: "external-mcp-servers.yaml"
  conflict_resolution: "local_first"
  discovery:
    enabled: false
    refresh_interval_minutes: 60

# Authentication (optional - disabled by default)
# auth:
#   type: "api_key"
#   api_keys:
#     - name: "admin"
#       key: "your-secure-api-key-here"

# Logging
logging:
  level: "info"
  format: "text"
```

--------------------------------

### Install and Run MagicTunnel (Ollama)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/web-dashboard.md

This snippet demonstrates a one-line setup for MagicTunnel using Ollama in development mode, including building the release, pre-generating embeddings, and starting the supervisor for web dashboard access.

```bash
make build-release-semantic && make pregenerate-embeddings-ollama MAGICTUNNEL_ENV=development
./target/release/magictunnel-supervisor
open http://localhost:5173/dashboard
```

--------------------------------

### Install Node.js MCP Servers

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Installs Node.js packages for MCP servers, enabling filesystem, git, and sqlite functionalities for external MCP server integration.

```javascript
# Install Node.js MCP servers
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-git
npm install -g @modelcontextprotocol/server-sqlite
```

--------------------------------

### Natural Language Interface Example (JSON)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Examples of using the 'smart_tool_discovery' tool with natural language requests, formatted as JSON objects.

```json
{
  "name": "smart_tool_discovery",
  "arguments": {
    "request": "read the config.yaml file"
  }
}

{
  "name": "smart_tool_discovery", 
  "arguments": {
    "request": "make HTTP POST request to https://api.example.com/data with JSON body"
  }
}
```

--------------------------------

### Run MagicTunnel Standalone Server

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Command to start the MagicTunnel application directly, without the web dashboard, suitable for development or testing.

```bash
# Start MagicTunnel directly
cargo run --release --bin magictunnel
```

--------------------------------

### Run MagicTunnel Supervisor (Full Stack)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Commands to start the MagicTunnel Supervisor, which manages the main server and provides a web dashboard. Includes expected output and access instructions.

```bash
# Start the MagicTunnel Supervisor (manages the main server)
cargo run --release --bin magictunnel-supervisor

# Or run the binary directly
./target/release/magictunnel-supervisor

# Expected Output:
# [INFO] MagicTunnel Supervisor starting on 0.0.0.0:8081
# [INFO] Starting main MagicTunnel server...
# [INFO] MagicTunnel starting on 0.0.0.0:3000
# [INFO] gRPC server starting on 0.0.0.0:4000
# [INFO] Web dashboard available at http://localhost:3000/dashboard
# [INFO] Loaded 5 capabilities from registry
# [INFO] MCP server ready for connections

# Access the Web Dashboard: Open http://localhost:5173/dashboard in your browser
```

--------------------------------

### Configure Smart Tool Discovery Behavior

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Example YAML configuration for the `config.yaml` file to control the behavior of the Smart Tool Discovery system, including hiding individual tools and overriding settings.

```yaml
# Smart Tool Discovery Configuration
visibility:
  hide_individual_tools: true      # Hide individual tools when smart discovery is enabled
  expose_smart_discovery_only: true # Only expose smart_tool_discovery
  allow_override: true             # Allow individual tools to override hidden setting
  default_hidden: false            # Default hidden state for new tools
```

--------------------------------

### Install Ollama and Pull Embedding Model

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Installs Ollama, a tool for running large language models locally, and pulls the 'nomic-embed-text' model for semantic search capabilities.

```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull embedding model
ollama pull nomic-embed-text
```

--------------------------------

### Setup FastAPI SSE MCP Server

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/SSE_MCP_TESTING.md

Steps to clone the repository, install dependencies using uv, and run the FastAPI SSE MCP server.

```bash
git clone https://github.com/ragieai/fastapi-sse-mcp.git
cd fastapi-sse-mcp

# Install dependencies
uv init fastapi_sse --bare
cd fastapi_sse
uv add fastapi mcp

# Create the server (see repository for full implementation)
# Run the server
uvicorn app.main:app --reload --port 8000
```

--------------------------------

### Install Python MCP Servers with Pip

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Installs necessary Python libraries for interacting with external MCP (Model Context Protocol) servers, including filesystem, git, and sqlite functionalities, using pip.

```python
# Option 1: Using pip
pip install mcp-filesystem mcp-git mcp-sqlite
```

--------------------------------

### List Available Capabilities via API

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Retrieves a list of all available capabilities (tools) from the MagicTunnel server by accessing the /mcp/tools endpoint.

```bash
curl http://localhost:3000/mcp/tools
```

--------------------------------

### Local Development Setup and Execution (Bash)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/deploy.md

Instructions for cloning the MagicTunnel repository, building the release binary, and running it with default or stdio configurations for local development.

```bash
git clone https://github.com/gouravd/magictunnel
cd magictunnel
cargo build --release

# Run with default configuration
./target/release/magictunnel --config config.yaml

# Run in stdio mode for Claude Desktop
./target/release/magictunnel --stdio --config config.yaml

# Connect client to ws://localhost:3000/mcp/ws
```

--------------------------------

### Build MagicTunnel with Semantic Search Support

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Builds the release version of the MagicTunnel project with support for semantic search capabilities enabled.

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

--------------------------------

### MagicTunnel Configuration File Example (TOML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

An example TOML configuration file for the MagicTunnel CLI, demonstrating settings for general options, OpenAPI, gRPC, and GraphQL generators.

```toml
# generator-config.toml
[general]
output_dir = "capabilities"
prefix = "mycompany_"

[openapi]
spec = "https://api.example.com/openapi.json"
base_url = "https://api.example.com"
auth_type = "bearer"
auth_token = "${API_TOKEN}"
methods = ["GET", "POST", "PUT", "DELETE"]
naming = "operation-id"

[grpc]
proto = "service.proto"
endpoint = "api.example.com:443"
tls = true
auth_type = "bearer"
auth_token = "${GRPC_TOKEN}"
services = ["UserService", "OrderService"]

[graphql]
schema = "schema.graphql"
endpoint = "https://api.example.com/graphql"
auth_type = "bearer"
auth_token = "${GRAPHQL_TOKEN}"
operations = ["query", "mutation"]
```

--------------------------------

### Start MagicTunnel

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/SSE_MCP_TESTING.md

Commands to build the MagicTunnel project in release mode and start the application using a specified configuration file.

```bash
# Build MagicTunnel
cargo build --release

# Start MagicTunnel
./target/release/magictunnel --config magictunnel-config.yaml
```

--------------------------------

### Ping Tool Configuration Example

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

Example configuration for a ping command, specifying the command, arguments, and error mapping.

```yaml
routing:
  type: "command"
  command: "ping"
  args: ["-c", "{count}", "{host}"]
  error_mapping:
    1: "Network is unreachable"
    2: "Host not found"
```

--------------------------------

### Basic MagicTunnel Configuration (YAML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/guide.md

Example of a basic MagicTunnel configuration file, including server settings, registry paths, and smart discovery options.

```YAML
# Server configuration
server:
  host: "127.0.0.1"
  port: 8080
  
# Tool registry
registry:
  paths: ["./capabilities"]
  hot_reload: true
  
# Smart discovery settings
smart_discovery:
  enabled: true
  tool_selection_mode: "rule_based"  # or "llm_based"
  default_confidence_threshold: 0.5
  
# Optional: LLM-based discovery
llm_tool_selection:
  enabled: false
  provider: "openai"  # openai, anthropic, ollama
  model: "gpt-4"
```

--------------------------------

### Start MagicTunnel Supervisor with Web Dashboard

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/SSE_MCP_TESTING.md

Commands to start the MagicTunnel supervisor, which includes a web dashboard, and how to access it in a browser.

```bash
# Start with web dashboard
./target/release/magictunnel-supervisor

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

# Navigate to:
# - Services tab to see SSE connection status
# - Tools tab to see tools from SSE servers
# - Logs tab to monitor SSE connection events
```

--------------------------------

### Run MagicTunnel Binary

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Execute the MagicTunnel binary directly from the release build. This section shows the command to run and the expected output indicating the server's status and loaded capabilities.

```bash
./target/release/magictunnel
```

```text
[INFO] MagicTunnel starting on 0.0.0.0:3000
[INFO] gRPC server starting on 0.0.0.0:4000
[INFO] Loaded 5 capabilities from registry
[INFO] MCP server ready for connections
```

--------------------------------

### Good Tool Description Example (YAML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

An example of a clear and informative description for a tool, adhering to best practices for smart discovery.

```yaml
# Good
description: "Test network connectivity by sending ICMP ping packets to a host"
```

--------------------------------

### Disable Smart Discovery Configuration

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Example YAML configuration for `config.yaml` to disable the Smart Discovery feature and revert to showing all individual tools.

```yaml
smart_discovery:
  enabled: false

visibility:
  hide_individual_tools: false
  expose_smart_discovery_only: false
```

--------------------------------

### Access Web Dashboard API for System Info

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Fetches system information from the MagicTunnel web dashboard's API by calling the /dashboard/api/system/info endpoint.

```bash
curl http://localhost:3000/dashboard/api/system/info
```

--------------------------------

### Install and Run MagicTunnel Tests

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/testing.md

Installs necessary testing tools like cargo-tarpaulin and cargo-nextest, then demonstrates how to run tests using nextest and generate a coverage report.

```bash
# Install required tools
cargo install cargo-tarpaulin  # Coverage
cargo install cargo-nextest    # Faster test runner

# Run tests with nextest
cargo nextest run

# Generate coverage report
cargo tarpaulin --out Html
```

--------------------------------

### Copy Environment-Specific Configuration Files

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Demonstrates how to copy environment-specific configuration files (e.g., '.env.development', '.env.production') to '.env.local' for managing different settings across development and production environments.

```bash
# Development environment
cp .env.development .env.local
# Edit .env.local with development API keys

# Production environment  
cp .env.production .env.local
# Edit .env.local with production API keys
```

--------------------------------

### Start MagicTunnel Main Server

Source: https://github.com/magicbeansai/magictunnel/blob/master/CLAUDE.md

Instructions for starting the main MagicTunnel MCP server, with options to specify a configuration file or use stdio mode for compatibility with applications like Claude Desktop.

```bash
# Start the main MCP server
cargo run --bin magictunnel -- --config config.yaml

# Start with stdio mode for Claude Desktop
cargo run --bin magictunnel -- --stdio --config config.yaml
```

--------------------------------

### Start MCP Proxy (Bash)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tls/TLS_DEPLOYMENT_GUIDE.md

Starts the MCP Proxy application using a specified configuration file. This command assumes the `magictunnel` executable is in the current directory.

```bash
./magictunnel --config config.yaml
```

--------------------------------

### Production Configuration Example

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/config.md

An example of a production-ready MagicTunnel configuration, optimizing for stability and logging by disabling hot reload and setting a warning log level.

```yaml
server:
  host: "0.0.0.0"
  port: 8080
  
logging:
  level: "warn"
  format: "json"
  
registry:
  hot_reload: false          # Disable for production
  validation:
    strict: true
```

--------------------------------

### Copy MagicTunnel Configuration Template

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Copies the default configuration template file ('config.yaml.template') to 'config.yaml', which can then be customized for MagicTunnel's settings.

```bash
# Copy the template configuration
cp config.yaml.template config.yaml
```

--------------------------------

### Run MagicTunnel Supervisor (Pre-built)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/web-dashboard.md

This snippet shows how to start the MagicTunnel supervisor using a pre-built binary, assuming the project has already been compiled. It then instructs how to access the web dashboard.

```bash
./target/release/magictunnel-supervisor
open http://localhost:5173/dashboard
```

--------------------------------

### Clone and Setup MCP Proxy

Source: https://github.com/magicbeansai/magictunnel/blob/master/CONTRIBUTING.md

Steps to clone the MCP Proxy repository, install development tools, and run tests locally using make commands.

```Bash
git clone https://github.com/MagicBeansAI/magictunnel.git
cd magictunnel

# Install development tools
make install-tools

# Run tests
make test

# Run development checks
make dev-check
```

--------------------------------

### Clone MagicTunnel Repository and Build

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Clones the MagicTunnel project from GitHub and builds the release version of the project using Cargo, Rust's build system and package manager.

```bash
# Clone the repository
git clone https://github.com/MagicBeansAI/magictunnel.git
cd magictunnel

# Build the project
cargo build --release
```

--------------------------------

### Tool Definition Example (YAML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/guide.md

YAML configuration for defining a 'ping' tool and a 'curl_get' tool, including their descriptions, input schemas, and routing information.

```YAML
# capabilities/networking.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"
        count:
          type: integer
          description: "Number of ping packets to send"
          default: 4
    routing:
      type: "command"
      command: "ping"
      args: ["-c", "{count}", "{host}"]

  - name: "curl_get"
    description: "Make HTTP GET request to a URL"
    input_schema:
      type: object
      properties:
        url:
          type: string
          description: "URL to request"
    routing:
      type: "http"
      method: "GET"
      url: "{url}"
```

--------------------------------

### Setup Python Sample SSE MCP Server

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/SSE_MCP_TESTING.md

Steps to clone the repository and run the Python sample SSE MCP server using uv.

```bash
git clone https://github.com/edom18/MCP-SSE-Server-Sample.git
cd MCP-SSE-Server-Sample

# Install dependencies (assuming uv is installed)
uv run mcp_server_sample --port 8080 --transport sse
```

--------------------------------

### Configure External MCP Servers

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Sets up integration with external MCP servers by defining their configurations in `external-mcp-servers.yaml`. Supports Node.js, Python with uvx, and Python with uv.

```yaml
mcpServers:
  # Node.js MCP server
  filesystem:
    command: "npx"
    args: ["@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
  
  # Python MCP server using uvx (recommended for isolation)
  git-uvx:
    command: "uvx"
    args: ["--from", "mcp-git", "mcp-server-git", "--repository", "/path/to/repo"]
  
  # Python MCP server using uv
  git-uv:
    command: "uv" 
    args: ["run", "mcp-server-git", "--repository", "/path/to/repo"]
```

--------------------------------

### Build and Run MagicTunnel Supervisor

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/supervisor.md

Commands to build the MagicTunnel supervisor in release mode and then run it to start all managed services. It also includes how to access the web dashboard.

```bash
# Build the supervisor
cargo build --release --bin magictunnel-supervisor

# Run the supervisor (starts all services)
./target/release/magictunnel-supervisor

# Access web dashboard
open http://localhost:5173/dashboard
```

--------------------------------

### Initialize MagicTunnel MCP Generator Configuration

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Initialize a configuration file for the `mcp-generator` CLI tool, which is used to generate capability files from various sources.

```bash
cargo run --bin mcp-generator init --output mcp-generator.toml
```

--------------------------------

### Build and Generate Embeddings with Ollama for Development

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Builds the release version of MagicTunnel with semantic search support and pre-generates embeddings using Ollama for a development environment.

```bash
# One-line setup for development with Ollama embeddings
make build-release-semantic && make pregenerate-embeddings-ollama MAGICTUNNEL_ENV=development

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

# Access dashboard at http://localhost:5173/dashboard
```

--------------------------------

### Manage Global Tool Visibility

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Commands to show all tools globally or hide all tools globally, effectively controlling the Smart Tool Discovery mode. Requires a configuration file.

```bash
cargo run --bin magictunnel-visibility -- -c config.yaml show-all

cargo run --bin magictunnel-visibility -- -c config.yaml hide-all
```

--------------------------------

### Command Routing Example (YAML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

Illustrates how to configure routing for a tool that executes a shell command, including arguments and an optional working directory.

```yaml
routing:
  type: "command"
  command: "ls"
  args: ["-la", "{path}"]
  working_dir: "/tmp"         # Optional
  timeout: 30                 # Optional timeout in seconds
```

--------------------------------

### Configure Cursor IDE for MagicTunnel

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Integrate MagicTunnel with Cursor IDE by adding it to the `mcp_servers.json` configuration file. This specifies using `cargo run` to execute the MagicTunnel binary with specific arguments.

```json
{
  "mcpServers": {
    "magictunnel": {
      "command": "cargo",
      "args": [
        "run",
        "--release",
        "--bin",
        "magictunnel",
        "--",
        "--stdio"
      ],
      "cwd": "/path/to/your/magictunnel"
    }
  }
}
```

--------------------------------

### Run MagicTunnel with Semantic Discovery

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

This command runs MagicTunnel with semantic discovery. It can be configured for OpenAI models using an API key or for local models.

```bash
# Only if using OpenAI
make run-release-semantic OPENAI_API_KEY=your-openai-key

# OR (for local models)
./target/release/magictunnel-supervisor

# OR (standalone)
cargo run --bin magictunnel --release -- --config magictunnel-config.yaml
```

--------------------------------

### Schema Naming Convention Example

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

Illustrates good and bad naming conventions for schema properties, emphasizing descriptive names.

```yaml
# Good - describes what it does
name: "ping_host"

# Bad - too generic
name: "network_tool"
```

--------------------------------

### Install and Renew Let's Encrypt Certificates with Certbot

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tls/TLS_DEPLOYMENT_GUIDE.md

This bash script demonstrates how to install Certbot, obtain a standalone certificate for a domain, and set up automatic renewal using cron. It covers the essential commands for managing Let's Encrypt certificates on a server.

```bash
# Install certbot
sudo apt-get install certbot

# Generate certificate
sudo certbot certonly --standalone -d magictunnel.example.com

# Set up automatic renewal
sudo crontab -e
# Add: 0 12 * * * /usr/bin/certbot renew --quiet --post-hook "systemctl reload magictunnel"

```

--------------------------------

### Manage Individual Tool Visibility

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Commands to show or hide specific tools using their names, or to show/hide all tools within a specific capability file. Requires a configuration file.

```bash
cargo run --bin magictunnel-visibility -- -c config.yaml show-tool git_status

cargo run --bin magictunnel-visibility -- -c config.yaml hide-tool git_status

cargo run --bin magictunnel-visibility -- -c config.yaml show-file capabilities/dev/git_tools.yaml

cargo run --bin magictunnel-visibility -- -c config.yaml hide-file capabilities/dev/git_tools.yaml
```

--------------------------------

### Execute Python MCP Servers with uvx

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Executes Python MCP server functionalities in isolated environments using 'uvx', specifically for filesystem, git, and sqlite interactions.

```python
# Option 3: Using uvx (for isolated tool execution)
uvx --from mcp-filesystem mcp-server-filesystem
uvx --from mcp-git mcp-server-git
uvx --from mcp-sqlite mcp-server-sqlite
```

--------------------------------

### Ollama Setup for Smart Discovery (Bash)

Source: https://github.com/magicbeansai/magictunnel/blob/master/README.md

This section details the setup for using MagicTunnel with local semantic search powered by Ollama. It includes installing Ollama, pulling an embedding model, building MagicTunnel with semantic search support, pre-generating embeddings, and running the service.

```bash
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull nomic-embed-text

make build-release-semantic

make pregenerate-embeddings-ollama

make run-release-ollama
```

--------------------------------

### Frontend Development Commands (Bash)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/frontend_todo.md

Commands for setting up and running the frontend development environment. Includes installing dependencies, starting the dev server, building for production, running tests, and type checking.

```bash
# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Start development server (runs on port 5173 with proxy to port 3001)
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run check
```

--------------------------------

### Copy MagicTunnel Environment Template

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Copies the default environment variables template file ('.env.example') to '.env', which is used for storing sensitive information like API keys for MagicTunnel.

```bash
# Copy the environment template
cp .env.example .env

# Edit .env and add your API keys
# OPENAI_API_KEY=sk-your-key-here
# ANTHROPIC_API_KEY=sk-ant-your-key-here
```

--------------------------------

### Enable External MCP Integration

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Enables the external MCP integration feature in the main configuration file by specifying the path to the external MCP server configuration file.

```yaml
external_mcp:
  enabled: true
  config_file: "external-mcp-servers.yaml"
```

--------------------------------

### HTTP Request Routing Example (YAML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

Demonstrates routing a tool request via an HTTP request, specifying the method, URL, optional headers, and request body.

```yaml
routing:
  type: "http"
  method: "GET"               # GET, POST, PUT, DELETE
  url: "https://api.example.com/users/{id}"
  headers:                    # Optional
    Authorization: "Bearer {token}"
    Content-Type: "application/json"
  body: |                     # Optional (for POST/PUT)
    {"name": "{name}", "email": "{email}"}
```

--------------------------------

### Run MagicTunnel with Specific Environment

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Executes the MagicTunnel application in either development or production mode by setting the MAGICTUNNEL_ENV environment variable before running the cargo command.

```bash
# Run in development mode
MAGICTUNNEL_ENV=development cargo run --release --bin magictunnel

# Run in production mode
MAGICTUNNEL_ENV=production cargo run --release --bin magictunnel
```

--------------------------------

### Environment Configuration for Semantic Search

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

This section details how to configure environment variables for semantic search based on the chosen model, including settings for OpenAI, Ollama, custom APIs, and common parameters.

```bash
# For OpenAI models
OPENAI_API_KEY=sk-your-openai-key-here
MAGICTUNNEL_SEMANTIC_MODEL=openai:text-embedding-3-small

# For Ollama (RECOMMENDED - real semantic embeddings)
OLLAMA_BASE_URL=http://localhost:11434
MAGICTUNNEL_SEMANTIC_MODEL=ollama:nomic-embed-text

# For fallback models (WARNING: hash-based, not real embeddings)
MAGICTUNNEL_SEMANTIC_MODEL=all-MiniLM-L6-v2     # Hash fallback - poor semantic matching
MAGICTUNNEL_SEMANTIC_MODEL=all-mpnet-base-v2    # Hash fallback - poor semantic matching

# For Ollama
OLLAMA_BASE_URL=http://localhost:11434
MAGICTUNNEL_SEMANTIC_MODEL=ollama:nomic-embed-text

# For custom embedding API
EMBEDDING_API_URL=http://your-server:8080
MAGICTUNNEL_SEMANTIC_MODEL=external:api

# Common settings
MAGICTUNNEL_DISABLE_SEMANTIC=false
```

--------------------------------

### Parameter Substitution Examples (YAML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

Illustrates various ways to substitute parameters within tool definitions, including simple substitution, default values, array indexing, and conditional substitution.

```yaml
# Simple substitution
args: ["--host", "{host}", "--port", "{port}"]

# Default values
args: ["--count", "{count|4}", "--timeout", "{timeout|30}"]

# Array indexing
args: ["{hosts[0]}", "{hosts[1]}"]

# Conditional substitution
args: 
  - "--verbose"
  - "{verbose?--debug:--quiet}"
```

--------------------------------

### Configure OpenAI for Semantic Search

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Enables semantic search using OpenAI embeddings by setting the model name and ensuring OpenAI API key is configured as an environment variable.

```yaml
smart_discovery:
  enabled: true
  semantic_search:
    enabled: true
    model_name: "openai:text-embedding-3-small"
```

```bash
export OPENAI_API_KEY="your-openai-api-key"
```

--------------------------------

### Integration Test Example: MCP Server (Rust)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/testing.md

An integration test for the MCP server. It initializes the server, starts it, and verifies that the server starts successfully and can list tools.

```rust
// tests/integration_test.rs
use magictunnel::*;

#[tokio::test]
async fn test_mcp_server_integration() {
    let config = Config::default();
    let server = McpServer::new(config).await.unwrap();
    
    // Test server startup
    let addr = server.start().await.unwrap();
    assert!(addr.port() > 0);
    
    // Test tool listing
    let tools = server.list_tools().await.unwrap();
    assert!(!tools.is_empty());
}
```

--------------------------------

### Custom MCP Client Integration (Python)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/guide.md

Python code example demonstrating how to interact with MagicTunnel's MCP endpoint using the requests library to call the 'smart_tool_discovery' tool.

```Python
import json
import requests

def call_magictunnel(request_text):
    response = requests.post(
        "http://localhost:8080/v1/mcp/call",
        json={
            "name": "smart_tool_discovery",
            "arguments": {"request": request_text}
        }
    )
    return response.json()

# Use it
result = call_magictunnel("check if google.com is reachable")
print(result)
```

--------------------------------

### Preferred Tools and Confidence Threshold

Source: https://github.com/magicbeansai/magictunnel/blob/master/examples/smart-discovery/README.md

Illustrates how to guide Smart Discovery by specifying preferred tools and a confidence threshold for the request. This helps in tuning the discovery process for specific needs.

```json
{
  "request": "make API call",
  "preferred_tools": ["http_client", "rest_api"],
  "confidence_threshold": 0.6
}
```

--------------------------------

### MagicTunnel Supervisor Configuration (Bash)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/supervisor.md

Examples of how to configure the MagicTunnel supervisor using environment variables and command-line arguments, including setting the port, host, configuration file path, and log level.

```bash
# Environment Variables
export SUPERVISOR_PORT=8081
export SUPERVISOR_HOST=127.0.0.1
export MAGICTUNNEL_CONFIG=./config.yaml
export SUPERVISOR_LOG_LEVEL=info

# Command Line Arguments
./target/release/magictunnel-supervisor \
  --port 8081 \
  --config ./config.yaml \
  --log-level debug
```

--------------------------------

### Verify External MCP Connections

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Use `curl` commands to check the status of external MCP servers, list all available tools (both local and external), and inspect the status of specific external servers.

```bash
# Check external MCP status
curl http://localhost:3000/mcp/external/status

# List all available tools (local + external)
curl http://localhost:3000/mcp/tools

# Check specific server status
curl http://localhost:3000/mcp/external/servers
```

--------------------------------

### Check MagicTunnel Health via API

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Checks the health status of the MagicTunnel server by sending a GET request to the /health endpoint.

```bash
curl http://localhost:3000/health
```

--------------------------------

### Build and Run MagicTunnel

Source: https://github.com/magicbeansai/magictunnel/blob/master/CLAUDE.md

Commands to build the MagicTunnel project in release mode and run it with custom configurations or in stdio mode for MCP clients. Includes an example of testing the service using curl.

```bash
# Build the project
make build-release-semantic && make pregenerate-embeddings-ollama MAGICTUNNEL_ENV=development

# Run with custom config
./target/release/magictunnel --config magictunnel-config.yaml

# Run in stdio mode for MCP clients (Claude Desktop, Cursor)
./target/release/magictunnel --stdio --config magictunnel-config.yaml

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

--------------------------------

### Client Connections for Direct HTTPS (Bash)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tls/TLS_DEPLOYMENT_GUIDE.md

Examples of client connections to the MCP Proxy using HTTPS for API calls and secure WebSockets. Demonstrates how to interact with the service over TLS.

```bash
# HTTPS API calls
curl https://magictunnel.example.com:3000/mcp/tools

# Secure WebSocket connections
wscat -c wss://magictunnel.example.com:3000/mcp/ws
```

--------------------------------

### Generate Embeddings with Ollama (Local Development)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

This command pulls the 'nomic-embed-text' model from Ollama and then pre-generates embeddings using the Ollama model for local development. It requires Ollama to be installed and running.

```bash
ollama pull nomic-embed-text
make pregenerate-embeddings-ollama MAGICTUNNEL_ENV=development
```

--------------------------------

### Function Call Routing Example (YAML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

An example of routing a tool request to a specific function within a module, typically used for advanced integrations.

```yaml
routing:
  type: "function"
  module: "my_module"
  function: "process_data"
```

--------------------------------

### Backend Development Setup

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/web-dashboard.md

Commands for running and building the MagicTunnel backend using Cargo and Cargo Watch. It covers running the backend with hot reload, building a release version with embedded frontend, and executing tests.

```bash
cargo watch -x run
cargo build --release
cargo test
```

--------------------------------

### MagicTunnel Configuration Example (YAML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/README.md

Provides an example of a `magictunnel-config.yaml` file, showcasing configuration options for the server host and port, registry paths for capabilities, and smart discovery settings like enabling the feature and choosing a tool selection mode.

```yaml
server:
  host: "127.0.0.1"
  port: 8080

registry:
  paths: ["./capabilities"]

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

--------------------------------

### Get Help for Subcommand

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

Retrieves help information for a specific subcommand of the `magictunnel-cli`, such as `graphql`.

```bash
magictunnel-cli graphql --help
```

--------------------------------

### Bash Troubleshooting: Supervisor Won't Start

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/supervisor.md

Provides bash commands to troubleshoot issues where the MagicTunnel supervisor fails to start. It covers checking port availability, file permissions, and running the supervisor with debug logs.

```bash
# Check port availability
netstat -an | grep 8081
```

```bash
# Check permissions
ls -la target/release/magictunnel-supervisor
```

```bash
# Check logs
RUST_LOG=debug ./target/release/magictunnel-supervisor
```

--------------------------------

### Environment Variables for LLM

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/config.md

Provides examples of environment variables required for different LLM providers, such as OpenAI, Anthropic, and Ollama.

```bash
# OpenAI
export OPENAI_API_KEY="your-api-key"

# Anthropic
export ANTHROPIC_API_KEY="your-api-key"

# Ollama (local)
export OLLAMA_BASE_URL="http://localhost:11434"
```

--------------------------------

### Tool Categorization Example (YAML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

Shows how to assign a category to a tool definition for better organization and discovery within the MagicTunnel system.

```yaml
tools:
  - name: "ping"
    description: "Test network connectivity"
    category: "networking"
    # ... rest of definition
    
  - name: "traceroute"  
    description: "Trace network path"
    category: "networking"
    # ... rest of definition
```

--------------------------------

### Full Stack Setup & API Test (Bash)

Source: https://github.com/magicbeansai/magictunnel/blob/master/README.md

This snippet covers the recommended full-stack setup for MagicTunnel, including cloning the repository, building the release, pre-generating embeddings using Ollama, and running the supervisor. It also demonstrates how to test the smart discovery feature via a cURL command to the MCP API.

```bash
git clone https://github.com/your-org/magictunnel.git
cd magictunnel

make build-release-semantic && make pregenerate-embeddings-ollama MAGICTUNNEL_ENV=development

./magictunnel-supervisor

open http://localhost:5173/dashboard

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

--------------------------------

### Python SDK for Smart Discovery

Source: https://github.com/magicbeansai/magictunnel/blob/master/examples/smart-discovery/README.md

Shows how to use the MagicTunnel Python SDK to interact with the Smart Discovery system, specifically for reading configuration files. This demonstrates programmatic integration.

```python
from magictunnel import SmartDiscoveryClient

client = SmartDiscoveryClient("http://localhost:8080")
response = client.discover_and_execute(
    request="read configuration from YAML file",
    context="Application startup sequence"
)
```

--------------------------------

### Check External MCP Server Status via API

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Checks the status of an external MCP server, if one is configured, by querying the /mcp/external/status endpoint.

```bash
curl http://localhost:3000/mcp/external/status
```

--------------------------------

### Manual Tool Creation Example (YAML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/README.md

Demonstrates how to manually create a tool definition in a YAML file, specifically for a 'ping' tool. It includes the tool's name, a description, an input schema defining the 'host' parameter, and routing information specifying it as a command-line execution.

```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}"]
```

--------------------------------

### Configure Claude Desktop for MagicTunnel

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Add MagicTunnel as an MCP server to Claude Desktop's configuration. This involves specifying the command to run MagicTunnel, its arguments (like `--stdio`), configuration file path, and environment variables.

```json
{
  "mcpServers": {
    "magictunnel": {
      "command": "/path/to/your/magictunnel/target/release/magictunnel",
      "args": [
        "--stdio",
        "--config", "/path/to/your/magictunnel/config.yaml"
      ],
      "env": {
        "RUST_LOG": "info"
      },
      "cwd": "/path/to/your/magictunnel"
    }
  }
}
```

--------------------------------

### Conditional Routing Example (YAML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

Illustrates conditional routing based on parameter values, allowing different routing strategies (HTTP or command) depending on conditions.

```yaml
routing:
  type: "conditional"
  conditions:
    - if: "{method} == 'GET'"
      then:
        type: "http"
        method: "GET"
        url: "https://api.example.com/{endpoint}"
    - else:
        type: "command"
        command: "curl"
        args: ["-X", "{method}", "https://api.example.com/{endpoint}"]
```

--------------------------------

### Check Tool Visibility Status

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

Checks the current visibility status of tools managed by MagicTunnel, optionally with a detailed per-file breakdown. Requires a configuration file.

```bash
cargo run --bin magictunnel-visibility -- -c config.yaml status

cargo run --bin magictunnel-visibility -- -c config.yaml status --detailed
```

--------------------------------

### External MCP Server Routing Example (YAML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

Shows how to route a tool request to an external MCP server, specifying the server, tool, and optional parameter mapping.

```yaml
routing:
  type: "external_mcp" 
  server: "filesystem-server"
  tool: "read_file"
  parameter_mapping:          # Optional parameter transformation
    file_path: "{path}"
```

--------------------------------

### Dockerfile for MagicTunnel Build

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/deploy.md

A multi-stage Dockerfile that first builds the MagicTunnel binary using Rust and then creates a slim Debian-based image containing the executable and necessary files.

```dockerfile
FROM rust:1.70 AS builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY --from=builder /app/target/release/magictunnel .
COPY config.yaml .
COPY capabilities/ ./capabilities/
EXPOSE 3000 4000
CMD ["./magictunnel", "--config", "config.yaml"]
```

--------------------------------

### Generate Tools using Unified CLI

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

Demonstrates generating capability files for different API types (GraphQL, gRPC, OpenAPI) using the unified `magictunnel-cli`.

```bash
magictunnel-cli graphql --schema schema.graphql --endpoint https://api.example.com/graphql --output capabilities.yaml
magictunnel-cli grpc --proto service.proto --endpoint localhost:50051 --output capabilities.yaml  
magictunnel-cli openapi --spec openapi.json --base-url https://api.example.com --output capabilities.yaml
```

--------------------------------

### Define Basic Tool (YAML)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/tools.md

Example of a basic tool definition in YAML, specifying its name, description, input schema using JSON Schema, and routing configuration.

```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"
        count:
          type: integer
          description: "Number of ping packets to send"
          default: 4
    routing:
      type: "command"
      command: "ping"
      args: ["-c", "{count}", "{host}"]
```

--------------------------------

### Generate Embeddings with Local Fallback Models

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/quickstart.md

These commands pre-generate embeddings using local, hash-based fallback models. They are suitable for testing but offer limited semantic functionality.

```bash
make pregenerate-embeddings-local    # all-MiniLM-L6-v2 hash fallback
make pregenerate-embeddings-hq       # all-mpnet-base-v2 hash fallback
```

--------------------------------

### Docker Deployment for MagicTunnel

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/guide.md

Provides a Dockerfile for building and deploying the MagicTunnel application. It includes multi-stage builds for efficient image creation, copying the compiled Rust binary, and exposing the necessary port.

```Dockerfile
FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates
COPY --from=builder /app/target/release/magictunnel /usr/local/bin/
EXPOSE 8080
CMD ["magictunnel"]
```

--------------------------------

### Docker Deployment (Dockerfile)

Source: https://github.com/magicbeansai/magictunnel/blob/master/docs/supervisor.md

A Dockerfile for building a production-ready Docker image for the MagicTunnel supervisor, including build steps and runtime configuration.

```dockerfile
# Dockerfile for supervisor
FROM rust:1.70 AS builder
COPY . .
RUN cargo build --release --bin magictunnel-supervisor

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/magictunnel-supervisor /usr/local/bin/
EXPOSE 8081
CMD ["magictunnel-supervisor"]
```