Enhanced Dash MCP Server

# Enhanced Dash MCP: Automation Detection & Non-Interactive Operation ## Overview The Enhanced Dash MCP server features sophisticated automation detection logic that enables seamless operation in CI/CD pipelines, containerized environments, and automated deployment scenarios. This document provides comprehensive details on the detection mechanisms, behavior patterns, and debugging approaches for developers and system administrators. ## 🔍 Interactive Mode Detection Algorithm The server employs an 8-phase detection sequence to determine the execution environment and adapt its behavior accordingly. Each phase is logged with detailed reasoning to aid in debugging and verification. ### Phase 1: CI Environment Detection **Purpose**: Detect continuous integration and build automation systems **Environment Variables Checked** (26 variables): #### Primary CI Indicators - `CI` - Generic CI indicator used by most platforms - `CONTINUOUS_INTEGRATION` - Alternative generic CI marker - `BUILD_ID` - Generic build identifier - `BUILD_NUMBER` - Generic build sequence number #### Platform-Specific CI Variables - `GITHUB_ACTIONS` - GitHub Actions workflows - `GITLAB_CI` - GitLab CI/CD pipelines - `JENKINS_URL` - Jenkins build server - `TRAVIS` - Travis CI builds - `CIRCLECI` - Circle CI workflows - `BUILDKITE` - Buildkite pipelines - `DRONE` - Drone CI systems - `BITBUCKET_BUILD_NUMBER` - Bitbucket Pipelines - `AZURE_HTTP_USER_AGENT` - Azure DevOps - `CODEBUILD_BUILD_ID` - AWS CodeBuild - `TEAMCITY_VERSION` - TeamCity builds - `BAMBOO_BUILD_NUMBER` - Atlassian Bamboo - `TF_BUILD` - Team Foundation Server - `APPVEYOR` - AppVeyor CI - `WERCKER` - Wercker builds - `CONCOURSE` - Concourse CI - `SEMAPHORE` - Semaphore CI - `HUDSON_URL` - Hudson CI (Jenkins predecessor) **Detection Logic**: ```python for env_var in ci_env_vars: env_value = os.getenv(env_var) if env_value: logger.info(f"❌ Non-interactive mode detected: CI environment variable '{env_var}' is set to '{env_value}'") logger.debug(f" └─ Detection reason: CI systems set this variable to indicate automated builds") return False ``` **Example Log Output**: ``` INFO: ❌ Non-interactive mode detected: CI environment variable 'GITHUB_ACTIONS' is set to 'true' DEBUG: └─ Detection reason: CI systems set this variable to indicate automated builds ``` ### Phase 2: Automation Environment Detection **Purpose**: Identify automated processing, batch jobs, and containerized environments **Environment Variables Checked** (20 variables): #### Generic Automation Indicators - `AUTOMATION` - Generic automation flag - `AUTOMATED` - Alternative automation marker - `NON_INTERACTIVE` - Explicit non-interactive mode - `BATCH_MODE` - Batch processing indicator - `HEADLESS` - Headless environment marker - `CRON` - Cron job execution #### Container and Cloud Platforms - `SYSTEMD_EXEC_PID` - systemd service execution - `KUBERNETES_SERVICE_HOST` - Kubernetes pod environment - `DOCKER_CONTAINER` - Docker container indicator - `CONTAINER` - Generic container environment - `AWS_EXECUTION_ENV` - AWS Lambda/container environment - `LAMBDA_RUNTIME_DIR` - AWS Lambda function - `GOOGLE_CLOUD_PROJECT` - Google Cloud environment - `AZURE_FUNCTIONS_ENVIRONMENT` - Azure Functions - `HEROKU_APP_ID` - Heroku dyno - `RAILWAY_ENVIRONMENT` - Railway deployment - `VERCEL` - Vercel deployment - `NETLIFY` - Netlify build environment - `CF_PAGES` - Cloudflare Pages **Detection Logic**: ```python for env_var in automation_env_vars: env_value = os.getenv(env_var) if env_value: logger.info(f"❌ Non-interactive mode detected: Automation environment variable '{env_var}' is set to '{env_value}'") logger.debug(f" └─ Detection reason: Indicates automated or batch processing environment") return False ``` ### Phase 3: Terminal Environment Validation **Purpose**: Verify terminal capabilities and type **Terminal Types Rejected**: - `dumb` - Basic terminal without advanced features - `unknown` - Unrecognized terminal type - Empty string - No terminal type specified **Detection Logic**: ```python term = os.getenv('TERM', '').lower() if term in ['dumb', 'unknown', '']: logger.info(f"❌ Non-interactive mode detected: TERM environment variable is '{term}'") logger.debug(f" └─ Detection reason: Terminal type indicates no interactive capabilities") return False ``` ### Phase 4: Shell Environment Analysis **Purpose**: Validate shell type and interactive capabilities **Non-Interactive Shells Detected**: - Shells containing `/nologin` - Explicitly disabled interactive login - Shells containing `/false` - False shell (no interaction) **Detection Logic**: ```python shell = os.getenv('SHELL', '').lower() if '/nologin' in shell or '/false' in shell: logger.info(f"❌ Non-interactive mode detected: Non-interactive shell '{shell}'") logger.debug(f" └─ Detection reason: Shell configured to prevent interactive login") return False ``` ### Phase 5: TTY Stream Detection **Purpose**: Verify standard streams are connected to terminals **Streams Tested**: - **STDIN** (`sys.stdin.isatty()`) - Input stream - **STDOUT** (`sys.stdout.isatty()`) - Output stream - **STDERR** (`sys.stderr.isatty()`) - Error stream **Detection Logic**: ```python # Check each stream individually if not sys.stdin.isatty(): logger.info("❌ Non-interactive mode detected: STDIN is not a TTY (piped/redirected input)") logger.debug(" └─ Detection reason: Input stream is redirected from file or pipe") return False if not sys.stdout.isatty(): logger.info("❌ Non-interactive mode detected: STDOUT is not a TTY (piped/redirected output)") logger.debug(" └─ Detection reason: Output stream is redirected to file or pipe") return False if not sys.stderr.isatty(): logger.info("❌ Non-interactive mode detected: STDERR is not a TTY (piped/redirected error output)") logger.debug(" └─ Detection reason: Error stream is redirected to file or pipe") return False ``` ### Phase 6: Process Environment Analysis **Purpose**: Detect daemon processes and background execution **Process Characteristics Analyzed**: - **nohup execution** - Process started with nohup (no hangup signal) - **Daemon characteristics** - Session leader without controlling terminal - **Orphaned processes** - Parent process is init (PID 1) **Detection Logic**: ```python # Check for nohup execution if os.getenv('NOHUP'): logger.info("❌ Non-interactive mode detected: Running under nohup") logger.debug(" └─ Detection reason: Process started with nohup (no hangup signal handling)") return False # Check for daemon process characteristics if os.getpgrp() == os.getpid() and not os.isatty(0): logger.info("❌ Non-interactive mode detected: Running as daemon (no controlling terminal)") logger.debug(" └─ Detection reason: Process is session leader without controlling terminal") return False # Check for orphaned process if os.getppid() == 1: logger.info("❌ Non-interactive mode detected: Parent process is init (orphaned process)") logger.debug(" └─ Detection reason: Process has been orphaned and adopted by init") return False ``` ### Phase 7: SSH Connection Analysis **Purpose**: Validate remote connections and TTY allocation **SSH Environment Variables**: - `SSH_CONNECTION` - SSH connection details - `SSH_TTY` - TTY allocated for SSH session **Detection Logic**: ```python ssh_connection = os.getenv('SSH_CONNECTION') ssh_tty = os.getenv('SSH_TTY') if ssh_connection: if not ssh_tty: logger.info("❌ Non-interactive mode detected: SSH connection without TTY allocation") logger.debug(f" └─ Detection reason: SSH_CONNECTION='{ssh_connection}' but SSH_TTY not set") return False else: logger.debug(f"✅ Phase 7 passed: SSH connection with TTY allocation (SSH_TTY='{ssh_tty}')") else: logger.debug("✅ Phase 7 passed: Not an SSH connection") ``` ### Phase 8: Session Environment Analysis **Purpose**: Recognize terminal multiplexer sessions **Session Managers Supported**: - **GNU Screen** - `STY` environment variable - **tmux** - `TMUX` environment variable **Detection Logic**: ```python screen_session = os.getenv('STY') tmux_session = os.getenv('TMUX') if screen_session: logger.debug(f"✅ Phase 8a: Running in GNU Screen session (STY='{screen_session}')") logger.debug(" └─ Screen sessions maintain interactive capabilities") elif tmux_session: logger.debug(f"✅ Phase 8b: Running in tmux session (TMUX='{tmux_session}')") logger.debug(" └─ Tmux sessions maintain interactive capabilities") else: logger.debug("✅ Phase 8c: Not running in a terminal multiplexer") ``` ## 🎯 Behavior Adaptation by Environment ### GitHub Actions **Detection**: `GITHUB_ACTIONS=true` **Behavior**: - Silent operation with INFO-level logging - No user prompts or interactive input - Automatic default selection for all choices - Comprehensive error reporting for workflow debugging ### GitLab CI **Detection**: `GITLAB_CI=true` **Behavior**: - Silent operation optimized for GitLab runners - Pipeline-friendly exit codes - Structured logging for GitLab CI log parsing - No terminal color codes in output ### Docker Containers **Detection**: `CONTAINER=true` or non-TTY streams **Behavior**: - Container-aware resource usage - Layer-friendly installation patterns - Minimal output for build log optimization - Cache-conscious operation ### Kubernetes Pods **Detection**: `KUBERNETES_SERVICE_HOST` present **Behavior**: - Pod lifecycle-aware operation - Service discovery integration - Health check endpoints - Graceful shutdown handling ### AWS Lambda **Detection**: `LAMBDA_RUNTIME_DIR` present **Behavior**: - Serverless-optimized initialization - Cold start minimization - Memory-efficient operation - DEBUG-level logging for CloudWatch ### Cron Jobs **Detection**: Non-TTY streams with minimal environment **Behavior**: - Silent operation with comprehensive logging - Email-friendly error reporting - Minimal resource usage - Proper exit code handling ### SSH Scripts **Detection**: `SSH_CONNECTION` without `SSH_TTY` **Behavior**: - Network-aware timeouts - Connection failure resilience - Secure operation patterns - Remote execution optimization ## 🔧 Configuration Options ### Environment Variable Overrides ```bash # Force interactive mode (for testing) export FORCE_INTERACTIVE=true # Override automatic detection export DASH_MCP_MODE=interactive # or 'automation' # Enable detailed process debugging export DASH_MCP_DEBUG_PROCESS=true # Set custom log level export DASH_MCP_LOG_LEVEL=DEBUG # or INFO, WARNING, ERROR # Custom log file location export DASH_MCP_LOG_FILE=/custom/path/server.log ``` ### Startup Modes ```bash # Test mode - validates setup without starting server python3 enhanced_dash_server.py --test # Normal mode - runs server with stdio streams python3 enhanced_dash_server.py # CI mode (forced via environment) CI=true python3 enhanced_dash_server.py --test ``` ## 📊 Performance Characteristics ### Detection Performance - **Environment Variable Check**: <1ms per variable - **TTY Status Check**: <5ms per stream - **Process Information**: <10ms - **Total Detection Time**: <50ms ### Automation vs Interactive Performance | Operation | Interactive Mode | Automation Mode | Difference | |-----------|------------------|-----------------|------------| | Startup Time | 200-300ms | 150-200ms | 25% faster | | Log Volume | DEBUG level | INFO level | 80% reduction | | Memory Usage | Full caching | Minimal caching | 40% reduction | | Error Detail | Interactive prompts | Structured logs | N/A | ## 🛠️ Debugging Automation Detection ### Enable Detailed Logging ```bash # Maximum verbosity export DASH_MCP_LOG_LEVEL=DEBUG python3 enhanced_dash_server.py --test # View detection phase logs grep "Phase [1-8]" ~/.cache/dash-mcp/server.log # View detection decisions grep "Detection reason" ~/.cache/dash-mcp/server.log # View environment summary grep "Environment summary" ~/.cache/dash-mcp/server.log ``` ### Common Debugging Scenarios #### "Server detected as non-interactive but should be interactive" ```bash # Check environment variables env | grep -E "(CI|AUTOMATION|BATCH|HEADLESS|CONTAINER)" # Check TTY status python3 -c "import sys; print(f'stdin: {sys.stdin.isatty()}, stdout: {sys.stdout.isatty()}, stderr: {sys.stderr.isatty()}')" # Check terminal type echo "TERM='$TERM'" # Force interactive mode for testing FORCE_INTERACTIVE=true python3 enhanced_dash_server.py --test ``` #### "Server should be non-interactive but appears interactive" ```bash # Set explicit automation mode CLI=true python3 enhanced_dash_server.py --test # Check for missing environment variables echo "Missing CI variable - consider setting CI=true" # Verify stream redirection echo "test" | python3 enhanced_dash_server.py --test ``` ### Log Analysis Patterns #### Successful Interactive Detection ``` DEBUG: 🔍 Starting interactive mode detection sequence... DEBUG: ✅ Phase 1 passed: No CI environment variables detected DEBUG: ✅ Phase 2 passed: No automation environment variables detected ... INFO: 🎉 Interactive mode confirmed: All detection phases passed ``` #### CI Environment Detection ``` DEBUG: 🔍 Starting interactive mode detection sequence... DEBUG: 📋 Phase 1: Checking CI environment variables INFO: ❌ Non-interactive mode detected: CI environment variable 'CI' is set to 'true' DEBUG: └─ Detection reason: CI systems set this variable to indicate automated builds ``` #### Container Environment Detection ``` DEBUG: 🔍 Starting interactive mode detection sequence... DEBUG: 🤖 Phase 2: Checking automation environment variables INFO: ❌ Non-interactive mode detected: Automation environment variable 'CONTAINER' is set to 'true' DEBUG: └─ Detection reason: Indicates automated or batch processing environment ``` ## 🧪 Testing Automation Detection ### Unit Test Examples ```python def test_ci_detection(): """Test CI environment detection""" with mock.patch.dict(os.environ, {'CI': 'true'}, clear=True): assert not is_interactive_mode() def test_container_detection(): """Test container environment detection""" with mock.patch.dict(os.environ, {'CONTAINER': 'true'}, clear=True): assert not is_interactive_mode() def test_tty_detection(): """Test TTY stream detection""" with mock.patch('sys.stdin.isatty', return_value=False): assert not is_interactive_mode() ``` ### Integration Test Scripts ```bash # Test CI simulation CI=true ./test-ci-automation.sh # Test clean environment env -i PATH=/usr/bin:/bin HOME=$HOME CI=true ./scripts/setup-dash-mcp.sh # Test input redirection echo "" | ./scripts/setup-dash-mcp.sh # Test timeout mechanisms timeout 5s ./scripts/setup-dash-mcp.sh ``` ## 📈 Monitoring and Metrics ### Key Metrics to Monitor - **Detection Accuracy**: Percentage of correct environment classifications - **False Positives**: Interactive environments detected as automation - **False Negatives**: Automation environments detected as interactive - **Performance Impact**: Time spent on detection vs core functionality ### Log Aggregation Patterns ```bash # Count detection outcomes grep -c "Interactive mode confirmed" ~/.cache/dash-mcp/server.log grep -c "Non-interactive mode detected" ~/.cache/dash-mcp/server.log # Analyze detection triggers grep "Detection reason:" ~/.cache/dash-mcp/server.log | sort | uniq -c # Performance monitoring grep "detection sequence" ~/.cache/dash-mcp/server.log | grep -o "[0-9.]*ms" ``` ## 🔮 Future Enhancements ### Planned Detection Improvements 1. **Machine Learning Detection**: Learn from environment patterns 2. **Custom Detection Rules**: User-configurable detection logic 3. **Environment Profiles**: Predefined configurations for common setups 4. **Runtime Mode Switching**: Dynamic mode changes based on usage patterns ### Proposed Environment Variables ```bash # Future configuration options DASH_MCP_DETECTION_STRICT=true # Require explicit mode setting DASH_MCP_DETECTION_TIMEOUT=30 # Detection timeout in seconds DASH_MCP_DETECTION_PROFILE=docker # Use predefined detection profile DASH_MCP_DETECTION_RULES=/path/to/custom/rules.yaml # Custom detection rules ``` --- **For questions or issues with automation detection, please check the logs first, then open a GitHub issue with the relevant log entries and environment details.**