JaggerITA/unified-mcp-server

Unified MCP Server

A comprehensive Model Context Protocol (MCP) server that provides multiple tools for system administration, file processing, and OBIEE query management. This unified server combines WSL utilities with specialized OBIEE accent removal capabilities.

🚀 Features

📂 OBIEE Query Processing

• Batch Processing: Process all query files in a directory at once
• Single File Processing: Process individual query files as needed
• Accent Removal: Uses Unicode normalization (NFD) for reliable accent removal
• SQL Extension: Forces .sql extension on all output files
• Comprehensive Logging: Detailed logs for every processed file
• Backup Management: Automatic backup of original files

🖥️ WSL System Utilities

• Command Execution: Run WSL system commands safely
• File Management: List and manage directory contents
• System Information: Display detailed system information

📊 Logging & Tracking

• Change Logs: Detailed logs showing exactly what was modified
• Timestamp Tracking: All operations are timestamped
• File Statistics: Size comparisons and change counts

📋 Requirements

• Python 3.8 or higher
• MCP framework (mcp>=1.0.0)

🛠️ Installation

1. Clone the repository:

   git clone https://github.com/JaggerITA/mcp-server.git
   cd mcp-server
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Install in development mode (optional):

   pip install -e .
   

📁 Project Structure

mcp-server/
├── main.py                   # Main MCP server entry point
├── src/
│   ├── __init__.py
│   └── accent_remover.py     # Core accent removal logic
├── tests/
│   ├── __init__.py
│   └── test_accent_remover.py # Unit tests
├── examples/
│   └── sample_query.txt      # Sample OBIEE query
├── original/                 # Input directory for query files
├── generated/                # Output directory for processed files (.sql)
├── backup/                   # Backup directory for original files
├── logs/                     # Processing logs directory
├── docs/                     # Documentation
├── requirements.txt
├── pyproject.toml
└── README.md

🎯 Usage

Running the MCP Server

python main.py

Available MCP Tools

The server provides the following tools:

1. remove_accents_from_queries

Processes all files in the original/ directory, removes accents, saves results to generated/ with .sql extension, and moves originals to backup/.

Parameters:

• original_folder (optional): Source directory path (default: ./original)
• generated_folder (optional): Output directory path (default: ./generated)
• backup_folder (optional): Backup directory path (default: ./backup)
• file_pattern (optional): File pattern to match (default: *.txt)

2. process_single_query

Processes a single query file.

Parameters:

• input_file (required): Path to the input query file
• output_file (required): Path where the processed file should be saved (will be forced to .sql)
• backup_folder (optional): Backup directory path (default: ./backup)

3. WSL System Tools

• run_command: Execute WSL system commands
• list_files: List files in a directory
• system_info: Display system information

File Processing Workflow

1. 📁 Input: Files are read from original/ directory
2. 🔄 Process: Accents are removed using Unicode normalization
3. 💾 Save: Results saved to generated/ with .sql extension
4. 📝 Log: Detailed processing log created in generated/logs/
5. 📦 Backup: Original file moved to backup/ directory
6. 🧹 Clean: Original directory is cleaned

🔄 Accent Transformations

The tool handles common Italian accented characters:

📝 Example

Input Query (original/sample.txt):

SELECT
   0 s_0,
   "EDW"."Anagrafica Dipendente"."Età" s_1,
   "EDW"."Anagrafica Dipendente"."Società matricola" s_2,
   "EDW"."Fact - Anagrafica Dipendente"."Età" s_3
FROM "EDW"
ORDER BY 2 ASC NULLS LAST

Output Query (generated/sample.sql):

SELECT
   0 s_0,
   "EDW"."Anagrafica Dipendente"."Eta" s_1,
   "EDW"."Anagrafica Dipendente"."Societa matricola" s_2,
   "EDW"."Fact - Anagrafica Dipendente"."Eta" s_3
FROM "EDW"
ORDER BY 2 ASC NULLS LAST

Generated Log (generated/logs/sample_20241227_143022.log):

Processing Log - 2024-12-27 14:30:22
Input File: /path/to/original/sample.txt
Output File: /path/to/generated/sample.sql
Changes: Removed accents from sample.txt: 'Età' → 'Eta', 'Società' → 'Societa'
Original Size: 234 chars
Processed Size: 230 chars

🧪 Testing

Run the test suite:

# Run all tests
python -m pytest tests/

# Run with coverage
python -m pytest tests/ --cov=src

# Run specific test
python -m pytest tests/test_accent_remover.py::TestAccentRemover::test_remove_accents_basic

🔧 Development

Setting up development environment:

# Install development dependencies
pip install -e ".[dev]"

# Run code formatting
black src/ tests/
isort src/ tests/

# Run linting
flake8 src/ tests/

Adding new functionality:

1. Add core logic to src/ modules
2. Expose via MCP tools in main.py
3. Add tests to tests/
4. Update documentation

🐛 Troubleshooting

Common Issues:

1. File encoding errors: Ensure all files are saved with UTF-8 encoding
2. Permission errors: Check file/directory permissions
3. MCP connection issues: Verify the server is running and accessible
4. Missing logs: Check that generated/logs/ directory has write permissions

Debugging:

# Test accent removal directly
python -c "from src.accent_remover import remove_accents; print(remove_accents('Età'))"

# Check server startup
python main.py --debug

📄 License

This project is licensed under the MIT License - see the file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📞 Support

If you encounter any issues or have questions:

1. Check the
2. Search existing issues
3. Create a new issue

🏷️ Version History

• v1.1.0 - Added comprehensive logging and .sql extension forcing

  • Detailed change logs for every processed file
  • Automatic .sql extension for all output files
  • Enhanced backup and logging functionality

• v1.0.0 - Initial release with basic accent removal functionality

  • Batch and single file processing
  • MCP server integration
  • WSL utilities
  • Comprehensive test suite

Made with ❤️ for OBIEE developers and system administrators.