karar-hayder/Simple-MCP

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

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