0.4.2

Doris MCP Server v0.4.2 Release Notes

Release Date: 2025-07-02
Version: 0.4.2
Type: Major Feature & Stability Release

🎯 Overview

Doris MCP Server v0.4.2 is a comprehensive release that introduces significant enhancements focused on operational excellence, advanced monitoring capabilities, configuration standardization, and critical stability improvements. This release includes enhanced security features, MCP library compatibility resolution, and establishes a unified configuration framework for better maintainability and production reliability.

🚀 Major Features & Improvements

1. 🔧 MCP Version Compatibility Layer

The Problem:

• MCP 1.9.3 introduced breaking changes to the RequestContext class (changed from 2 to 3 generic parameters)
• Users encountered TypeError: Too few arguments for RequestContext when upgrading MCP library
• Version conflicts prevented server startup and caused deployment issues

The Solution:

• Intelligent Version Detection: Automatically detects installed MCP version at runtime
• Compatibility Abstraction: Gracefully handles API differences between MCP 1.8.x and 1.9.x
• Flexible Dependency Range: Updated to mcp>=1.8.0,<2.0.0 for broader compatibility

Technical Implementation:

# Added version compatibility layer in doris_mcp_server/main.py
def _get_mcp_capabilities(self):
    """Get MCP capabilities with version compatibility"""
    try:
        # For MCP 1.9.x and newer - handles 3-parameter RequestContext
        return self.server.get_capabilities(...)
    except TypeError:
        # For MCP 1.8.x - handles 2-parameter RequestContext  
        return self.server.get_capabilities(...)
    except Exception:
        # Fallback for any version compatibility issues
        return minimal_capabilities

Benefits:

• Zero Configuration: No manual adjustments needed for different MCP versions
• Future-Proof: Robust handling of potential future API changes
• Developer Friendly: Clear version logging for troubleshooting

Supported MCP Versions:

• MCP 1.8.x: Fully supported (recommended for stability)
• MCP 1.9.x: Fully supported (latest features)
• Future 1.x versions: Compatible through intelligent detection

2. 🛠️ Critical Connection Stability Resolution (at_eof Error Fix)

The Problem:

• Users experienced sudden at_eof connection errors during operation
• Database interactions would fail unexpectedly, requiring server restarts
• Connection pool became unstable under load

Root Cause Analysis:
The at_eof error was caused by aiomysql connection state checking issues when the connection's internal _reader object became None, but the ping check still attempted to access the at_eof attribute.

Comprehensive Solution:

A. Enhanced Connection Health Monitoring

# Added in doris_mcp_server/utils/db.py
async def ping(self):
    """Enhanced ping with connection state validation"""
    if not self._connection:
        return False
    
    # NEW: Strict connection state validation
    if hasattr(self._connection, '_reader') and self._connection._reader is None:
        return False
    if hasattr(self._connection, '_transport') and self._connection._transport is None:
        return False
        
    # Only check at_eof if connection components are valid
    if (hasattr(self._connection, '_reader') and 
        hasattr(self._connection._reader, 'at_eof')):
        return not self._connection._reader.at_eof()
    
    return True

B. Automatic Query Retry Mechanism

# Added in doris_mcp_server/utils/query_executor.py
async def execute_sql_for_mcp(self, sql: str, **kwargs):
    """Execute SQL with automatic retry for connection errors"""
    max_retries = 2
    
    for attempt in range(max_retries + 1):
        try:
            return await self._execute_sql_internal(sql, **kwargs)
        except Exception as e:
            if self._is_connection_error(e) and attempt < max_retries:
                logger.warning(f"Connection error detected, retrying... (attempt {attempt + 1})")
                await self._recover_connection()
                continue
            raise

Results:

• Zero at_eof errors in 50+ comprehensive test scenarios
• Automatic recovery from transient connection issues
• Improved stability under high concurrent load

3. 🔒 Unified Security Configuration Management

The Problem:
Security keywords were defined inconsistently across multiple locations:

• SecurityConfig: 9 keywords
• DorisSecurityManager._load_blocked_keywords(): 13 keywords
• SQLSecurityValidator.__init__(): 7 keywords

Solution: Single Source of Truth

A. Centralized Configuration

# doris_mcp_server/utils/config.py
@dataclass
class SecurityConfig:
    blocked_keywords: list[str] = field(
        default_factory=lambda: [
            # DDL Operations (Data Definition Language)
            "DROP", "CREATE", "ALTER", "TRUNCATE",
            # DML Operations (Data Manipulation Language) 
            "DELETE", "INSERT", "UPDATE",
            # DCL Operations (Data Control Language)
            "GRANT", "REVOKE",
            # System Operations
            "EXEC", "EXECUTE", "SHUTDOWN", "KILL",
        ]
    )

B. Environment Variable Support

# New environment variable configuration
ENABLE_SECURITY_CHECK=true
BLOCKED_KEYWORDS="DROP,DELETE,TRUNCATE,ALTER,CREATE,INSERT,UPDATE,GRANT,REVOKE,EXEC,EXECUTE,SHUTDOWN,KILL"

Benefits:

• Configuration Consistency: All components use the same keyword list
• Flexible Management: Easy customization through environment variables
• No Code Duplication: Single source eliminates maintenance overhead

4. 🛠️ Enhanced Monitoring Tools Module

Design Philosophy

The enhanced monitoring tools module follows a modular, extensible design pattern that emphasizes:

• Separation of Concerns: Each tool handles specific monitoring aspects
• Composability: Tools can be combined for comprehensive monitoring workflows
• Observability: Built-in monitoring and logging for all operations
• Resilience: Robust error handling and recovery mechanisms

Core Capabilities

A. Real-time Memory Monitoring

# Example: Real-time memory statistics via BE Memory Tracker
{
  "tool_name": "get_realtime_memory_stats",
  "capabilities": [
    "Process memory tracking",
    "Global shared memory monitoring", 
    "Query-specific memory usage",
    "Load operations memory tracking",
    "Compaction memory analysis"
  ]
}

B. Historical Memory Analytics

# Example: Historical memory statistics via BE Bvar interface
{
  "tool_name": "get_historical_memory_stats",
  "features": [
    "Time-series memory data collection",
    "Configurable time range analysis",
    "Memory usage trend identification",
    "Performance baseline establishment",
    "Capacity planning insights"
  ]
}

C. BE Node Discovery & Configuration
The monitoring tools support flexible BE (Backend) node discovery to accommodate different deployment scenarios:

External Network (Manual Configuration):

# Configure BE hosts manually for external network access
DORIS_BE_HOSTS=10.1.1.100,10.1.1.101,10.1.1.102
DORIS_BE_WEBSERVER_PORT=8040

Internal Network (Automatic Discovery):

# Leave BE_HOSTS empty for automatic discovery via SHOW BACKENDS
# DORIS_BE_HOSTS=  # Empty or not set
# System will execute: SHOW BACKENDS and use internal IPs

5. 🔍 Mature Query Information Tools

Enhanced SQL Explain with Content Analysis

# New Feature: Content-aware explain plans with file export capability
{
  "tool_name": "get_sql_explain",
  "enhancements": [
    "Configurable content truncation (MAX_RESPONSE_CONTENT_SIZE)",
    "LLM-friendly output formatting with file export for attachments",
    "Plan complexity scoring",
    "Optimization suggestion integration",
    "Historical plan comparison",
    "Direct file output for LLM analysis and SQL optimization workflows"
  ]
}

Advanced SQL Profiling

# New Feature: Comprehensive profiling with truncation and file export
{
  "tool_name": "get_sql_profile", 
  "capabilities": [
    "Real-time performance tracking",
    "Resource usage breakdown",
    "Bottleneck identification",
    "Content size management with configurable truncation",
    "Performance trend analysis",
    "Complete profile file generation for LLM attachment analysis",
    "SQL optimization workflow integration with file export"
  ]
}

LLM Integration & File Export Capabilities

Both SQL Explain and Profile tools are designed for seamless LLM integration workflows:

Dual Output Strategy:

# Each tool provides both truncated content and complete file output
response = {
  "content": "Truncated content for immediate LLM analysis (4096 chars)",
  "file_path": "/tmp/explain_12345.txt",  # Complete file for attachment
  "is_content_truncated": true,
  "original_content_size": 156552
}

6. ⚙️ Unified Configuration Framework

Configuration Standardization

All configuration parameters have been consolidated into a unified framework:

A. Central Configuration Management

• Single Source of Truth: All settings managed through doris_mcp_server/utils/config.py
• Environment Integration: Seamless .env file and environment variable support
• Validation Framework: Comprehensive configuration validation with clear error messages

B. Configuration Categories

# Unified configuration structure
DorisConfig:
├── DatabaseConfig          # Database connection settings
├── SecurityConfig          # Authentication and authorization
├── PerformanceConfig       # Query execution and caching
├── LoggingConfig          # Logging and audit settings
├── MonitoringConfig       # Metrics and health checks
└── OperationalConfig      # Operational tools settings

7. 🗃️ Smart Default Database Handling

Problem Resolution:

• Previous Issue: Server required explicit database configuration during startup
• Solution: Implemented intelligent default database selection with automatic fallback to information_schema

Graceful Fallback Mechanism:

# Enhanced startup sequence
1. Check user-specified database
2. Fallback to information_schema (universal availability)
3. Validate database accessibility
4. Log selected database for transparency
5. Continue with service initialization

🐛 Bug Fixes

• MCP-001: Fixed TypeError: Too few arguments for RequestContext in MCP 1.9.3
• MCP-002: Resolved server startup failures with mixed MCP versions
• MCP-003: Fixed capabilities negotiation errors across MCP versions
• DB-001: Fixed at_eof connection errors with enhanced connection state validation
• DB-002: Resolved connection pool instability under concurrent load
• Security-001: Fixed inconsistent blocked keywords across security components
• Security-002: Resolved security validation bypass in certain edge cases
• Config-001: Fixed inconsistent parameter naming across configuration modules
• Config-002: Resolved circular dependency in configuration loading
• Tools-001: Removed race condition in experimental tool cleanup

🔄 Migration Guide

From v0.3.x to v0.4.2

Simple Upgrade:
Most users can upgrade without any configuration changes:

pip install --upgrade doris-mcp-server==0.4.2

For Users with MCP Version Issues:

# If you previously had MCP version conflicts
pip uninstall mcp
pip install --upgrade doris-mcp-server==0.4.2
# MCP will be automatically installed with compatible version

Configuration Updates:

# Update your .env file with new standardized variables
# Add new security settings (optional)
ENABLE_SECURITY_CHECK=true
BLOCKED_KEYWORDS="DROP,DELETE,TRUNCATE,ALTER,CREATE,INSERT,UPDATE,GRANT,REVOKE,EXEC,EXECUTE,SHUTDOWN,KILL"

# Add new operational tool settings (optional)
MAX_RESPONSE_CONTENT_SIZE=4096

Tool Usage Updates:

# Replace experimental tools (if you were using them)
# OLD: column_analysis
# NEW: get_realtime_memory_stats + get_monitoring_metrics_data

# OLD: performance_stats  
# NEW: get_historical_memory_stats + get_monitoring_metrics_info

Version Verification:

# Check MCP version compatibility
doris-mcp-server --transport stdio
# Look for log message: "Using MCP version: x.x.x"

🗑️ Removed Experimental Tools

Removed Tools:

• column_analysis
• performance_stats

Rationale:
The experimental tools have been completely replaced by better-designed, production-ready alternatives that offer:

• Enhanced performance and reliability
• Better error handling and monitoring
• Unified API design patterns
• Comprehensive documentation and examples

🔧 Technical Improvements

Performance Enhancements

• Content Truncation: Configurable response size limits for LLM compatibility
• Query Optimization: Enhanced caching mechanisms for operational tools
• Memory Management: Improved resource utilization in monitoring tools
• Connection Stability: Zero-downtime connection recovery and retry mechanisms

Reliability Improvements

• Error Handling: Comprehensive error recovery in operational tools
• Connection Management: Enhanced database connection pooling with proactive cleanup
• Graceful Degradation: Service continues operation even with partial failures
• Version Compatibility: Intelligent MCP library version detection and adaptation

Developer Experience

• Unified APIs: Consistent interface patterns across all tools
• Enhanced Documentation: Comprehensive examples and usage guides
• Configuration Validation: Clear error messages for misconfigurations
• Version Logging: Clear visibility into MCP library versions being used

⚠️ Breaking Changes

1. Removed Tools: column_analysis and performance_stats are no longer available
2. Configuration Structure: Some configuration parameters have been renamed for consistency
3. Default Database: Service now defaults to information_schema instead of requiring explicit configuration

Continuous Improvements (Ongoing)

• Performance Optimization: Ongoing enhancements to query execution speed and resource utilization
• Security Hardening: Regular updates to security features and vulnerability assessments
• Documentation: Expanded examples, tutorials, and best practices guides
• Community Features: Enhanced community tools and integration examples

📞 Support & Resources

• Documentation: README.md
• Configuration Reference: doris_mcp_server/utils/config.py
• Issue Reporting: GitHub Issues
• Community: GitHub Discussions

👥 Contributors

Special thanks to all contributors who made v0.4.0 possible through code contributions, testing, and feedback.