Oracle Database MCP Server

# Winston to Lightweight Logger Migration - Summary ## Overview Successfully replaced Winston logging library with a custom, dependency-free logging solution for the MCP Oracle Database server. ## Motivation - **Reduce dependencies**: Remove 20+ transitive dependencies from Winston - **Improve security**: Minimize attack surface by using only Node.js built-ins - **Maintain simplicity**: Keep the codebase lean and maintainable - **Preserve functionality**: Maintain all existing logging capabilities ## Changes Made ### 1. New Logger Implementation **File**: `src/utils/logger.ts` Features: - Zero external dependencies (uses fs, path, url from Node.js) - Console logging with ANSI color codes - Optional file logging with daily rotation - Log levels: info, warn, error, debug - Audit logging support - Production-safe (debug suppressed in production) - Proper JSON object serialization ### 2. Removed Files - `src/logging/logger.ts` - Old Winston-based logger ### 3. Updated Files All files with logger imports updated to use new logger: - `src/server.ts` - `src/database/oracleConnection.ts` - `src/database/queryExecutor.ts` - `src/tools/queryDatabase.ts` - `src/tools/getSchema.ts` Configuration updates: - `package.json` - Winston dependency removed - `tsconfig.json` - Added Node.js types - `.env.example` - Added new logging environment variables - `README.md` - Updated logging configuration ### 4. New Documentation - `docs/LOGGING.md` - Comprehensive logging guide - `test-logger.mjs` - Integration test suite ### 5. New Environment Variables ```env ENABLE_FILE_LOGGING=true # Enable/disable file logging LOG_DIR=./logs # Directory for log files NODE_ENV=development # Environment mode (affects debug logs) ENABLE_AUDIT_LOGGING=true # Enable/disable audit logs ``` ## Dependencies Removed Before: ```json "dependencies": { "@modelcontextprotocol/sdk": "^1.20.2", "zod": "^3.25.76", "oracledb": "^6.4.0", "dotenv": "^16.3.1", "winston": "^3.11.0" // ← Removed } ``` After: ```json "dependencies": { "@modelcontextprotocol/sdk": "^1.20.2", "dotenv": "^16.3.1", "oracledb": "^6.4.0", "zod": "^3.25.76" } ``` Winston brought 20+ transitive dependencies. All removed. ## Log File Format ### Daily Rotation Log files are created daily with format: `app-YYYY-MM-DD.log` Example: ``` logs/ app-2025-10-24.log app-2025-10-25.log app-2025-10-26.log ``` ### Log Entry Format ``` 2025-10-26T10:30:00.123Z INFO: Server started {"port":3000} 2025-10-26T10:30:05.456Z WARN: Connection pool nearly full {"current":9,"max":10} 2025-10-26T10:30:10.789Z ERROR: Query failed {"error":"Connection timeout"} 2025-10-26T10:30:15.012Z DEBUG: Query executed {"rows":100,"time":45} ``` ## API Compatibility The new logger maintains backward compatibility with the old Winston-based API: ```typescript // Old (Winston) import logger from './logging/logger.js'; logger.info('message', { meta: 'data' }); logger.warn('warning'); logger.error('error', { details: 'info' }); // New (Lightweight) import logger from './utils/logger.js'; logger.info('message', { meta: 'data' }); // ✅ Same API logger.warn('warning'); // ✅ Same API logger.error('error', { details: 'info' }); // ✅ Same API ``` Audit logging also preserved: ```typescript import { audit } from './utils/logger.js'; audit('Event description', { metadata: 'value' }); ``` ## Testing All integration tests pass: - ✅ Basic logging (info, warn, error, debug) - ✅ Object serialization to JSON - ✅ Audit logging - ✅ File logging with daily rotation - ✅ Production mode (debug suppression) - ✅ Timestamp and log level validation ## Security - ✅ CodeQL scan: 0 vulnerabilities - ✅ No external dependencies to audit - ✅ Uses only Node.js built-in modules - ✅ No file path traversal vulnerabilities - ✅ Safe file operations with error handling ## Performance Benefits: - Fewer dependencies = faster npm install - No dependency vulnerabilities to monitor - Smaller bundle size - Direct file I/O (no abstraction layers) Trade-offs: - No advanced features (log rotation by size, network transports, etc.) - Manual log cleanup required (no automatic old log removal) - Single-process focused (no built-in multi-process support) ## Migration Guide For developers updating from Winston: 1. **Imports**: Change import path only ```diff - import logger from './logging/logger.js'; + import logger from './utils/logger.js'; ``` 2. **Environment**: Add new variables to `.env` ```env ENABLE_FILE_LOGGING=true LOG_DIR=./logs NODE_ENV=development ``` 3. **No code changes needed**: The API is compatible ## Maintenance ### Log Cleanup Old logs must be cleaned up manually or via external tools: ```bash # Delete logs older than 30 days find ./logs -name "app-*.log" -mtime +30 -delete # Compress logs older than 7 days find ./logs -name "app-*.log" -mtime +7 -exec gzip {} \; ``` ### Future Enhancements Potential improvements if needed: - Add log rotation by file size - Add compression for old logs - Add network log shipping - Add structured logging formats (JSON) - Add log levels filtering ## Conclusion ✅ **Mission accomplished**: Winston completely removed ✅ **Zero regressions**: All functionality preserved ✅ **Improved security**: Fewer dependencies, smaller attack surface ✅ **Simpler codebase**: One file, zero dependencies ✅ **Well tested**: Comprehensive integration tests ✅ **Well documented**: Complete logging guide The MCP Oracle Database server now has a lightweight, secure, and maintainable logging solution.