diff --git a/astro.config.ts b/astro.config.ts index 67bfc42..c0ce139 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -144,46 +144,24 @@ export default defineConfig({ { label: "Overview", link: "/mcp-gateway" }, { label: "Getting Started", link: "/mcp-gateway/getting-started" }, { - label: "Core Concepts", + label: "Reference", collapsed: false, items: [ + { label: "CLI", link: "/mcp-gateway/reference#cli" }, + { label: "Storage", link: "/mcp-gateway/reference#storage" }, { - label: "Server Management", - link: "/mcp-gateway/core-concepts/server-management", - }, - { - label: "Activity Logging", - link: "/mcp-gateway/core-concepts/activity-logging", - }, - { - label: "Interfaces", - link: "/mcp-gateway/core-concepts/interfaces", - }, - ], - }, - { - label: "Features", - collapsed: false, - items: [ - { - label: "CLI Options", - link: "/mcp-gateway/features/cli-options", - }, - { - label: "Terminal UI", - link: "/mcp-gateway/features/terminal-ui", - }, - { - label: "Web Interface", - link: "/mcp-gateway/features/web-interface", + label: "Authentication", + link: "/mcp-gateway/reference#authentication", }, + { label: "Proxy", link: "/mcp-gateway/reference#proxy" }, + { label: "REST API", link: "/mcp-gateway/reference#rest-api" }, { - label: "Storage & Registry", - link: "/mcp-gateway/features/storage", + label: "Gateway MCP Server", + link: "/mcp-gateway/reference#gateway-mcp-server", }, + { label: "Web UI", link: "/mcp-gateway/reference#web-ui" }, ], }, - { label: "Troubleshooting", link: "/mcp-gateway/troubleshooting" }, ], }, ], diff --git a/src/assets/add-mcp-server-form.png b/src/assets/add-mcp-server-form.png new file mode 100644 index 0000000..8fe8ab8 Binary files /dev/null and b/src/assets/add-mcp-server-form.png differ diff --git a/src/assets/adding-mcp-server.png b/src/assets/adding-mcp-server.png new file mode 100644 index 0000000..e974538 Binary files /dev/null and b/src/assets/adding-mcp-server.png differ diff --git a/src/assets/mcp-server-logs.png b/src/assets/mcp-server-logs.png new file mode 100644 index 0000000..c1b6a08 Binary files /dev/null and b/src/assets/mcp-server-logs.png differ diff --git a/src/assets/terminal-output.png b/src/assets/terminal-output.png new file mode 100644 index 0000000..69977a0 Binary files /dev/null and b/src/assets/terminal-output.png differ diff --git a/src/content/docs/mcp-gateway/core-concepts/activity-logging.md b/src/content/docs/mcp-gateway/core-concepts/activity-logging.md deleted file mode 100644 index cf3c645..0000000 --- a/src/content/docs/mcp-gateway/core-concepts/activity-logging.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -title: Activity Logging -description: Track and inspect MCP requests and responses ---- - -MCP Gateway captures all traffic flowing through the proxy, providing detailed logs for debugging and monitoring. - -## What Gets Logged - -### Request Data - -For each request, the gateway logs: -- **Timestamp**: When the request was received -- **Server**: Which MCP server handled the request -- **Method**: The MCP method called -- **Parameters**: Request parameters (sanitized if needed) -- **Headers**: HTTP headers - -### Response Data - -For each response, the gateway logs: -- **Status**: Success or error -- **Result**: The response payload -- **Duration**: How long the request took -- **Size**: Response size in bytes - -### Example Log Entry - -```jsonl -{ - "timestamp": "2025-01-20T15:30:45.123Z", - "server": "github-server", - "method": "tools/list", - "params": {}, - "response": { - "tools": [ - { "name": "create_issue", "description": "..." } - ] - }, - "duration_ms": 45, - "status": "success" -} -``` - -## Log Storage - -### Storage Location - -Logs are stored in `~/.mcp-gateway/captures/`: - -``` -~/.mcp-gateway/ -├── mcp.json # Server registry -└── captures/ - ├── github-server/ - │ ├── 2025-01-20.jsonl - │ └── 2025-01-21.jsonl - └── weather-server/ - └── 2025-01-20.jsonl -``` - -### Log Format - -Logs are stored as **JSON Lines (JSONL)**: -- One JSON object per line -- Easy to parse and process -- Efficient for streaming - -### Log Rotation - -- Logs are organized by server and date -- Each day creates a new log file -- Old logs are retained based on storage settings - -## Inspecting Logs - -### Via Terminal UI - -Press `v` to open the Activity Log viewer: - -- **Navigation**: Use arrow keys to scroll -- **Filter**: Press `/` to search -- **Details**: Press Enter to view full request/response -- **Clear**: Press `c` to clear the current view (doesn't delete files) - -### Via Web UI - -Navigate to a server in the Web UI: - -1. Select a server from the dashboard -2. View the activity log in the sidebar -3. Click on entries to see details -4. Use filters to narrow down results - -### Via Command Line - -Logs are plain JSON Lines files, so you can use standard tools: - -```bash -# View today's logs for a server -cat ~/.mcp-gateway/captures/github-server/$(date +%Y-%m-%d).jsonl - -# Pretty-print logs -cat ~/.mcp-gateway/captures/github-server/*.jsonl | jq '.' - -# Filter by method -cat ~/.mcp-gateway/captures/github-server/*.jsonl | jq 'select(.method == "tools/list")' - -# Count requests per method -cat ~/.mcp-gateway/captures/github-server/*.jsonl | jq -r '.method' | sort | uniq -c -``` - -## Filtering and Searching - -### Terminal UI Filters - -In the Activity Log (`v`): -- `/`: Open search -- Type to filter by any field -- ESC to clear filter - -### Web UI Filters - -Use the filter controls to: -- Filter by date range -- Filter by server -- Filter by method -- Filter by status (success/error) -- Search in request/response data - -## Log Retention - -### Default Retention - -By default, logs are kept indefinitely. You can manually clean up old logs: - -```bash -# Remove logs older than 30 days -find ~/.mcp-gateway/captures -name "*.jsonl" -mtime +30 -delete -``` - -### Custom Retention - -Set up a cron job for automatic cleanup: - -```bash -# Add to crontab: clean up logs older than 30 days daily -0 2 * * * find ~/.mcp-gateway/captures -name "*.jsonl" -mtime +30 -delete -``` - -## Privacy and Security - -### Sensitive Data - -The gateway logs all request and response data. If your MCP servers handle sensitive information: - -- Avoid logging in production environments -- Implement log sanitization -- Restrict access to the storage directory -- Use encryption for log files - -### Log Access - -Protect log files with appropriate permissions: - -```bash -# Restrict access to logs -chmod 700 ~/.mcp-gateway -chmod 600 ~/.mcp-gateway/captures/**/*.jsonl -``` - -## Performance Considerations - -### Log Volume - -High-traffic servers generate large log files. Monitor disk usage: - -```bash -# Check log storage size -du -sh ~/.mcp-gateway/captures -``` - -### Impact on Gateway - -Logging has minimal performance impact: -- Logs written asynchronously -- Buffered writes for efficiency -- No impact on request/response latency - -## Use Cases - -### Debugging - -Inspect failed requests: - -```bash -# Find all errors -cat ~/.mcp-gateway/captures/*/*.jsonl | jq 'select(.status == "error")' -``` - -### Performance Analysis - -Analyze request durations: - -```bash -# Average response time -cat ~/.mcp-gateway/captures/my-server/*.jsonl | \ - jq '.duration_ms' | \ - awk '{sum+=$1; count++} END {print sum/count}' -``` - -### Usage Monitoring - -Track API usage: - -```bash -# Requests per hour -cat ~/.mcp-gateway/captures/my-server/*.jsonl | \ - jq -r '.timestamp' | \ - cut -d: -f1 | \ - sort | uniq -c -``` - -### Replay and Testing - -Use captured logs to replay requests for testing: - -```bash -# Extract a request -cat ~/.mcp-gateway/captures/my-server/*.jsonl | \ - jq 'select(.method == "tools/list") | .params' | \ - head -1 -``` - -## Next Steps - -- [**Interfaces**](/mcp-gateway/core-concepts/interfaces) - Learn about TUI and Web UI -- [**Storage & Registry**](/mcp-gateway/features/storage) - Understand data persistence -- [**Debugging**](/mcp-gateway/development/debugging) - Advanced debugging techniques diff --git a/src/content/docs/mcp-gateway/core-concepts/interfaces.md b/src/content/docs/mcp-gateway/core-concepts/interfaces.md deleted file mode 100644 index 9e7b74d..0000000 --- a/src/content/docs/mcp-gateway/core-concepts/interfaces.md +++ /dev/null @@ -1,254 +0,0 @@ ---- -title: Interfaces -description: Terminal UI and Web UI for managing MCP Gateway ---- - -MCP Gateway provides two interfaces for managing servers and viewing logs: a Terminal UI (TUI) for keyboard-driven workflows and a Web UI for visual management. - -## Terminal UI (TUI) - -The Terminal UI runs in your console and provides fast, keyboard-driven access to all gateway features. - -### Starting the TUI - -```bash -# TUI starts by default -mcp-gateway - -# Disable TUI (headless mode) -mcp-gateway --no-tui -``` - -### Navigation - -Use keyboard shortcuts to navigate: - -- `/` - Open command menu -- `q` - Quit application -- `ESC` - Go back / Close modal -- Arrow keys - Navigate lists -- Enter - Select / View details - -### Main Views - -#### Activity Log (`v`) - -View real-time request/response activity: -- Scroll through recent events -- Filter by keyword -- View full request/response details -- Clear the current view - -#### Server Management (`m`) - -Manage MCP servers: -- View all configured servers -- See connection status -- Add new servers -- Remove servers - -#### Help (`h`) - -Access help and setup guide: -- Keyboard shortcuts reference -- Setup instructions -- Troubleshooting tips - -### Command Menu (`/`) - -Quick access to all commands: - -``` -/ - Command Menu -──────────────── -v - View Activity Log -m - Manage Servers -a - Add New Server -c - Clear Activity Logs -h - Help & Setup Guide -q - Quit -``` - -### Adding Servers - -Press `a` to add a server: - -``` -┌─ Add MCP Server ─────────────┐ -│ │ -│ Name: [____________] │ -│ URL: [____________] │ -│ │ -│ [Cancel] [Add] │ -└───────────────────────────────┘ -``` - -### Activity Log View - -``` -┌─ Activity Log ───────────────────────────────┐ -│ [Filter: ___________] │ -├──────────────────────────────────────────────┤ -│ ● 15:30:45 github-server tools/list 45ms │ -│ ● 15:30:50 weather-server query 120ms│ -│ ● 15:30:55 github-server tools/call 89ms │ -│ │ -│ Press Enter to view details │ -└──────────────────────────────────────────────┘ -``` - -### Terminal Compatibility - -Recommended terminals: -- **macOS**: iTerm2, Alacritty, Terminal.app -- **Linux**: Alacritty, kitty, gnome-terminal -- **Windows**: Windows Terminal, Alacritty - -Requirements: -- ANSI escape code support -- UTF-8 encoding -- Minimum 80x24 character size - -## Web UI - -The Web UI provides a browser-based interface for visual server management and log inspection. - -### Accessing the Web UI - -```bash -# Default URL -http://localhost:3333/ui - -# Custom port -http://localhost:8080/ui # if using --port 8080 -``` - -Or open automatically: - -```bash -open http://localhost:3333/ui # macOS -xdg-open http://localhost:3333/ui # Linux -``` - -### Dashboard - -The main dashboard shows: -- **Server List**: All configured MCP servers -- **Status Indicators**: Connection state for each server -- **Recent Activity**: Latest requests across all servers -- **Quick Actions**: Add/remove servers - -### Server Management - -Click on a server to: -- View detailed information -- See server-specific activity log -- Configure server settings -- Test connectivity -- Remove the server - -### Activity Inspection - -The activity view provides: -- **Timeline**: Chronological list of requests -- **Filters**: By server, method, date range, status -- **Search**: Full-text search in requests/responses -- **Details**: Click any entry to see full request/response - -Example log entry view: - -``` -Request -──────── -Method: tools/list -Server: github-server -Time: 2025-01-20 15:30:45 - -Response -──────── -Status: Success -Duration: 45ms -Result: -{ - "tools": [ - { - "name": "create_issue", - "description": "Create a GitHub issue" - } - ] -} -``` - -### Adding Servers - -Click "Add Server" button: - -1. Enter server name -2. Enter server URL -3. Click "Add" -4. Server appears in the list - -### Server Configuration - -Click on a server card to configure: -- Edit server name -- Update server URL -- View connection history -- Remove server - -## Choosing an Interface - -### Use Terminal UI When: - -- Working in a terminal-focused workflow -- Need keyboard-driven speed -- SSH into remote servers -- Limited screen space -- Prefer command-line tools - -### Use Web UI When: - -- Prefer visual interfaces -- Need to share view with others -- Want to keep logs visible while working -- Managing multiple servers visually -- Need detailed filtering and search - -## Running Both Simultaneously - -You can use both interfaces at the same time: - -```bash -# Start gateway (TUI + Web UI) -mcp-gateway - -# In your browser -open http://localhost:3333/ui -``` - -Both interfaces share the same data: -- Changes in TUI reflect in Web UI -- Web UI updates show in TUI -- Logs visible in both - -## Headless Mode - -Run without the TUI for background operation: - -```bash -mcp-gateway --no-tui -``` - -Useful for: -- Docker containers -- systemd services -- CI/CD environments -- Production deployments - -Access via Web UI only: `http://localhost:3333/ui` - -## Next Steps - -- [**Terminal UI Features**](/mcp-gateway/features/terminal-ui) - Master keyboard shortcuts -- [**Web Interface**](/mcp-gateway/features/web-interface) - Explore Web UI features -- [**CLI Options**](/mcp-gateway/features/cli-options) - Configure the gateway diff --git a/src/content/docs/mcp-gateway/core-concepts/server-management.md b/src/content/docs/mcp-gateway/core-concepts/server-management.md deleted file mode 100644 index 509a942..0000000 --- a/src/content/docs/mcp-gateway/core-concepts/server-management.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: Server Management -description: Add, configure, and monitor MCP servers ---- - -MCP Gateway acts as a proxy for multiple MCP servers, allowing you to manage them all from one interface. - -## Adding Servers - -### Via Terminal UI - -1. Press `a` to open the "Add Server" dialog -2. Enter server details: - - **Name**: A unique identifier for this server - - **URL**: The HTTP endpoint for the MCP server -3. Press Enter to save - -Example: -``` -Name: weather-server -URL: http://localhost:3000/mcp -``` - -### Via Web UI - -1. Navigate to `http://localhost:3333/ui` -2. Click "Add Server" -3. Fill in the form and submit - -### Via Registry File - -Manually edit `~/.mcp-gateway/mcp.json`: - -```json -{ - "servers": [ - { - "name": "weather-server", - "url": "http://localhost:3000/mcp" - }, - { - "name": "database-server", - "url": "http://localhost:4000/mcp" - } - ] -} -``` - -## Server Configuration - -### URL Format - -MCP Gateway expects HTTP endpoints that implement the MCP protocol: - -``` -http://localhost:3000/mcp -https://api.example.com/mcp -``` - -### Server Names - -- Must be unique within the registry -- Used to identify servers in logs and UI -- Can contain letters, numbers, hyphens, and underscores - -## Monitoring Servers - -### Server Status - -The gateway tracks the status of each server: - -- **Connected**: Server is reachable and responding -- **Disconnected**: Server is not responding -- **Error**: Server returned an error - -### Viewing Status - -**Terminal UI:** -- Press `m` to open Server Management -- View the status column for each server - -**Web UI:** -- Check the server dashboard -- Status indicators show connection state - -## Managing Servers - -### View Server List - -**TUI**: Press `m` -**Web UI**: Navigate to the servers page - -### Remove a Server - -**TUI**: -1. Press `m` to open Server Management -2. Select the server -3. Press `d` to delete - -**Web UI**: -1. Navigate to the server -2. Click "Remove Server" - -### Edit Server Configuration - -**Registry File**: -Edit `~/.mcp-gateway/mcp.json` and restart the gateway. - -## Connection Handling - -### Automatic Reconnection - -The gateway automatically attempts to reconnect to servers that become unavailable. - -### Connection Timeout - -If a server doesn't respond within the timeout period, it's marked as disconnected. - -### Error Handling - -Connection errors are logged in the activity log. View them with: -- **TUI**: Press `v` -- **Web UI**: Check the server's activity log - -## Multi-Server Routing - -The gateway routes requests to servers based on: -- Server name in the request -- Path-based routing (if configured) -- Round-robin (if multiple servers handle the same capability) - -## Best Practices - -### Naming Conventions - -Use descriptive names that reflect the server's purpose: -- ✅ `github-integration` -- ✅ `database-tools` -- ❌ `server1` -- ❌ `test` - -### URL Management - -- Use `http://localhost` for local development -- Use full URLs with HTTPS for production servers -- Ensure servers are accessible from the gateway's network - -### Server Organization - -Group related servers logically: -- Development servers on separate ports -- Production servers with HTTPS -- Test servers isolated from production - -## Troubleshooting - -### Server Won't Connect - -1. Verify the URL is correct -2. Check the server is running: `curl ` -3. Check for CORS issues (HTTP MCP servers) -4. Review server logs for errors - -### Server Shows Disconnected - -- Check network connectivity -- Verify the server is still running -- Look for errors in activity logs - -### Cannot Add Server - -- Ensure the name is unique -- Verify URL format is correct -- Check for typos in the URL - -## Next Steps - -- [**Activity Logging**](/mcp-gateway/core-concepts/activity-logging) - Track requests and responses -- [**Terminal UI**](/mcp-gateway/features/terminal-ui) - Master keyboard shortcuts -- [**Storage & Registry**](/mcp-gateway/features/storage) - Understand data persistence diff --git a/src/content/docs/mcp-gateway/features/cli-options.md b/src/content/docs/mcp-gateway/features/cli-options.md deleted file mode 100644 index cde4dd1..0000000 --- a/src/content/docs/mcp-gateway/features/cli-options.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: CLI Options -description: Command-line configuration options for MCP Gateway ---- - -Configure MCP Gateway behavior using command-line flags. - -## Basic Usage - -```bash -mcp-gateway [options] -``` - -## Options - -### `--port ` - -Set the HTTP server port. - -```bash -# Use port 8080 instead of default 3333 -mcp-gateway --port 8080 -``` - -**Default:** `3333` - -**Example:** -```bash -mcp-gateway --port 8080 -# API: http://localhost:8080/api -# Web UI: http://localhost:8080/ui -``` - -### `--storage-dir ` - -Set custom storage directory for logs and registry. - -```bash -mcp-gateway --storage-dir /custom/path -``` - -**Default:** `~/.mcp-gateway` - -**Example:** -```bash -mcp-gateway --storage-dir ~/my-gateway-data -# Registry: ~/my-gateway-data/mcp.json -# Logs: ~/my-gateway-data/captures/ -``` - -### `--no-tui` - -Run in headless mode without the Terminal UI. - -```bash -mcp-gateway --no-tui -``` - -**Use Cases:** -- Docker containers with TTY allocated but headless mode desired -- systemd services -- CI/CD environments -- Background processes -- Multiple instances managed via Web UI only - -**Example:** -```bash -# Run in background -mcp-gateway --no-tui & - -# Access via Web UI -open http://localhost:3333/ui -``` - -### `--help` - -Display help information. - -```bash -mcp-gateway --help -``` - -**Output:** -``` -MCP Gateway - Unified proxy for MCP servers - -Usage: mcp-gateway [options] - -Options: - --port Set HTTP server port (default: 3333) - --storage-dir Set storage directory (default: ~/.mcp-gateway) - --no-tui Run without Terminal UI - --version Show version number - --help Show this help message -``` - -### `--version` - -Display version information. - -```bash -mcp-gateway --version -``` - -**Output:** -``` -@fiberplane/mcp-gateway v1.0.0 -``` - -## Combining Options - -You can combine multiple options: - -```bash -mcp-gateway --port 8080 --storage-dir ~/gateway --no-tui -``` - -This configures the gateway to: -- Run on port 8080 -- Store data in `~/gateway` -- Run without Terminal UI - -## Environment Variables - -Some configurations can be set via environment variables: - -### `MCP_GATEWAY_PORT` - -Alternative to `--port`: - -```bash -MCP_GATEWAY_PORT=8080 mcp-gateway -``` - -### `MCP_GATEWAY_STORAGE_DIR` - -Alternative to `--storage-dir`: - -```bash -MCP_GATEWAY_STORAGE_DIR=~/gateway mcp-gateway -``` - -**Note:** CLI flags take precedence over environment variables. - -## Configuration Precedence - -Options are applied in this order (highest to lowest): - -1. Command-line flags -2. Environment variables -3. Default values - -Example: - -```bash -# Port will be 9000 (CLI flag wins) -MCP_GATEWAY_PORT=8080 mcp-gateway --port 9000 -``` - -## Common Patterns - -### Development - -```bash -# Default settings, with TUI -mcp-gateway -``` - -### Production (systemd) - -```bash -# Headless, custom storage, non-default port -mcp-gateway --no-tui --port 8080 --storage-dir /var/lib/mcp-gateway -``` - -### Docker - -```bash -# Headless, standard port, volume-mounted storage -docker run -p 3333:3333 \ - -v ./data:/data \ - mcp-gateway --no-tui --storage-dir /data -``` - -### Multiple Instances - -```bash -# Instance 1 -mcp-gateway --port 3333 --storage-dir ~/.mcp-gateway-1 - -# Instance 2 -mcp-gateway --port 3334 --storage-dir ~/.mcp-gateway-2 -``` - -## Troubleshooting - -### Port Already in Use - -**Error:** `EADDRINUSE: address already in use :::3333` - -**Solution:** -```bash -# Find process using port -lsof -i :3333 - -# Kill process -kill -9 - -# Or use different port -mcp-gateway --port 8080 -``` - -### Permission Denied (Storage Directory) - -**Error:** `EACCES: permission denied, mkdir '/var/lib/mcp-gateway'` - -**Solution:** -```bash -# Create directory with proper permissions -sudo mkdir -p /var/lib/mcp-gateway -sudo chown $USER:$USER /var/lib/mcp-gateway - -# Or use user-writable directory -mcp-gateway --storage-dir ~/mcp-gateway -``` - -### Invalid Port Number - -**Error:** `Invalid port number: abc` - -**Solution:** -```bash -# Use numeric port between 1-65535 -mcp-gateway --port 3333 -``` - -## Next Steps - -- [**Terminal UI**](/mcp-gateway/features/terminal-ui) - Master keyboard shortcuts -- [**Storage & Registry**](/mcp-gateway/features/storage) - Understand data storage -- [**Production Deployment**](/mcp-gateway/deployment/production) - Deploy to production diff --git a/src/content/docs/mcp-gateway/features/storage.md b/src/content/docs/mcp-gateway/features/storage.md deleted file mode 100644 index 0459366..0000000 --- a/src/content/docs/mcp-gateway/features/storage.md +++ /dev/null @@ -1,370 +0,0 @@ ---- -title: Storage & Registry -description: Data persistence and file organization ---- - -MCP Gateway stores server configuration and captured logs in a local directory. - -## Storage Location - -### Default Directory - -``` -~/.mcp-gateway/ -``` - -### Custom Directory - -```bash -mcp-gateway --storage-dir /custom/path -``` - -Or via environment variable: - -```bash -MCP_GATEWAY_STORAGE_DIR=/custom/path mcp-gateway -``` - -## Directory Structure - -``` -~/.mcp-gateway/ -├── mcp.json # Server registry -└── captures/ # Captured logs - ├── github-server/ - │ ├── 2025-01-20.jsonl - │ ├── 2025-01-21.jsonl - │ └── 2025-01-22.jsonl - ├── weather-server/ - │ └── 2025-01-20.jsonl - └── database-server/ - └── 2025-01-20.jsonl -``` - -## Server Registry - -### File: `mcp.json` - -The registry stores server configurations. - -### Format - -```json -{ - "version": "1.0", - "servers": [ - { - "id": "github-server", - "name": "GitHub Integration", - "url": "http://localhost:3000/mcp", - "createdAt": "2025-01-20T10:00:00.000Z", - "updatedAt": "2025-01-20T10:00:00.000Z" - }, - { - "id": "weather-server", - "name": "Weather Service", - "url": "http://localhost:4000/mcp", - "createdAt": "2025-01-20T11:00:00.000Z", - "updatedAt": "2025-01-20T11:00:00.000Z" - } - ] -} -``` - -### Manual Editing - -You can manually edit `mcp.json`: - -```bash -# Edit registry -nano ~/.mcp-gateway/mcp.json - -# Restart gateway to apply changes -mcp-gateway -``` - -**Caution**: Invalid JSON will prevent the gateway from starting. - -### Backup - -```bash -# Backup registry -cp ~/.mcp-gateway/mcp.json ~/.mcp-gateway/mcp.json.backup - -# Restore from backup -cp ~/.mcp-gateway/mcp.json.backup ~/.mcp-gateway/mcp.json -``` - -## Capture Storage - -### Organization - -Logs are organized by server and date: - -``` -captures/ -└── / - └── YYYY-MM-DD.jsonl -``` - -### File Format: JSON Lines - -Each log file uses JSON Lines format: -- One JSON object per line -- Easy to parse and stream -- Append-only for performance - -### Example Log File - -```jsonl -{"timestamp":"2025-01-20T15:30:45.123Z","server":"github-server","method":"tools/list","params":{},"response":{"tools":[]},"duration_ms":45,"status":"success"} -{"timestamp":"2025-01-20T15:30:50.456Z","server":"github-server","method":"tools/call","params":{"name":"create_issue"},"response":{"content":[{"type":"text","text":"Issue created"}]},"duration_ms":89,"status":"success"} -``` - -### Log Rotation - -- New file created each day -- No automatic cleanup (manual or scripted) -- Files can be deleted without affecting the gateway - -## Data Persistence - -### When Data is Written - -**Registry (`mcp.json`):** -- When adding a server -- When removing a server -- When updating server configuration - -**Captures:** -- After each request/response -- Buffered writes for performance -- Flushed on gateway shutdown - -### Data Durability - -- Registry updates are atomic (safe from crashes) -- Logs written asynchronously (small risk of loss on crash) -- No data loss on clean shutdown - -## Disk Usage - -### Monitoring - -```bash -# Check total storage size -du -sh ~/.mcp-gateway - -# Check captures size -du -sh ~/.mcp-gateway/captures - -# Size by server -du -sh ~/.mcp-gateway/captures/* -``` - -### Example Sizes - -Approximate disk usage: -- Registry: ~1-10 KB -- Logs: ~1-10 MB per day per high-traffic server - -## Cleanup - -### Manual Cleanup - -```bash -# Remove old logs (older than 30 days) -find ~/.mcp-gateway/captures -name "*.jsonl" -mtime +30 -delete - -# Remove all logs for a specific server -rm -rf ~/.mcp-gateway/captures/old-server -``` - -### Automated Cleanup - -Create a cron job: - -```bash -# Edit crontab -crontab -e - -# Add daily cleanup at 2 AM -0 2 * * * find ~/.mcp-gateway/captures -name "*.jsonl" -mtime +30 -delete -``` - -### Cleanup Script - -```bash -#!/bin/bash -# cleanup-gateway-logs.sh - -STORAGE_DIR="${MCP_GATEWAY_STORAGE_DIR:-$HOME/.mcp-gateway}" -RETENTION_DAYS=30 - -find "$STORAGE_DIR/captures" \ - -name "*.jsonl" \ - -mtime +$RETENTION_DAYS \ - -delete - -echo "Cleaned up logs older than $RETENTION_DAYS days" -``` - -## Migration - -### Moving Storage Directory - -```bash -# Stop gateway -# Move directory -mv ~/.mcp-gateway ~/new-location/.mcp-gateway - -# Start with new location -mcp-gateway --storage-dir ~/new-location/.mcp-gateway -``` - -### Merging Registries - -```bash -# Backup both registries -cp ~/.mcp-gateway-1/mcp.json mcp1.json -cp ~/.mcp-gateway-2/mcp.json mcp2.json - -# Manually merge server arrays in a text editor -# Copy merged file to primary location -cp merged.json ~/.mcp-gateway/mcp.json -``` - -### Combining Logs - -```bash -# Merge logs for the same server from different gateways -cat ~/.mcp-gateway-1/captures/my-server/*.jsonl \ - ~/.mcp-gateway-2/captures/my-server/*.jsonl \ - > combined.jsonl - -# Sort by timestamp -cat combined.jsonl | jq -s 'sort_by(.timestamp)[]' > sorted.jsonl -``` - -## Backup and Restore - -### Full Backup - -```bash -# Backup entire storage directory -tar -czf mcp-gateway-backup-$(date +%Y%m%d).tar.gz ~/.mcp-gateway -``` - -### Restore from Backup - -```bash -# Stop gateway -# Extract backup -tar -xzf mcp-gateway-backup-20250120.tar.gz -C ~/ - -# Start gateway -mcp-gateway -``` - -### Selective Backup - -```bash -# Backup registry only -cp ~/.mcp-gateway/mcp.json mcp-backup.json - -# Backup logs for specific server -tar -czf github-server-logs.tar.gz ~/.mcp-gateway/captures/github-server -``` - -## Security - -### File Permissions - -Protect sensitive data: - -```bash -# Restrict directory access -chmod 700 ~/.mcp-gateway - -# Restrict registry access -chmod 600 ~/.mcp-gateway/mcp.json - -# Restrict logs -chmod 600 ~/.mcp-gateway/captures/**/*.jsonl -``` - -### Encryption - -For sensitive environments: - -```bash -# Encrypt storage directory (macOS) -hdiutil create -size 100m -encryption -volname "MCP Gateway" \ - -fs HFS+J ~/mcp-gateway-encrypted.dmg - -# Mount and use -hdiutil attach ~/mcp-gateway-encrypted.dmg -mcp-gateway --storage-dir /Volumes/MCP\ Gateway -``` - -### Git Ignore - -If storage is in a project directory: - -```gitignore -# .gitignore -.mcp-gateway/ -*.jsonl -mcp.json -``` - -## Troubleshooting - -### Registry Corrupted - -**Symptoms:** Gateway won't start, JSON parse error - -**Solution:** -```bash -# Restore from backup -cp ~/.mcp-gateway/mcp.json.backup ~/.mcp-gateway/mcp.json - -# Or recreate empty registry -echo '{"version":"1.0","servers":[]}' > ~/.mcp-gateway/mcp.json -``` - -### Disk Full - -**Symptoms:** ENOSPC error, logs not being written - -**Solution:** -```bash -# Check disk space -df -h - -# Clean up old logs -find ~/.mcp-gateway/captures -name "*.jsonl" -mtime +7 -delete - -# Or move storage to larger disk -mv ~/.mcp-gateway /larger-disk/.mcp-gateway -mcp-gateway --storage-dir /larger-disk/.mcp-gateway -``` - -### Permission Denied - -**Symptoms:** EACCES error - -**Solution:** -```bash -# Fix permissions -chmod -R u+rw ~/.mcp-gateway - -# Or use different directory -mcp-gateway --storage-dir ~/mcp-data -``` - -## Next Steps - -- [**Activity Logging**](/mcp-gateway/core-concepts/activity-logging) - Understanding captured logs -- [**CLI Options**](/mcp-gateway/features/cli-options) - Configure storage location -- [**Debugging**](/mcp-gateway/development/debugging) - Inspect storage diff --git a/src/content/docs/mcp-gateway/features/terminal-ui.md b/src/content/docs/mcp-gateway/features/terminal-ui.md deleted file mode 100644 index 4d36162..0000000 --- a/src/content/docs/mcp-gateway/features/terminal-ui.md +++ /dev/null @@ -1,309 +0,0 @@ ---- -title: Terminal UI -description: Keyboard shortcuts and TUI features ---- - -The Terminal UI (TUI) provides a fast, keyboard-driven interface for managing MCP servers and viewing activity logs. - -## Keyboard Shortcuts - -### Global - -| Key | Action | -|-----|--------| -| `/` | Open command menu | -| `q` | Quit application | -| `ESC` | Go back / Close modal | -| `h` | Help & Setup Guide | - -### Navigation - -| Key | Action | -|-----|--------| -| `↑` `↓` | Navigate up/down in lists | -| `←` `→` | Navigate left/right (where applicable) | -| `Enter` | Select / View details | -| `Tab` | Move between input fields | - -### Views - -| Key | Action | -|-----|--------| -| `v` | View Activity Log | -| `m` | Manage Servers | -| `a` | Add New Server | -| `c` | Clear Activity Logs (view only) | - -## Command Menu - -Press `/` to open the command menu: - -``` -┌─ Command Menu ──────────────────┐ -│ │ -│ v View Activity Log │ -│ m Manage Servers │ -│ a Add New Server │ -│ c Clear Activity Logs │ -│ h Help & Setup Guide │ -│ q Quit │ -│ │ -└──────────────────────────────────┘ -``` - -Navigate with arrow keys and press `Enter` to select. - -## Activity Log View - -Press `v` to view the activity log. - -### Features - -- **Real-time updates**: See requests as they happen -- **Filtering**: Press `/` to filter by keyword -- **Details**: Press `Enter` to view full request/response -- **Auto-scroll**: Automatically scrolls to show newest entries - -### Layout - -``` -┌─ Activity Log ────────────────────────────────────┐ -│ Filter: [______________] │ -├───────────────────────────────────────────────────┤ -│ Time Server Method Duration │ -├───────────────────────────────────────────────────┤ -│ ● 15:30:45 github-server tools/list 45ms │ -│ ● 15:30:50 weather-server query 120ms │ -│ ● 15:30:55 github-server tools/call 89ms │ -│ ● 15:31:00 database-server query 234ms │ -│ │ -│ ↑↓ Navigate Enter: Details /: Filter ESC: Back │ -└────────────────────────────────────────────────────┘ -``` - -### Filtering - -1. Press `/` while in Activity Log -2. Type your search term -3. Press `Enter` to apply -4. Press `ESC` to clear filter - -**Example filters:** -- `github` - Show only github-server logs -- `tools/list` - Show only tools/list method calls -- `error` - Show only errors - -### Viewing Details - -1. Navigate to an entry with arrow keys -2. Press `Enter` to view details - -``` -┌─ Request Details ─────────────────────────────────┐ -│ │ -│ Time: 2025-01-20 15:30:45 │ -│ Server: github-server │ -│ Method: tools/list │ -│ Duration: 45ms │ -│ Status: Success │ -│ │ -│ Request: │ -│ { │ -│ "params": {} │ -│ } │ -│ │ -│ Response: │ -│ { │ -│ "tools": [ │ -│ { │ -│ "name": "create_issue", │ -│ "description": "Create a GitHub issue" │ -│ } │ -│ ] │ -│ } │ -│ │ -│ Press ESC to close │ -└───────────────────────────────────────────────────┘ -``` - -### Clearing the View - -Press `c` to clear the current view: -- Clears the display buffer -- Does **not** delete log files -- Useful for reducing clutter - -## Server Management View - -Press `m` to manage servers. - -### Features - -- View all configured servers -- See connection status -- Navigate to add/remove servers -- Monitor server health - -### Layout - -``` -┌─ Server Management ────────────────────────────────┐ -│ │ -│ Name URL Status │ -├────────────────────────────────────────────────────┤ -│ ● github-server http://localhost:3000 Connected │ -│ ○ weather-server http://localhost:4000 Disconn. │ -│ ● database-server http://localhost:5000 Connected │ -│ │ -│ ↑↓ Navigate a: Add d: Delete Enter: Details │ -└────────────────────────────────────────────────────┘ -``` - -### Status Indicators - -- `●` (green) - Connected -- `○` (gray) - Disconnected -- `×` (red) - Error - -### Actions - -- `a` - Add new server -- `d` - Delete selected server (with confirmation) -- `Enter` - View server details - -## Add Server Dialog - -Press `a` to add a new server. - -``` -┌─ Add MCP Server ──────────────────────┐ -│ │ -│ Name: │ -│ ┌────────────────────────────────────┐ │ -│ │ my-server │ │ -│ └────────────────────────────────────┘ │ -│ │ -│ URL: │ -│ ┌────────────────────────────────────┐ │ -│ │ http://localhost:3000/mcp │ │ -│ └────────────────────────────────────┘ │ -│ │ -│ [Cancel] [Add] │ -└────────────────────────────────────────┘ -``` - -### Input Validation - -- **Name**: Must be unique, alphanumeric with hyphens/underscores -- **URL**: Must be valid HTTP/HTTPS URL - -### Keyboard Navigation - -- `Tab` - Move between fields -- `Enter` - Submit (when on Add button) -- `ESC` - Cancel - -## Help View - -Press `h` to view help and setup information. - -``` -┌─ Help & Setup Guide ──────────────────────────────┐ -│ │ -│ Keyboard Shortcuts: │ -│ / - Command Menu │ -│ v - View Activity Log │ -│ m - Manage Servers │ -│ a - Add New Server │ -│ c - Clear Activity Logs │ -│ h - Help │ -│ q - Quit │ -│ │ -│ Getting Started: │ -│ 1. Press 'a' to add your first MCP server │ -│ 2. Enter server name and URL │ -│ 3. Press 'v' to view activity │ -│ │ -│ Web UI: http://localhost:3333/ui │ -│ │ -│ Press ESC to close │ -└────────────────────────────────────────────────────┘ -``` - -## Terminal Compatibility - -### Recommended Terminals - -**macOS:** -- iTerm2 (recommended) -- Alacritty -- Terminal.app - -**Linux:** -- Alacritty (recommended) -- kitty -- gnome-terminal -- konsole - -**Windows:** -- Windows Terminal (recommended) -- Alacritty - -### Requirements - -- ANSI escape code support -- UTF-8 encoding -- Minimum 80x24 characters -- Recommended 120x30+ for best experience - -### Troubleshooting Display Issues - -**Garbled text or overlapping elements:** - -1. Ensure terminal supports ANSI codes -2. Try resizing the terminal window -3. Check UTF-8 encoding is enabled -4. Update terminal emulator to latest version - -**Colors not displaying:** - -1. Check terminal color support -2. Enable 256-color mode -3. Try a different terminal emulator - -## Tips and Tricks - -### Quick Navigation - -- Use `/` to quickly jump to any command -- Use `v` → `/` to filter logs without opening the menu - -### Multiple Windows - -Run multiple instances in different terminals: - -```bash -# Terminal 1 -mcp-gateway --port 3333 --storage-dir ~/.gateway-1 - -# Terminal 2 -mcp-gateway --port 3334 --storage-dir ~/.gateway-2 -``` - -### Background Mode - -Run TUI in one terminal, use another for work: - -```bash -# Terminal 1: Gateway TUI -mcp-gateway - -# Terminal 2: Development work -cd my-project && npm run dev -``` - -## Next Steps - -- [**Web Interface**](/mcp-gateway/features/web-interface) - Explore the Web UI -- [**CLI Options**](/mcp-gateway/features/cli-options) - Configure the gateway -- [**Activity Logging**](/mcp-gateway/core-concepts/activity-logging) - Understand logging diff --git a/src/content/docs/mcp-gateway/features/web-interface.md b/src/content/docs/mcp-gateway/features/web-interface.md deleted file mode 100644 index 8ae3246..0000000 --- a/src/content/docs/mcp-gateway/features/web-interface.md +++ /dev/null @@ -1,360 +0,0 @@ ---- -title: Web Interface -description: Browser-based UI for managing MCP Gateway ---- - -The Web UI provides a visual, browser-based interface for managing servers and inspecting activity logs. - -## Accessing the Web UI - -### Default URL - -``` -http://localhost:3333/ui -``` - -### Custom Port - -If running with `--port`: - -```bash -mcp-gateway --port 8080 -# Access at: http://localhost:8080/ui -``` - -### Opening Automatically - -```bash -# macOS -open http://localhost:3333/ui - -# Linux -xdg-open http://localhost:3333/ui - -# Windows -start http://localhost:3333/ui -``` - -## Dashboard - -The main dashboard provides an overview of your MCP infrastructure. - -### Server Cards - -Each server is displayed as a card showing: -- **Server name** -- **URL** -- **Status** (Connected/Disconnected/Error) -- **Recent activity count** -- **Last request time** - -### Quick Actions - -- **Add Server**: Click to add a new MCP server -- **Refresh**: Reload server status -- **Settings**: Configure gateway settings - -### Activity Summary - -View recent activity across all servers: -- Total requests in last hour -- Error rate -- Average response time -- Active servers count - -## Server Management - -### Adding a Server - -1. Click "Add Server" button -2. Fill in the form: - ``` - Name: [my-server] - URL: [http://localhost:3000/mcp] - ``` -3. Click "Add" -4. Server appears in the dashboard - -### Viewing Server Details - -Click on a server card to view: -- Full server configuration -- Connection status history -- Server-specific activity log -- Performance metrics - -### Editing a Server - -1. Click on a server card -2. Click "Edit" button -3. Update name or URL -4. Click "Save" - -### Removing a Server - -1. Click on a server card -2. Click "Remove Server" -3. Confirm deletion - -**Note**: Removing a server does not delete its logs. - -## Activity Log Browser - -The activity log browser provides powerful tools for inspecting captured traffic. - -### Accessing Logs - -**All Servers:** -- Click "Activity" in the main navigation -- View combined logs from all servers - -**Single Server:** -- Click on a server card -- View server-specific logs - -### Log Entry Display - -Each entry shows: -- **Timestamp** -- **Server name** -- **Method** (e.g., tools/list, query) -- **Duration** (in milliseconds) -- **Status** (Success/Error) - -### Filtering - -Use filters to narrow down logs: - -**By Time:** -- Last hour -- Last 24 hours -- Last 7 days -- Custom range - -**By Server:** -- Select one or more servers - -**By Method:** -- tools/list -- tools/call -- resources/list -- Custom method - -**By Status:** -- Success only -- Errors only -- All - -### Search - -Full-text search across: -- Request parameters -- Response data -- Error messages - -``` -Search: [create_issue] -``` - -### Viewing Details - -Click on any log entry to see: - -``` -┌─────────────────────────────────────┐ -│ Request Details │ -├─────────────────────────────────────┤ -│ Time: 2025-01-20 15:30:45 │ -│ Server: github-server │ -│ Method: tools/call │ -│ Duration: 89ms │ -│ Status: Success │ -│ │ -│ Request: │ -│ { │ -│ "name": "create_issue", │ -│ "arguments": { │ -│ "title": "Bug report", │ -│ "body": "Description..." │ -│ } │ -│ } │ -│ │ -│ Response: │ -│ { │ -│ "content": [ │ -│ { │ -│ "type": "text", │ -│ "text": "Issue created: #42" │ -│ } │ -│ ] │ -│ } │ -└─────────────────────────────────────┘ -``` - -### Exporting Logs - -Export filtered logs: - -1. Apply desired filters -2. Click "Export" -3. Choose format: - - JSON - - CSV - - JSON Lines - -## Performance Monitoring - -### Server Health - -View server health metrics: -- Uptime -- Request count -- Error rate -- Average response time - -### Request Timeline - -Visual timeline of requests: -- Scatter plot of request times -- Color-coded by status -- Hover for details - -### Response Time Distribution - -Histogram showing: -- Response time ranges -- Request count per bucket -- Percentiles (p50, p95, p99) - -## Settings - -### Gateway Configuration - -View and configure: -- Port number -- Storage directory -- Log retention settings - -### UI Preferences - -Customize the Web UI: -- Theme (Light/Dark/Auto) -- Refresh interval -- Items per page -- Timezone - -## Real-Time Updates - -The Web UI updates in real-time: -- New log entries appear automatically -- Server status changes reflect immediately -- Activity counts update live - -No manual refresh needed! - -## Browser Compatibility - -Supported browsers: -- **Chrome** 90+ -- **Firefox** 88+ -- **Safari** 14+ -- **Edge** 90+ - -Recommended: Latest version of Chrome or Firefox - -## Mobile Support - -The Web UI is responsive and works on mobile devices: -- Phones: Basic server management and log viewing -- Tablets: Full feature set - -Recommended for mobile: -- Use landscape orientation -- Minimum screen width: 375px - -## Tips and Tricks - -### Keyboard Shortcuts - -| Key | Action | -|-----|--------| -| `/` | Focus search | -| `r` | Refresh servers | -| `a` | Add server | -| `ESC` | Close modal | - -### Quick Filters - -Save frequently used filter combinations: - -1. Apply filters -2. Click "Save Filter" -3. Name your filter preset -4. Access from "Saved Filters" menu - -### Bookmarking - -Bookmark URLs with filters: - -``` -http://localhost:3333/ui/activity?server=github&status=error -``` - -Direct link to filtered view! - -### Multi-Tab Workflow - -Open multiple tabs: -- Tab 1: Dashboard (overview) -- Tab 2: Server A logs -- Tab 3: Server B logs - -All tabs update in real-time. - -## Development Mode - -When running the gateway with Vite dev server: - -```bash -# Terminal 1: Gateway -mcp-gateway - -# Terminal 2: Vite dev server -cd packages/web && npm run dev -``` - -Access at `http://localhost:5173` for hot reload during development. - -## Troubleshooting - -### Stale Data - -If the UI shows outdated information: - -1. Hard refresh: `Cmd+Shift+R` (macOS) or `Ctrl+Shift+R` (Windows/Linux) -2. Clear browser cache -3. Check gateway is running -4. Restart the gateway - -### UI Not Loading - -**Symptoms:** 404 error at `/ui` - -**Solutions:** -1. Verify gateway is running -2. Check the correct port -3. Ensure public folder exists (development builds) - -### Slow Performance - -If the UI is slow: -1. Reduce refresh interval in settings -2. Apply filters to reduce log count -3. Clear old logs -4. Check browser console for errors - -## Next Steps - -- [**Terminal UI**](/mcp-gateway/features/terminal-ui) - Learn keyboard shortcuts -- [**CLI Options**](/mcp-gateway/features/cli-options) - Configure the gateway -- [**Activity Logging**](/mcp-gateway/core-concepts/activity-logging) - Understand logging diff --git a/src/content/docs/mcp-gateway/getting-started.md b/src/content/docs/mcp-gateway/getting-started.md deleted file mode 100644 index 1bd61e2..0000000 --- a/src/content/docs/mcp-gateway/getting-started.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Getting Started -description: Install and set up MCP Gateway ---- - -Get up and running with MCP Gateway in minutes. - -## Installation - -### NPM - -```bash -npm install -g @fiberplane/mcp-gateway -``` - -### Bun - -```bash -bun add -g @fiberplane/mcp-gateway -``` - -### Platform Binaries - -Download platform-specific binaries from the [releases page](https://github.com/fiberplane/mcp-gateway/releases): - -- `mcp-gateway-darwin-arm64` - macOS Apple Silicon -- `mcp-gateway-darwin-x64` - macOS Intel -- `mcp-gateway-linux-x64` - Linux -- `mcp-gateway-windows-x64` - Windows - -## Quick Start - -### 1. Start the Gateway - -```bash -mcp-gateway -``` - -This starts the gateway with: -- **Terminal UI** in your current shell -- **API server** on port 3333 -- **Web UI** at `http://localhost:3333/ui` - -### 2. Add Your First MCP Server - -In the Terminal UI, press `a` to add a new server: - -``` -Name: my-server -URL: http://localhost:3000/mcp -``` - -Or use the Web UI at `http://localhost:3333/ui`. - -### 3. Test the Connection - -The gateway will automatically attempt to connect to your server. Check the status in: -- **TUI**: Press `m` to view server management -- **Web UI**: Navigate to the dashboard - -### 4. View Activity Logs - -See requests and responses in real-time: -- **TUI**: Press `v` to view activity log -- **Web UI**: Click on a server to see its logs - -## Basic Configuration - -### Custom Port - -```bash -mcp-gateway --port 8080 -``` - -### Custom Storage Directory - -```bash -mcp-gateway --storage-dir /custom/path -``` - -### Headless Mode - -Run without the Terminal UI (useful for Docker, systemd, or background processes): - -```bash -mcp-gateway --no-tui -``` - -Access the Web UI at `http://localhost:3333/ui` to manage servers. - -## Common Commands - -```bash -# Show help -mcp-gateway --help - -# Show version -mcp-gateway --version - -# Start with custom settings -mcp-gateway --port 8080 --storage-dir ~/.my-gateway -``` - -## Verifying Installation - -Check that the gateway is running: - -```bash -# Check API health -curl http://localhost:3333/api/health - -# Or visit in browser -open http://localhost:3333/ui -``` - -## Next Steps - -- [**Server Management**](/mcp-gateway/core-concepts/server-management) - Add and configure MCP servers -- [**Terminal UI**](/mcp-gateway/features/terminal-ui) - Learn keyboard shortcuts -- [**CLI Options**](/mcp-gateway/features/cli-options) - Explore all command-line options diff --git a/src/content/docs/mcp-gateway/getting-started.mdx b/src/content/docs/mcp-gateway/getting-started.mdx new file mode 100644 index 0000000..659715c --- /dev/null +++ b/src/content/docs/mcp-gateway/getting-started.mdx @@ -0,0 +1,74 @@ +--- +title: Getting Started +description: Install and set up MCP Gateway +--- + +import { Tabs, TabItem } from "@astrojs/starlight/components"; +import { Steps } from "@astrojs/starlight/components"; + +## Installation + +MCP Gateway is available for installation through JavaScript package managers such as npm, pnpm, or bun. + +{/* prettier-ignore */} + + + ```bash + npm install -g @fiberplane/mcp-gateway + ``` + + + ```bash + pnpm add -g @fiberplane/mcp-gateway + ``` + + + ```bash + bun add -g @fiberplane/mcp-gateway + ``` + + + +Alternatively, the mcp-gateway runs directly from its [repository](https://github.com/fiberplane/mcp-gateway) +More details [here](https://github.com/fiberplane/mcp-gateway?tab=readme-ov-file#alternatively-you-can-run-the-mcp-gateway-from-the-repo) + +### Quickstart + + + +1. **Start the Gateway**: + + ```bash + mcp-gateway + ``` + + - Web UI at `http://localhost:3333/ui` , using the authentication token provided in the terminal output + - API server at `http://localhost:3333/api` + +2. **Adding an MCP Server via the Web UI** + + - Go to **Manage Servers** in the right sidebar, then click **Add Server**. + ![Adding an MCP server via Web UI](/src/assets/adding-mcp-server.png) + + - Fill in the server details + ![Form to add an MCP server](/src/assets/add-mcp-server-form.png) + +3. **Connect MCP client** + + Connect the MCP client through the gateway. For example for Claude: + + ``` + claude mcp add --transport http "linear-mcp" \ + "http://localhost:3333/s/linear-mcp/mcp" + ``` + +4. **Viewing Activity Logs** + + View requests, responses, timing, and token usage in real-time via the Web UI + ![MCP server logs](/src/assets/mcp-server-logs.png) + + + +## Next Steps + +- [**Reference**](/mcp-gateway/reference#cli) - CLI, storage, API, and all technical details diff --git a/src/content/docs/mcp-gateway/index.md b/src/content/docs/mcp-gateway/index.md index 3c55023..dd90d34 100644 --- a/src/content/docs/mcp-gateway/index.md +++ b/src/content/docs/mcp-gateway/index.md @@ -3,94 +3,72 @@ title: Overview description: Unified gateway for managing and debugging MCP servers --- -MCP Gateway is a unified HTTP proxy for managing, routing, and debugging multiple Model Context Protocol servers with ease. +MCP Gateway is a unified HTTP proxy for managing, routing, and debugging multiple Model Context Protocol (MCP) servers. ## What is MCP Gateway? -MCP Gateway provides a local development tool that acts as a proxy between your AI applications and multiple MCP servers. It combines a **Terminal UI (TUI)** and **Web UI** to help you: +MCP Gateway is a local development tool that proxies communication between AI applications and multiple MCP servers. MCP Gateway runs from a terminal command and exposes a Web UI for managing and interacting with MCP servers. The gateway provides capabilities for: -- Manage multiple MCP servers from a single interface -- Inspect and debug request/response traffic -- Monitor server activity in real-time -- Store and replay captured logs - -## Key Features - -### Multi-Server Management -Add, configure, and monitor multiple MCP servers from one place. Switch between servers seamlessly and manage their lifecycle. - -### Activity Logging -Capture all requests and responses flowing through the gateway. Inspect detailed logs, filter by server or time, and debug issues faster. - -### Dual Interfaces -- **Terminal UI**: Keyboard-driven interface for power users -- **Web UI**: Browser-based dashboard for visual server management - -### Local Development -Run the gateway locally during development to test and debug MCP integrations before deploying to production. - -## Use Cases - -### Local MCP Development -Develop and test MCP servers locally with full request/response visibility. The gateway acts as an intermediary, logging all traffic for inspection. - -### Multi-Server Coordination -Route requests to different MCP servers based on your needs. Manage complex setups with multiple specialized servers. - -### Request Debugging -Inspect the exact requests sent to MCP servers and responses received. Identify issues quickly with detailed logging. - -### Activity Monitoring -Track server health, response times, and error rates. Monitor your MCP infrastructure in real-time. +- **Multi-server management** from a single interface +- **Activity logging** of all requests and responses +- **Real-time monitoring** via a Web UI +- **Traffic capture** stored in SQLite for inspection ## Architecture +The gateway operates in dual mode: it's both a proxy for MCP servers AND an MCP server itself. + +```text +┌───────────────────────────────────────────────────────────────┐ +│ MCP Gateway │ +│ │ +│ ┌─────────────┐ ┌──────────────┐ ┌───────────────────────┐ │ +│ │ Web UI │ │ Gateway MCP │ │ MCP Proxy Router │ │ +│ │ (React) │ │ Server │ │ (/s/{name}/mcp) │ │ +│ │ (/ui) │ │ (/gateway/ │ │ │ │ +│ │ │ │ mcp) │ │ - Traffic capture │ │ +│ └──────┬──────┘ │ │ │ - Request routing │ │ +│ │ │ Tools: │ └───────────┬───────────┘ │ +│ │ │ • add_server│ │ │ +│ │ │ • remove_ │ │ │ +│ │ │ server │ │ │ +│ │ │ • list_ │ │ │ +│ │ │ servers │ │ │ +│ │ │ • search_ │ │ │ +│ │ │ records │ │ │ +│ │ └──────┬───────┘ │ │ +│ └────────────────┼──────────────────────┘ │ +│ │ │ +│ ┌────────────────▼──────────────────┐ │ +│ │ REST API (/api) │ │ +│ │ (Powers Web UI) │ │ +│ └────────────────┬──────────────────┘ │ +│ │ │ +│ ┌────────────────▼──────────────────┐ │ +│ │ Storage & Log Management │ │ +│ │ (SQLite + mcp.json registry) │ │ +│ └────────────────┬──────────────────┘ │ +│ │ │ +└──────────────────────────┼────────────────────────────────────┘ + │ + ┌───────────┼───────────┐ + │ │ │ + ┌──────▼───┐ ┌────▼────┐ ┌───▼──────┐ + │ MCP │ │ MCP │ │ MCP │ + │ Server 1 │ │ Server 2│ │ Server N │ + └──────────┘ └─────────┘ └──────────┘ ``` -┌─────────────┐ -│ AI Client │ -└──────┬──────┘ - │ - ▼ -┌─────────────────┐ -│ MCP Gateway │ -│ ┌──────────┐ │ -│ │ TUI │ │ -│ └──────────┘ │ -│ ┌──────────┐ │ -│ │ Web UI │ │ -│ └──────────┘ │ -│ ┌──────────┐ │ -│ │ Proxy │ │ -│ └──────────┘ │ -│ ┌──────────┐ │ -│ │ Storage │ │ -│ └──────────┘ │ -└────┬────┬───┬───┘ - │ │ │ - ▼ ▼ ▼ - MCP MCP MCP - Server1 2 3 -``` - -## Quick Example -```bash -# Install MCP Gateway -npm install -g @fiberplane/mcp-gateway +## Endpoints -# Start the gateway -mcp-gateway - -# Add a server (in TUI, press 'a') -# Name: my-server -# URL: http://localhost:3000/mcp - -# Access Web UI -open http://localhost:3333/ui -``` +| Endpoint | Auth | Description | +| --------------------- | ------------- | ----------------------------- | +| `/ui?token=` | Token (query) | Web UI dashboard | +| `/api/*` | Bearer token | REST API | +| `/gateway/mcp` | Bearer token | Gateway MCP Server | +| `/s/{serverName}/mcp` | None | Proxy (upstream handles auth) | ## Next Steps - [**Getting Started**](/mcp-gateway/getting-started) - Install and configure MCP Gateway -- [**Server Management**](/mcp-gateway/core-concepts/server-management) - Learn to manage MCP servers -- [**Terminal UI**](/mcp-gateway/features/terminal-ui) - Master keyboard shortcuts and TUI features +- [**Reference**](/mcp-gateway/reference#cli) - CLI, storage, and API reference diff --git a/src/content/docs/mcp-gateway/reference.md b/src/content/docs/mcp-gateway/reference.md new file mode 100644 index 0000000..fe6f6e0 --- /dev/null +++ b/src/content/docs/mcp-gateway/reference.md @@ -0,0 +1,199 @@ +--- +title: Reference +description: technical references +--- + +## CLI + +```bash +mcp-gateway [options] +``` + +| Flag | Environment Variable | Default | Description | +| --------------- | ------------------------- | ---------------- | ----------------- | +| `--port` | `MCP_GATEWAY_PORT` | `3333` | HTTP server port | +| `--storage-dir` | `MCP_GATEWAY_STORAGE_DIR` | `~/.mcp-gateway` | Storage directory | +| N/A | `MCP_GATEWAY_TOKEN` | (auto-generated) | Auth token | +| `--help` | | | Show help | +| `--version` | | | Show version | + +```bash +# Examples +mcp-gateway --port 8080 +MCP_GATEWAY_TOKEN=my-secret-token mcp-gateway +DEBUG=* mcp-gateway # Enable debug logging +``` + +CLI flags override environment variables. + +## Authentication + +Bearer token required for `/ui/*`, `/api/*`, and `/gateway/mcp`. Proxy endpoints (`/s/{name}/mcp`) are unauthenticated—upstream handles its own auth. + +Token is auto-generated on startup (shown in terminal) or set via `MCP_GATEWAY_TOKEN`. + +```bash +# API authentication +curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3333/api/servers + +# Web UI (token in query string) +http://localhost:3333/ui?token=YOUR_TOKEN +``` + +## Proxy + +Route MCP clients through the gateway to capture traffic: + +```text +Direct: MCP Client → http://localhost:3001/mcp → MCP Server +Proxied: MCP Client → http://localhost:3333/s/my-server/mcp → Gateway → MCP Server + ↓ + SQLite Storage +``` + +Proxy URL pattern: `http://localhost:3333/s/{serverName}/mcp` + +Example (Claude Code): + +```bash +claude mcp add --transport http "my-server" \ + "http://localhost:3333/s/my-server/mcp" +``` + +Proxy endpoints do **not** require authentication—upstream servers handle their own auth. + +## Storage + +Files stored under `~/.mcp-gateway/`: + +```text +~/.mcp-gateway/ +├── mcp.json # Server registry +├── logs.db # SQLite traffic logs +└── logs.db-* # SQLite files +``` + +### Server Registry (mcp.json) + +HTTP server: + +```json +{ + "servers": [ + { + "name": "my-server", + "type": "http", + "url": "http://localhost:3000/mcp", + "enabled": true + } + ] +} +``` + +Stdio server: + +```json +{ + "servers": [ + { + "name": "memory", + "type": "stdio", + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "sessionMode": "shared", + "timeout": 30000 + } + ] +} +``` + +- `sessionMode`: `"shared"` (default) or `"isolated"` (per `x-session-id`) +- Stdio servers are long-lived; restart via UI/API + +## Web UI + +Access: `http://localhost:3333/ui?token=YOUR_TOKEN` + +### Features + +- **Activity Log** — view/filter captured MCP traffic +- **Server Management** — add, edit, remove servers +- **Health Status** — real-time health checks +- **Export** — download logs as JSONL + +Updates in real-time; no manual refresh needed. + +## REST API + +Base: `http://localhost:3333/api` + +All endpoints require Bearer token authentication. + +### GET /api/servers + +List registered servers with health status. + +```bash +curl -H "Authorization: Bearer TOKEN" http://localhost:3333/api/servers +``` + +### POST /api/servers + +Add a server. + +```bash +curl -X POST http://localhost:3333/api/servers \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer TOKEN" \ + -d '{"name": "my-server", "url": "http://localhost:3001/mcp"}' +``` + +With auth headers for upstream: + +```json +{ + "name": "private-api", + "url": "https://api.example.com/mcp", + "headers": { "Authorization": "Bearer SERVER_KEY" } +} +``` + +### GET /api/logs + +Query parameters: `serverName`, `sessionId`, `method`, `limit` (default 100), `before`, `after` + +```bash +curl -H "Authorization: Bearer TOKEN" \ + "http://localhost:3333/api/logs?serverName=my-server&limit=50" +``` + +### POST /api/logs/clear + +Clear logs. Optional: `?serverName=...` or `?before=2025-01-01T00:00:00Z` + +### GET /api/sessions + +List active sessions. + +### GET /api/clients + +List connected clients. + +### GET /api/health + +Health check. + +## Gateway MCP server + +Endpoint: `http://localhost:3333/gateway/mcp` (or `/g/mcp`) + +Requires Bearer token. Any MCP client can connect to manage the gateway programmatically. + +### Available Tools + +| Tool | Description | +| ---------------- | -------------------------------------------------------- | +| `add_server` | Add server (name, url, headers) | +| `remove_server` | Remove server by name | +| `list_servers` | List servers (filter: all/active/inactive) | +| `search_records` | Query logs (serverName, sessionId, method, limit, order) | diff --git a/src/content/docs/mcp-gateway/references/authentication.md b/src/content/docs/mcp-gateway/references/authentication.md new file mode 100644 index 0000000..2bf5e68 --- /dev/null +++ b/src/content/docs/mcp-gateway/references/authentication.md @@ -0,0 +1,16 @@ +--- +title: Authentication +description: Token-based security +--- + +Bearer token required for `/ui/*`, `/api/*`, and `/gateway/mcp`. Proxy endpoints (`/s/{name}/mcp`) are unauthenticated—upstream handles its own auth. + +Token is auto-generated on startup (shown in terminal) or set via `MCP_GATEWAY_TOKEN`. + +```bash +# API authentication +curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3333/api/servers + +# Web UI (token in query string) +http://localhost:3333/ui?token=YOUR_TOKEN +``` diff --git a/src/content/docs/mcp-gateway/references/cli.md b/src/content/docs/mcp-gateway/references/cli.md new file mode 100644 index 0000000..79fbf64 --- /dev/null +++ b/src/content/docs/mcp-gateway/references/cli.md @@ -0,0 +1,25 @@ +--- +title: CLI +description: Command-line options and environment variables +--- + +```bash +mcp-gateway [options] +``` + +| Flag | Environment Variable | Default | Description | +| --------------- | ------------------------- | ---------------- | ----------------- | +| `--port` | `MCP_GATEWAY_PORT` | `3333` | HTTP server port | +| `--storage-dir` | `MCP_GATEWAY_STORAGE_DIR` | `~/.mcp-gateway` | Storage directory | +| N/A | `MCP_GATEWAY_TOKEN` | (auto-generated) | Auth token | +| `--help` | | | Show help | +| `--version` | | | Show version | + +```bash +# Examples +mcp-gateway --port 8080 +MCP_GATEWAY_TOKEN=my-secret-token mcp-gateway +DEBUG=* mcp-gateway # Enable debug logging +``` + +CLI flags override environment variables. diff --git a/src/content/docs/mcp-gateway/references/gateway-mcp-server.md b/src/content/docs/mcp-gateway/references/gateway-mcp-server.md new file mode 100644 index 0000000..d78726d --- /dev/null +++ b/src/content/docs/mcp-gateway/references/gateway-mcp-server.md @@ -0,0 +1,17 @@ +--- +title: Gateway MCP Server +description: MCP tools for gateway control +--- + +Endpoint: `http://localhost:3333/gateway/mcp` (or `/g/mcp`) + +Requires Bearer token. Any MCP client can connect to manage the gateway programmatically. + +## Available Tools + +| Tool | Description | +| ---------------- | -------------------------------------------------------- | +| `add_server` | Add server (name, url, headers) | +| `remove_server` | Remove server by name | +| `list_servers` | List servers (filter: all/active/inactive) | +| `search_records` | Query logs (serverName, sessionId, method, limit, order) | diff --git a/src/content/docs/mcp-gateway/references/proxy.md b/src/content/docs/mcp-gateway/references/proxy.md new file mode 100644 index 0000000..dff911b --- /dev/null +++ b/src/content/docs/mcp-gateway/references/proxy.md @@ -0,0 +1,24 @@ +--- +title: Proxy +description: Routing MCP traffic through the gateway +--- + +Route MCP clients through the gateway to capture traffic: + +```text +Direct: MCP Client → http://localhost:3001/mcp → MCP Server +Proxied: MCP Client → http://localhost:3333/s/my-server/mcp → Gateway → MCP Server + ↓ + SQLite Storage +``` + +Proxy URL pattern: `http://localhost:3333/s/{serverName}/mcp` + +Example (Claude Code): + +```bash +claude mcp add --transport http "my-server" \ + "http://localhost:3333/s/my-server/mcp" +``` + +Proxy endpoints do **not** require authentication—upstream servers handle their own auth. diff --git a/src/content/docs/mcp-gateway/references/rest-api.md b/src/content/docs/mcp-gateway/references/rest-api.md new file mode 100644 index 0000000..3003d7c --- /dev/null +++ b/src/content/docs/mcp-gateway/references/rest-api.md @@ -0,0 +1,62 @@ +--- +title: REST API +description: HTTP API endpoints +--- + +Base: `http://localhost:3333/api` + +All endpoints require Bearer token authentication. + +## GET /api/servers + +List registered servers with health status. + +```bash +curl -H "Authorization: Bearer TOKEN" http://localhost:3333/api/servers +``` + +## POST /api/servers + +Add a server. + +```bash +curl -X POST http://localhost:3333/api/servers \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer TOKEN" \ + -d '{"name": "my-server", "url": "http://localhost:3001/mcp"}' +``` + +With auth headers for upstream: + +```json +{ + "name": "private-api", + "url": "https://api.example.com/mcp", + "headers": { "Authorization": "Bearer SERVER_KEY" } +} +``` + +## GET /api/logs + +Query parameters: `serverName`, `sessionId`, `method`, `limit` (default 100), `before`, `after` + +```bash +curl -H "Authorization: Bearer TOKEN" \ + "http://localhost:3333/api/logs?serverName=my-server&limit=50" +``` + +## POST /api/logs/clear + +Clear logs. Optional: `?serverName=...` or `?before=2025-01-01T00:00:00Z` + +## GET /api/sessions + +List active sessions. + +## GET /api/clients + +List connected clients. + +## GET /api/health + +Health check. diff --git a/src/content/docs/mcp-gateway/references/storage.md b/src/content/docs/mcp-gateway/references/storage.md new file mode 100644 index 0000000..097e1c3 --- /dev/null +++ b/src/content/docs/mcp-gateway/references/storage.md @@ -0,0 +1,50 @@ +--- +title: Storage +description: Data persistence and server registry format +--- + +Files stored under `~/.mcp-gateway/`: + +``` +~/.mcp-gateway/ +├── mcp.json # Server registry +├── logs.db # SQLite traffic logs +└── logs.db-* # SQLite files +``` + +## Server Registry (mcp.json) + +HTTP server: + +```json +{ + "servers": [ + { + "name": "my-server", + "type": "http", + "url": "http://localhost:3000/mcp", + "enabled": true + } + ] +} +``` + +Stdio server: + +```json +{ + "servers": [ + { + "name": "memory", + "type": "stdio", + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "sessionMode": "shared", + "timeout": 30000 + } + ] +} +``` + +- `sessionMode`: `"shared"` (default) or `"isolated"` (per `x-session-id`) +- Stdio servers are long-lived; restart via UI/API diff --git a/src/content/docs/mcp-gateway/references/web-ui.md b/src/content/docs/mcp-gateway/references/web-ui.md new file mode 100644 index 0000000..2b12d82 --- /dev/null +++ b/src/content/docs/mcp-gateway/references/web-ui.md @@ -0,0 +1,15 @@ +--- +title: Web UI +description: Browser-based dashboard +--- + +Access: `http://localhost:3333/ui?token=YOUR_TOKEN` + +## Features + +- **Activity Log** — view/filter captured MCP traffic +- **Server Management** — add, edit, remove servers +- **Health Status** — real-time health checks +- **Export** — download logs as JSONL + +Updates in real-time; no manual refresh needed. diff --git a/src/content/docs/mcp-gateway/troubleshooting.md b/src/content/docs/mcp-gateway/troubleshooting.md deleted file mode 100644 index f969de4..0000000 --- a/src/content/docs/mcp-gateway/troubleshooting.md +++ /dev/null @@ -1,469 +0,0 @@ ---- -title: Troubleshooting -description: Common issues and solutions ---- - -Solutions to common problems when using MCP Gateway. - -## Installation Issues - -### NPM Install Fails - -**Symptom:** `npm install -g @fiberplane/mcp-gateway` fails - -**Solutions:** -```bash -# Try with sudo (macOS/Linux) -sudo npm install -g @fiberplane/mcp-gateway - -# Or use npx (no install) -npx @fiberplane/mcp-gateway - -# Or use Bun instead -bun add -g @fiberplane/mcp-gateway -``` - -### Binary Not Found - -**Symptom:** `mcp-gateway: command not found` - -**Solutions:** -```bash -# Check npm global bin directory -npm config get prefix - -# Add to PATH (add to ~/.bashrc or ~/.zshrc) -export PATH="$PATH:$(npm config get prefix)/bin" - -# Or use npx -npx @fiberplane/mcp-gateway -``` - -## Startup Issues - -### Port Already in Use - -**Symptom:** `EADDRINUSE: address already in use :::3333` - -**Solutions:** -```bash -# Find process using port 3333 -lsof -i :3333 - -# Kill the process -kill -9 - -# Or use a different port -mcp-gateway --port 8080 -``` - -### Storage Directory Permission Denied - -**Symptom:** `EACCES: permission denied, mkdir '/var/lib/mcp-gateway'` - -**Solutions:** -```bash -# Create directory with proper permissions -sudo mkdir -p /var/lib/mcp-gateway -sudo chown $USER:$USER /var/lib/mcp-gateway - -# Or use user-writable directory -mcp-gateway --storage-dir ~/mcp-gateway -``` - -### Registry File Corrupted - -**Symptom:** `SyntaxError: Unexpected token in JSON` - -**Solutions:** -```bash -# Restore from backup -cp ~/.mcp-gateway/mcp.json.backup ~/.mcp-gateway/mcp.json - -# Or recreate empty registry -echo '{"version":"1.0","servers":[]}' > ~/.mcp-gateway/mcp.json - -# Restart gateway -mcp-gateway -``` - -## Connection Issues - -### Cannot Connect to MCP Server - -**Symptom:** "Failed to connect to server" in TUI/Web UI - -**Solutions:** - -1. **Verify server is running:** - ```bash - curl http://localhost:3000/mcp - ``` - -2. **Check server URL is correct:** - - Ensure protocol (http/https) - - Verify port number - - Check path (/mcp) - -3. **Test from gateway's perspective:** - ```bash - # From same machine as gateway - curl http://localhost:3000/mcp - ``` - -4. **Check for CORS issues:** - - MCP servers must allow gateway's origin - - Check server CORS configuration - -5. **Review server logs:** - - Look for connection errors - - Check for auth requirements - -### Server Shows Disconnected - -**Symptom:** Server status shows "Disconnected" in UI - -**Solutions:** - -1. **Check network connectivity:** - ```bash - ping - ``` - -2. **Verify server is still running:** - ```bash - curl - ``` - -3. **Check gateway logs:** - Press `v` in TUI or view Web UI logs for connection errors - -4. **Restart gateway:** - Sometimes a restart resolves transient issues - -### Timeout Errors - -**Symptom:** "Request timeout" errors - -**Solutions:** - -1. **Check server response time:** - ```bash - time curl http://localhost:3000/mcp - ``` - -2. **Increase timeout** (if configurable in future versions) - -3. **Check server performance:** - - High load? - - Resource constraints? - -## UI Issues - -### TUI Display Issues - -**Symptom:** Garbled text, overlapping elements, incorrect colors - -**Solutions:** - -1. **Check terminal compatibility:** - - Use iTerm2, Alacritty, or Windows Terminal - - Ensure ANSI escape code support - -2. **Resize terminal window:** - - Minimum 80x24 characters - - Recommended 120x30+ - -3. **Check UTF-8 encoding:** - ```bash - echo $LANG - # Should show UTF-8, e.g., en_US.UTF-8 - ``` - -4. **Try different terminal:** - ```bash - # macOS - open -a iTerm - - # Linux - alacritty - ``` - -5. **Update terminal emulator** to latest version - -### Web UI Shows 404 - -**Symptom:** Visiting `http://localhost:3333/ui` shows "404 Not Found" - -**Solutions:** - -1. **Verify gateway is running:** - ```bash - curl http://localhost:3333/api/health - ``` - -2. **Check correct port:** - ```bash - # If using custom port - curl http://localhost:8080/api/health - ``` - -3. **Rebuild Web UI** (development): - ```bash - cd packages/web - bun run build - cp -r public ../cli/public - ``` - -### Web UI Shows Stale Data - -**Symptom:** Web UI doesn't reflect recent changes - -**Solutions:** - -1. **Hard refresh browser:** - - macOS: `Cmd+Shift+R` - - Windows/Linux: `Ctrl+Shift+R` - -2. **Clear browser cache:** - - Chrome: Settings → Privacy → Clear browsing data - - Firefox: Preferences → Privacy → Clear Data - -3. **Check real-time updates:** - - Ensure WebSocket connection is active - - Check browser console for errors - -4. **Restart gateway:** - ```bash - # Stop and restart - mcp-gateway - ``` - -## Performance Issues - -### Slow Log Loading - -**Symptom:** Activity log takes long to load - -**Solutions:** - -1. **Apply filters to reduce data:** - - Filter by date range - - Filter by server - - Filter by method - -2. **Clean up old logs:** - ```bash - find ~/.mcp-gateway/captures -name "*.jsonl" -mtime +30 -delete - ``` - -3. **Check disk I/O:** - ```bash - iostat -x 1 - ``` - -4. **Move storage to faster disk** (SSD vs HDD) - -### High Memory Usage - -**Symptom:** Gateway consuming excessive RAM - -**Solutions:** - -1. **Check log buffer size:** - - Large buffers consume more memory - - Restart gateway to clear buffers - -2. **Reduce active servers:** - - Remove unused servers - - Distribute servers across multiple gateways - -3. **Monitor memory:** - ```bash - # macOS/Linux - ps aux | grep mcp-gateway - ``` - -### High CPU Usage - -**Symptom:** Gateway using high CPU - -**Solutions:** - -1. **Check request volume:** - - High traffic increases CPU usage - - Review server activity - -2. **Check for request loops:** - - Server calling itself via gateway? - - Review logs for patterns - -3. **Update to latest version:** - - Performance improvements in newer versions - -## Log Issues - -### Logs Not Being Captured - -**Symptom:** No log files in `~/.mcp-gateway/captures/` - -**Solutions:** - -1. **Check storage directory:** - ```bash - ls -la ~/.mcp-gateway/captures - ``` - -2. **Verify write permissions:** - ```bash - touch ~/.mcp-gateway/captures/test.txt - rm ~/.mcp-gateway/captures/test.txt - ``` - -3. **Check disk space:** - ```bash - df -h - ``` - -4. **Review gateway logs** for write errors - -### Corrupted Log Files - -**Symptom:** Cannot parse log files, invalid JSON - -**Solutions:** - -1. **Validate JSON Lines:** - ```bash - cat ~/.mcp-gateway/captures/server/2025-01-20.jsonl | jq '.' - ``` - -2. **Find corrupted lines:** - ```bash - cat file.jsonl | while read line; do - echo "$line" | jq '.' >/dev/null 2>&1 || echo "Bad: $line" - done - ``` - -3. **Remove corrupted entries:** - ```bash - # Backup first! - cp file.jsonl file.jsonl.backup - - # Filter valid JSON - cat file.jsonl | while read line; do - echo "$line" | jq '.' >/dev/null 2>&1 && echo "$line" - done > file.jsonl.clean - ``` - -## Server Management Issues - -### Cannot Add Server - -**Symptom:** Add server fails with validation error - -**Solutions:** - -1. **Check server name uniqueness:** - - Name must be unique across all servers - - Check `~/.mcp-gateway/mcp.json` for conflicts - -2. **Verify URL format:** - ``` - ✅ http://localhost:3000/mcp - ✅ https://api.example.com/mcp - ❌ localhost:3000 - ❌ http://localhost:3000 (missing /mcp path) - ``` - -3. **Check special characters:** - - Server name: alphanumeric, hyphens, underscores only - - No spaces, no special chars - -### Cannot Remove Server - -**Symptom:** Delete server fails or server reappears - -**Solutions:** - -1. **Manually edit registry:** - ```bash - nano ~/.mcp-gateway/mcp.json - # Remove server entry, save - ``` - -2. **Restart gateway:** - ```bash - mcp-gateway - ``` - -3. **Check file permissions:** - ```bash - ls -la ~/.mcp-gateway/mcp.json - chmod 644 ~/.mcp-gateway/mcp.json - ``` - -## Debug Techniques - -### Enable Debug Logging - -```bash -# Set DEBUG environment variable -DEBUG=* mcp-gateway -``` - -### Inspect Storage - -```bash -# View registry -cat ~/.mcp-gateway/mcp.json | jq '.' - -# List captures -ls -la ~/.mcp-gateway/captures/ - -# View recent logs -tail -f ~/.mcp-gateway/captures/my-server/$(date +%Y-%m-%d).jsonl -``` - -### Test MCP Server Connection - -```bash -# Test with curl -curl -X POST http://localhost:3000/mcp \ - -H "Content-Type: application/json" \ - -d '{"method":"tools/list","params":{}}' -``` - -### Check Gateway API - -```bash -# Health check -curl http://localhost:3333/api/health - -# List servers (if API supports) -curl http://localhost:3333/api/servers -``` - -## Getting Help - -If you've tried the above and still have issues: - -1. **Check GitHub Issues:** - https://github.com/fiberplane/mcp-gateway/issues - -2. **Create a Bug Report:** - - Include OS and version - - Gateway version (`mcp-gateway --version`) - - Steps to reproduce - - Error messages - - Relevant logs - -3. **Community Support:** - - Discussions tab on GitHub - - Fiberplane Discord/Slack - -## Next Steps - -- [**Development Debugging**](/mcp-gateway/development/debugging) - Advanced debugging -- [**CLI Options**](/mcp-gateway/features/cli-options) - Configuration options -- [**Storage & Registry**](/mcp-gateway/features/storage) - Understanding data storage diff --git a/src/content/docs/reference/example.md b/src/content/docs/reference/example.md deleted file mode 100644 index 1082841..0000000 --- a/src/content/docs/reference/example.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Example Reference -description: A reference page in my new Starlight docs site. ---- - -Reference pages are ideal for outlining how things work in terse and clear terms. -Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting. - -## Further reading - -- Read [about reference](https://diataxis.fr/reference) in the Diátaxis framework