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

🚀 Quick Start

1. Install dependencies:

   pip install -r requirements.txt

2. Create environment file:

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

3. Run the server:

   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