Warp SQL Server MCP

# Debug Logging and Log Analysis This document describes the logging features and debugging tools available in the Warp SQL Server MCP. ## Configuration Summary The MCP server provides a comprehensive configuration summary at startup with emoji indicators: - 🌐 **Connection Settings**: Host, port, database, authentication type - 🔒 **Security & Operation Settings**: Password masking, security levels, permissions - ⚡ **Performance Monitoring**: Query tracking and optimization features - 📊 **Streaming Configuration**: Large dataset handling settings - 📝 **Logging & Output**: Log levels and output formatting ### Password Security For security, the `SQL_SERVER_PASSWORD` is fully masked in logs: - Shows `***********` (fixed-length masking) when a password is configured - Shows `<not set>` when using Windows Authentication or no password - Usernames are shown in cleartext for configuration verification ## Debug Mode Enable debug mode for enhanced logging: ```bash export SQL_SERVER_DEBUG=true ``` This enables: - Enhanced error logging and stack traces - Additional debug information in tool responses - More verbose connection and query logging ## Server Information and Diagnostics ### get_server_info MCP Tool The server includes a comprehensive diagnostics tool accessible through the MCP interface: ```json // MCP tool call { "name": "get_server_info", "arguments": { "include_logs": true // Optional: include logging context } } ``` This tool provides: - **Server Status**: Real-time information (name, version, uptime, platform, Node.js version) - **Configuration Overview**: Complete configuration summary including connection, security, performance, and logging settings - **Security Level Display**: Human-readable security levels ("MAXIMUM (Read-Only)", "MEDIUM (DML Allowed)", "MINIMAL (Full Access)") - **Runtime Statistics**: Performance metrics, connection health, memory usage, and process information - **Optional Log Context**: Recent logging information when requested **Perfect for:** - Troubleshooting configuration issues - Verifying server health and performance - Understanding current security settings - Debugging MCP connectivity problems ## Log Analysis Tools ### Smart Log Viewer (Recommended) The repository includes a comprehensive smart log viewer with automatic path detection: ```bash # Show all available commands npm run help # View recent server logs npm run logs # Follow logs in real-time npm run logs:tail # View security audit logs npm run logs:audit # Follow audit logs in real-time npm run logs:tail:audit # Direct script usage ./scripts/show-logs.sh --help ``` **Features:** - 🎯 **Smart path detection** (development vs production) - 📁 **Custom file path support** (--file or --path) - 📄 **Clean JSON formatting** with proper indentation - 🎨 **Color-coded log levels** and timestamps - ⚡ **Real-time log following** with `--follow` mode - 📊 **Multiple log types** (server and security audit) - 🔍 **Automatic log file discovery** **Custom File Path Support:** ```bash # View logs from any file path npm run logs -- --file /path/to/custom.log # Follow logs from a custom location npm run logs -- --file ~/my-logs/server.log --follow # Direct script usage ./scripts/show-logs.sh --path /var/log/my-app/server.log ``` This is especially useful for: - Viewing logs in non-standard locations - Examining archived log files - Debugging when log paths are customized - Analyzing logs from different environments **Smart Path Detection:** - **Development**: `./logs/server.log`, `./logs/security-audit.log` - **Production**: `~/.local/state/warp-sql-server-mcp/server.log`, `~/.local/state/warp-sql-server-mcp/security-audit.log` - **Windows**: `%LOCALAPPDATA%/warp-sql-server-mcp/server.log` ### Manual Log Analysis You can also manually analyze logs using standard tools: ```bash # View recent logs tail -f "/Users/$USER/Library/Application Support/dev.warp.Warp-Stable/mcp/[YOUR_MCP_ID].log" # Extract and pretty-print JSON responses grep "Received response" your-mcp.log | sed 's/.*{"result":/{"result":/' | jq . # Filter for errors only grep -E "(error|ERROR|Error)" your-mcp.log ``` ## Log Locations MCP logs are typically stored at: - **macOS**: `~/Library/Application Support/dev.warp.Warp-Stable/mcp/[MCP_ID].log` - **Windows**: `%APPDATA%\dev.warp.Warp-Stable\mcp\[MCP_ID].log` - **Linux**: `~/.local/share/dev.warp.Warp-Stable/mcp/[MCP_ID].log` ## Understanding Log Messages ### Startup Sequence 1. `Starting Warp SQL Server MCP server...` 2. Connection attempts with retry logic 3. Configuration summary display 4. `Warp SQL Server MCP server running on stdio` ### Connection Issues Look for: - `Connection attempt X failed:` - Individual retry failures - `Failed to connect to SQL Server after X attempts:` - Complete failure - Connection troubleshooting suggestions in configuration summary ### Tool Execution - MCP protocol messages show JSON-RPC requests/responses - SQL query execution results (formatted as JSON) - Safety policy violations and error messages ### Security Warnings - `WARNING: Read-write mode, DML allowed, DDL allowed` - Unsafe configuration - `Overall Security Level: ❌ UNSAFE` - Review security settings - Recommendations for production-safe configuration ## Troubleshooting Tips 1. **Get comprehensive help**: `npm run help` - See all available commands 2. **View recent activity**: `npm run logs` - Check recent server logs 3. **Monitor in real-time**: `npm run logs:tail` - Follow logs as issues occur 4. **Check security events**: `npm run logs:audit` - Review security audit logs 5. **Enable Debug Mode**: Set `SQL_SERVER_DEBUG=true` for detailed logs 6. **Check Connection Settings** in the configuration summary 7. **Verify Credentials** - look for authentication errors in logs 8. **Review Security Warnings** - ensure appropriate safety settings ## Example Log Analysis Workflow ```bash # 1. Get help and see all available commands npm run help # 2. Enable debug mode (if needed) export SQL_SERVER_DEBUG=true # 3. Check recent server activity npm run logs # 4. Monitor logs in real-time for troubleshooting npm run logs:tail # 5. Check security audit logs if needed npm run logs:audit # 6. Follow audit logs in real-time npm run logs:tail:audit # 7. Use compact mode for quick overview ./scripts/show-logs.sh --compact # 8. Get detailed help for the log viewer ./scripts/show-logs.sh --help ``` ### Quick Debugging Commands ```bash # View logs with different options npm run logs # Recent server logs (last 50 entries) npm run logs -- --all # All server log entries npm run logs -- --compact # Compact format without JSON details npm run logs:tail # Follow server logs in real-time npm run logs:audit -- --all # All security audit entries # Use custom file paths npm run logs -- --file /path/to/custom.log npm run logs -- --file ~/archived-logs/server-2025-01-01.log --all npm run logs -- --path /var/log/app/server.log --follow ```