# MCP Server - Modular Architecture

This MCP (Model Context Protocol) server is built with a clean, modular architecture for maintainable, scalable, and robust development.

## 📁 Project Structure

```text
MCP-test/
├── main.py                  # Main entry point
├── config.py                # Configuration and constants
├── persistence.py           # Data persistence layer
├── scheduler.py             # Job scheduling functionality
├── tools/                   # MCP tools organized by concern
│   ├── __init__.py          # Tools package initialization and registry
│   ├── basic_tools.py       # Basic utility tools
│   ├── control_tools.py     # Server control tools (restart, shutdown, etc)
│   ├── file_tools.py        # File system operations
│   ├── persistence_tools.py # Persistence management tools
│   ├── scheduling_tools.py  # Scheduling-related tools
│   ├── system_tools.py      # System information and commands
│   ├── telegram_tools.py    # Telegram integration
│   └── youtube_tools.py     # YouTube-related tools
├── requirements.txt         # Python dependencies
├── .env                     # Environment variables (create this)
└── README.md                # This file
```

## 🚀 Quick Start

1. **Install dependencies:**

   ```bash
   pip install -r requirements.txt
   ```

2. **Create environment file:**

   ```bash
   # Create .env file with your configuration
   TG_TOKEN=your_telegram_bot_token
   ADMIN_ID=your_telegram_chat_id
   ```

3. **Run the server:**

   ```bash
   python main.py
   ```

## 📋 Available Tools

### Basic Tools

- `echo` — Echo back input text

### File Tools

- `read_file` — Read the contents of a file
- `write_file` — Write content to a file
- `create_file` — Create a new empty file
- `create_folder` — Create a new directory
- `list_files` — List files and folders in a directory
- `delete_file` — Delete a file
- `rename_file` — Rename or move a file
- `move_folder` — Move a folder (directory) to a new location

### System Tools

- `system_info` — Get basic system information (platform, memory, CPU, etc.)
- `list_processes` — List running processes (PID, name, user)
- `run_python_code` — Execute a Python code snippet and return the output
- `install_python_library` — Install a Python library (via pip) and update requirements.txt

### Telegram Integration

- `send_telegram_message` — Send Telegram messages, audio, video, or documents (with optional metadata)
- `receive_telegram_updates` — Receive and download incoming Telegram messages and files

### Scheduling & Job Tools (still in testing)

- `schedule_telegram_message` — Schedule a Telegram message to be sent at a specific time (supports ISO datetime or relative times like "in 10 minutes")
- `schedule_function_call` — Schedule any registered function to run once at a specified time
- `schedule_recurring_job` — Schedule recurring jobs using cron expressions or intervals (e.g., "every 5 minutes", "0 9 ** 1-5")
- `list_scheduled_jobs` — List all currently scheduled jobs with details
- `cancel_scheduled_job` — Cancel a scheduled job by its ID
- `get_available_functions` — List all functions available for scheduling
- `get_job_execution_log` — View the execution history and results of scheduled jobs

### Persistence Tools

- `update_persistent_info` — Add or update a key-value pair in persistent storage
- `get_persistent_info` — Retrieve all persistent data, or a specific key's value
- `delete_persistent_info_key` — Delete a key from persistent storage

### Control Tools

- `type_text` — Simulate typing text using the keyboard
- `press_hotkey` — Press a combination of keys as a hotkey (e.g., Ctrl+Tab)
- `switch_to_window` — Switch focus to a window with a specified title
- `list_open_windows` — List the titles of all currently open windows
- `move_mouse_to` — Move the mouse cursor to specified screen coordinates
- `click_mouse` — Click the mouse at specified coordinates or at the current position

### YouTube Tools

- `youtube_download_video` — Download a YouTube video as MP4
- `youtube_download_audio` — Download YouTube audio as MP3
- `youtube_video_info` — Get detailed YouTube video information

## 🔧 Architecture Benefits

### Separation of Concerns

- **config.py**: Centralized configuration
- **persistence.py**: Data storage abstraction
- **scheduler.py**: Scheduling logic isolated
- **tools/**: Tools organized by functionality

### Maintainability

- Add new tools by creating new modules
- Clear dependencies between components
- Consistent error handling and logging

### Scalability

- Modular design for easy extension
- Shared MCP instance prevents conflicts
- Function registry enables dynamic scheduling

## 📊 Data Persistence

The server automatically persists:

- **Scheduled Jobs**: Survives server restarts
- **Execution Logs**: Detailed job run history
- **Persistent Info**: Custom key-value storage

Files created:

- `scheduled_jobs.json` — Job definitions
- `job_execution_log.json` — Execution history
- `persistent_info.json` — Custom data
- `main.log` — Application logs
- `error.log` — Error logs

## 🛠️ Development

### Adding New Tools

1. Create a new module in `tools/`
2. Import the shared MCP instance: `from . import mcp`
3. Define your tool function with `@mcp.tool()` decorator
4. Register the function in `tools/__init__.py` if needed

### Adding New Persistence Functions

1. Add functions to `persistence.py`
2. Import and use them in your tools
3. Follow the existing pattern for error handling

## 🔍 Troubleshooting

- Check logs in `main.log` and `error.log`
- Verify environment variables in `.env`
- Ensure all dependencies are installed
- Check file permissions for persistence