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
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
-
Install dependencies:
pip install -r requirements.txt -
Create environment file:
# Create .env file with your configuration TG_TOKEN=your_telegram_bot_token ADMIN_ID=your_telegram_chat_id -
Run the server:
python main.py
📋 Available Tools
Basic Tools
echo— Echo back input text
File Tools
read_file— Read the contents of a filewrite_file— Write content to a filecreate_file— Create a new empty filecreate_folder— Create a new directorylist_files— List files and folders in a directorydelete_file— Delete a filerename_file— Rename or move a filemove_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 outputinstall_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 timeschedule_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 detailscancel_scheduled_job— Cancel a scheduled job by its IDget_available_functions— List all functions available for schedulingget_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 storageget_persistent_info— Retrieve all persistent data, or a specific key's valuedelete_persistent_info_key— Delete a key from persistent storage
Control Tools
type_text— Simulate typing text using the keyboardpress_hotkey— Press a combination of keys as a hotkey (e.g., Ctrl+Tab)switch_to_window— Switch focus to a window with a specified titlelist_open_windows— List the titles of all currently open windowsmove_mouse_to— Move the mouse cursor to specified screen coordinatesclick_mouse— Click the mouse at specified coordinates or at the current position
YouTube Tools
youtube_download_video— Download a YouTube video as MP4youtube_download_audio— Download YouTube audio as MP3youtube_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 definitionsjob_execution_log.json— Execution historypersistent_info.json— Custom datamain.log— Application logserror.log— Error logs
🛠️ Development
Adding New Tools
- Create a new module in
tools/ - Import the shared MCP instance:
from . import mcp - Define your tool function with
@mcp.tool()decorator - Register the function in
tools/__init__.pyif needed
Adding New Persistence Functions
- Add functions to
persistence.py - Import and use them in your tools
- Follow the existing pattern for error handling
🔍 Troubleshooting
- Check logs in
main.loganderror.log - Verify environment variables in
.env - Ensure all dependencies are installed
- Check file permissions for persistence