@standardbeagle/mcp-tui 0.5.0 → 0.7.0

package/README.md

@@ -111,7 +111,7 @@ mcp-tui  # Connects automatically!
 
 **🤖 Building Automation? Use CLI Mode:**
 ```bash
-# List all available tools via STDIO (combined command input) 
+# List all available tools via STDIO (combined command input)
 mcp-tui "npx -y @modelcontextprotocol/server-everything stdio" tool list
 
 # Or via SSE
@@ -121,10 +121,21 @@ mcp-tui --url http://localhost:8000/sse tool list
 mcp-tui --url http://localhost:8000/sse tool call echo message="Hello World"
 
 # Get JSON output for your scripts
-mcp-tui --json --url http://localhost:8000/sse tool list
+mcp-tui --url http://localhost:8000/sse tool list -f json
 ```
 *Why this works: Combined command input, perfect for CI/CD, scripts, and automated testing workflows*
 
+**🧪 Writing Tests? Use Porcelain Mode:**
+```bash
+# Porcelain mode gives clean output for test assertions
+mcp-tui --porcelain "npx -y @modelcontextprotocol/server-everything stdio" tool call echo message="test"
+
+# Combine with JSON for predictable parsing
+result=$(mcp-tui --porcelain -f json tool call weather location="NYC")
+temp=$(echo "$result" | jq -r '.temp')
+```
+*Why this works: No progress messages, only result data on stdout, detailed errors on stderr*
+
 **🌐 Have a Web Service? Connect via HTTP:**
 ```bash
 # Visual interface for web-based MCP servers
@@ -312,6 +323,47 @@ make test-servers
 ./mcp-tui --cmd node --args "test-servers/crash-server.js" tool list
 ```
 
+### Testing with Porcelain Mode
+
+For automated testing and CI/CD pipelines, use `--porcelain` mode to get clean, parseable output:
+
+```bash
+# Test that a tool returns expected result
+result=$(mcp-tui --porcelain "npx -y @modelcontextprotocol/server-everything stdio" tool call echo message="test")
+if [[ "$result" == *"test"* ]]; then
+    echo "PASS: echo tool returned expected message"
+else
+    echo "FAIL: unexpected result: $result"
+    exit 1
+fi
+
+# Parse JSON output for assertions
+result=$(mcp-tui --porcelain -f json "npx -y @modelcontextprotocol/server-everything stdio" tool call weather location="NYC")
+temp=$(echo "$result" | jq -r '.temp')
+if [[ "$temp" =~ ^[0-9]+ ]]; then
+    echo "PASS: temperature is numeric: $temp"
+else
+    echo "FAIL: invalid temperature: $temp"
+    exit 1
+fi
+
+# Count tools in CI/CD
+tool_count=$(mcp-tui --porcelain -f json tool list | jq '.count')
+if [ "$tool_count" -gt 0 ]; then
+    echo "PASS: server exposes $tool_count tools"
+else
+    echo "FAIL: no tools available"
+    exit 1
+fi
+```
+
+**Porcelain Mode Benefits:**
+- ✅ No progress messages or timestamps
+- ✅ Predictable output for assertions
+- ✅ Clean stdout with only result data
+- ✅ Detailed errors on stderr for debugging
+- ✅ Perfect for CI/CD pipelines and automated tests
+
 ## 📋 Commands Reference
 
 ### Command Line Arguments
@@ -352,16 +404,15 @@ mcp-tui prompt get <name> [args...]    # Get a prompt with arguments
 
 ### Global Options
 ```bash
---url string         # URL for SSE servers (primary method)
---type string        # Transport type (currently: sse)
---timeout duration   # Connection timeout (default 30s)
+--url string         # URL for SSE/HTTP servers
+--cmd string         # Command to run MCP server (STDIO mode)
+--args strings       # Arguments for server command
+--transport string   # Transport type (stdio, sse, http, streamable-http)
+--timeout duration   # Connection timeout (default 10s)
+--format string      # Output format: text or json (short: -f) (default "text")
+--porcelain          # Machine-readable output (no progress messages)
 --debug             # Enable debug mode with detailed logging
 --log-level string  # Log level (debug, info, warn, error)
---json              # Output results in JSON format
-
-# Legacy options (STDIO support coming back soon):
---cmd string         # Command to run MCP server (not yet implemented)
---args strings       # Arguments for server command (not yet implemented)
 ```
 
 ## 🔍 Error Handling & Debugging

package/examples/CONFIG_REFERENCE.md

@@ -0,0 +1,363 @@
+# MCP Configuration Reference
+
+This document provides a comprehensive reference for MCP configuration patterns, including examples from various MCP clients and servers.
+
+## Table of Contents
+- [Configuration Formats](#configuration-formats)
+- [MCP-TUI Configuration](#mcp-tui-configuration)
+- [Claude Desktop Configuration](#claude-desktop-configuration)
+- [Transport Types](#transport-types)
+- [Common Patterns](#common-patterns)
+
+## Configuration Formats
+
+MCP configurations can be written in JSON or YAML format. The examples in this directory demonstrate both.
+
+### File Locations
+
+MCP-TUI searches for configuration files in this order:
+
+1. **Command-line specified**: `--config path/to/config.json`
+2. **Project-local**: `.mcp.json`, `.claude.json` in current directory
+3. **User config**: `~/.config/mcp-tui/connections.json` (saved connections format)
+4. **Claude Desktop**: 
+   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+   - Linux: `~/.config/Claude/claude_desktop_config.json`
+5. **VS Code workspace**: `.vscode/mcp.json`
+
+## MCP-TUI Configuration
+
+MCP-TUI supports two configuration approaches:
+
+1. **Unified Configuration**: Comprehensive structure for advanced features
+2. **Saved Connections**: Simplified format for managing multiple servers
+
+### Saved Connections Format (Recommended)
+
+The saved connections format provides an intuitive way to manage multiple MCP servers with features like auto-connect, recent connections, and visual organization:
+
+```json
+{
+  "version": "1.0",
+  "defaultServer": "filesystem",
+  "servers": {
+    "filesystem": {
+      "id": "filesystem",
+      "name": "Local Filesystem",
+      "description": "Access local files and directories",
+      "icon": "📁",
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
+      "success": false,
+      "tags": ["local", "files"],
+      "lastUsed": "2025-01-12T10:30:00Z"
+    }
+  },
+  "recentConnections": [
+    {
+      "serverId": "filesystem",
+      "lastUsed": "2025-01-12T10:30:00Z",
+      "success": true
+    }
+  ]
+}
+```
+
+Key features:
+- **Auto-connect**: Set `defaultServer` or configure single server for automatic connection
+- **Visual organization**: Icons, names, descriptions, and tags for easy identification
+- **Recent connections**: Tracks usage history and success status
+- **Environment variables**: Supports `${env:VAR_NAME}` substitution
+
+### Unified Configuration
+
+MCP-TUI uses a comprehensive configuration structure that supports multiple aspects of MCP client behavior.
+
+### Basic Structure
+
+```json
+{
+  "connection": {
+    "type": "stdio|sse|http|streamable-http",
+    "command": "command-to-execute",
+    "args": ["arg1", "arg2"],
+    "url": "http://server-url",
+    "headers": {"Header": "Value"}
+  },
+  "transport": {
+    "http": { /* HTTP-specific settings */ },
+    "stdio": { /* STDIO-specific settings */ },
+    "sse": { /* SSE-specific settings */ }
+  },
+  "session": { /* Session management settings */ },
+  "error_handling": { /* Error handling configuration */ },
+  "debug": { /* Debug and logging settings */ },
+  "cli": { /* CLI-specific settings */ }
+}
+```
+
+### Complete Example
+
+See `mcp-config.json` and `mcp-config.yaml` for complete configuration examples.
+
+## Claude Desktop Configuration
+
+Claude Desktop uses a simpler configuration format focused on server definitions.
+
+### Structure
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "executable",
+      "args": ["arg1", "arg2"],
+      "env": {
+        "ENV_VAR": "value"
+      }
+    }
+  }
+}
+```
+
+### Multiple Servers Example
+
+See `claude-desktop-config.json` for an example with multiple server configurations.
+
+## Transport Types
+
+### STDIO Transport
+
+Most common for local MCP servers. The server communicates via standard input/output.
+
+```json
+{
+  "type": "stdio",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
+}
+```
+
+### HTTP Transport
+
+For REST API-style MCP servers with request/response pattern.
+
+```json
+{
+  "type": "http",
+  "url": "http://localhost:8080/mcp",
+  "headers": {
+    "Authorization": "Bearer token"
+  }
+}
+```
+
+### SSE Transport
+
+For servers using Server-Sent Events for real-time communication.
+
+```json
+{
+  "type": "sse",
+  "url": "http://localhost:3000/sse",
+  "headers": {
+    "X-API-Key": "api-key"
+  }
+}
+```
+
+### Streamable HTTP Transport
+
+For servers supporting streaming HTTP responses.
+
+```json
+{
+  "type": "streamable-http",
+  "url": "http://localhost:8080/mcp/stream"
+}
+```
+
+## Common Patterns
+
+### Environment Variable Substitution
+
+Many configurations support environment variable substitution using `${VAR_NAME}` syntax:
+
+```json
+{
+  "headers": {
+    "Authorization": "Bearer ${API_TOKEN}",
+    "X-API-Key": "${API_KEY}"
+  }
+}
+```
+
+### Timeout Configuration
+
+Standard timeout values in Go duration format:
+- `30s` - 30 seconds
+- `5m` - 5 minutes
+- `1h30m` - 1 hour 30 minutes
+
+### Security Settings
+
+```json
+{
+  "connection": {
+    "deny_unsafe_commands": true,
+    "allowed_commands": ["npx", "node", "python"]
+  },
+  "transport": {
+    "http": {
+      "tls_min_version": "1.2",
+      "tls_insecure_skip_verify": false
+    }
+  }
+}
+```
+
+### Debug Configuration
+
+```json
+{
+  "debug": {
+    "enabled": true,
+    "log_level": "debug",
+    "http_debugging": true,
+    "event_tracing": true
+  }
+}
+```
+
+## Server-Specific Examples
+
+### Official MCP Servers
+
+1. **Everything Server** (test server with all capabilities):
+   ```json
+   {
+     "command": "npx",
+     "args": ["-y", "@modelcontextprotocol/server-everything", "stdio"]
+   }
+   ```
+
+2. **Filesystem Server**:
+   ```json
+   {
+     "command": "npx",
+     "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path1", "/path2"]
+   }
+   ```
+
+3. **SQLite Server**:
+   ```json
+   {
+     "command": "npx",
+     "args": ["mcp-server-sqlite", "--db-path", "/path/to/database.db"]
+   }
+   ```
+
+### Custom Servers
+
+1. **Python Server**:
+   ```json
+   {
+     "command": "python",
+     "args": ["server.py", "--port", "3000"],
+     "env": {
+       "PYTHONPATH": "/path/to/modules"
+     }
+   }
+   ```
+
+2. **Node.js Server**:
+   ```json
+   {
+     "command": "node",
+     "args": ["dist/index.js"],
+     "env": {
+       "NODE_ENV": "production"
+     }
+   }
+   ```
+
+3. **Docker Container**:
+   ```json
+   {
+     "command": "docker",
+     "args": ["run", "-i", "--rm", "my-mcp-server:latest"]
+   }
+   ```
+
+## Best Practices
+
+1. **Use absolute paths** for file references and commands when possible
+2. **Set appropriate timeouts** based on your server's response times
+3. **Enable debug logging** during development
+4. **Use environment variables** for sensitive data like API keys
+5. **Validate commands** with `deny_unsafe_commands: true` for security
+6. **Configure health checks** for production deployments
+7. **Set up proper error handling** with retry logic for network transports
+
+## Validation
+
+MCP-TUI includes configuration validation. Common validation rules:
+
+- Transport type must be one of: `stdio`, `sse`, `http`, `streamable-http`
+- Timeouts must be positive durations
+- Buffer sizes must be at least 1024 bytes
+- Log levels must be one of: `debug`, `info`, `warn`, `error`
+- Backoff strategies must be one of: `none`, `linear`, `exponential`
+
+## Migration from Other Clients
+
+### From Claude Desktop to MCP-TUI
+
+Claude Desktop configuration:
+```json
+{
+  "mcpServers": {
+    "myserver": {
+      "command": "node",
+      "args": ["server.js"]
+    }
+  }
+}
+```
+
+Equivalent MCP-TUI configuration:
+```json
+{
+  "connection": {
+    "type": "stdio",
+    "command": "node",
+    "args": ["server.js"]
+  }
+}
+```
+
+## Example Files in This Directory
+
+### Saved Connections Format
+- `single-server-config.json` - Simple auto-connect setup
+- `development-preset.json` - Common development tools
+- `multi-transport-config.json` - All transport types with saved connections
+- `production-setup.json` - Production environment configuration
+
+### Unified Configuration Format
+- `mcp-config.json` - Basic MCP-TUI configuration
+- `mcp-config.yaml` - Same configuration in YAML format
+- `multi-server-config.json` - Multiple servers with different transports
+- `transport-examples.json` - Examples for each transport type
+
+### Compatibility Formats
+- `claude-desktop-config.json` - Claude Desktop multi-server example
+
+### Quick Start
+
+1. **Copy a preset**: Use `development-preset.json` as a starting point
+2. **Auto-connect setup**: Copy `single-server-config.json` for immediate connection
+3. **Multi-environment**: Use `production-setup.json` for complex setups
+4. **All features**: Check `multi-transport-config.json` for comprehensive example

package/examples/claude-desktop-config.json

@@ -0,0 +1,66 @@
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/Users/username/Desktop",
+        "/Users/username/Downloads"
+      ]
+    },
+    "weather": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/path/to/weather",
+        "run",
+        "weather.py"
+      ]
+    },
+    "github": {
+      "command": "node",
+      "args": [
+        "/path/to/github/dist/index.js"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_pat_here"
+      }
+    },
+    "sqlite": {
+      "command": "npx",
+      "args": [
+        "mcp-server-sqlite",
+        "--db-path",
+        "/path/to/database.db"
+      ]
+    },
+    "puppeteer": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-puppeteer"
+      ]
+    },
+    "postgres": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-postgres",
+        "postgresql://localhost/mydb"
+      ]
+    },
+    "custom-local": {
+      "command": "python",
+      "args": [
+        "/path/to/custom/server.py",
+        "--port",
+        "3000"
+      ],
+      "env": {
+        "API_KEY": "your-api-key",
+        "DEBUG": "true"
+      }
+    }
+  }
+}

package/examples/development-preset.json

@@ -0,0 +1,50 @@
+{
+  "version": "1.0",
+  "defaultServer": "everything",
+  "servers": {
+    "everything": {
+      "id": "everything",
+      "name": "Everything Server",
+      "description": "Official MCP server with all features for testing",
+      "icon": "🌟",
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-everything", "stdio"],
+      "success": false,
+      "tags": ["testing", "development"]
+    },
+    "filesystem-home": {
+      "id": "filesystem-home",
+      "name": "Home Directory",
+      "description": "Access your home directory files",
+      "icon": "🏠",
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~"],
+      "success": false,
+      "tags": ["filesystem", "home"]
+    },
+    "filesystem-workspace": {
+      "id": "filesystem-workspace",
+      "name": "Workspace Files",
+      "description": "Access current workspace directory",
+      "icon": "💼",
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
+      "success": false,
+      "tags": ["filesystem", "workspace"]
+    },
+    "sqlite-local": {
+      "id": "sqlite-local",
+      "name": "Local SQLite DB",
+      "description": "Local SQLite database access",
+      "icon": "🗄️",
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sqlite", "./database.db"],
+      "success": false,
+      "tags": ["database", "sqlite"]
+    }
+  }
+}

package/examples/mcp-config.json

@@ -0,0 +1,83 @@
+{
+  "connection": {
+    "type": "stdio",
+    "command": "npx",
+    "args": [
+      "-y",
+      "@modelcontextprotocol/server-everything",
+      "stdio"
+    ],
+    "connection_timeout": "30s",
+    "request_timeout": "30s",
+    "health_check_timeout": "5s",
+    "deny_unsafe_commands": true
+  },
+  "transport": {
+    "http": {
+      "timeout": "30s",
+      "max_idle_conns": 100,
+      "max_idle_conns_per_host": 10,
+      "idle_conn_timeout": "90s",
+      "tls_min_version": "1.2",
+      "user_agent": "mcp-tui/0.1.0"
+    },
+    "stdio": {
+      "command_validation": true,
+      "max_processes": 10,
+      "process_timeout": "300s",
+      "kill_timeout": "10s"
+    },
+    "sse": {
+      "reconnect_interval": "5s",
+      "max_reconnect_attempts": 5,
+      "buffer_size": 8192,
+      "read_timeout": "30s",
+      "write_timeout": "10s"
+    }
+  },
+  "session": {
+    "health_check_interval": "30s",
+    "health_check_timeout": "5s",
+    "max_reconnect_attempts": 3,
+    "reconnect_delay": "2s",
+    "reconnect_backoff": "exponential",
+    "max_reconnect_delay": "60s",
+    "enable_persistence": false,
+    "persistence_interval": "60s"
+  },
+  "error_handling": {
+    "enable_classification": true,
+    "user_friendly_messages": true,
+    "max_error_history": 1000,
+    "error_reporting": false,
+    "enable_retry": true,
+    "max_retry_attempts": 3,
+    "retry_delay": "1s",
+    "retry_backoff": "exponential"
+  },
+  "debug": {
+    "enabled": false,
+    "log_level": "info",
+    "event_tracing": false,
+    "max_traced_events": 1000,
+    "http_debugging": false,
+    "http_trace_body": false,
+    "http_trace_headers": false,
+    "pretty_print": true,
+    "colored_output": true,
+    "timestamp_format": "2006-01-02T15:04:05Z07:00",
+    "export_events": false,
+    "export_format": "json"
+  },
+  "cli": {
+    "output_format": "table",
+    "quiet_mode": false,
+    "verbose_mode": false,
+    "no_color": false,
+    "show_progress": true,
+    "progress_style": "bar",
+    "enable_clipboard": true,
+    "enable_paging": true,
+    "page_size": 25
+  }
+}