Metadata-Version: 2.5
Name: echo-mcp
Version: 0.1.9
Summary: A powerful MCP server for local system automation and browser control
Project-URL: Homepage, https://github.com/bala-2305/echo-mcp
Author-email: Mahibala H <hmahibala@gmail.com>
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4
Requires-Dist: mcp[cli]>=2.0.0
Requires-Dist: opencv-python
Requires-Dist: openpyxl
Requires-Dist: pandas
Requires-Dist: pillow
Requires-Dist: psutil
Requires-Dist: pyautogui
Requires-Dist: pycaw
Requires-Dist: pygetwindow
Requires-Dist: pyperclip
Requires-Dist: pytesseract
Requires-Dist: pyvolume
Requires-Dist: requests
Requires-Dist: selenium
Requires-Dist: uv
Requires-Dist: webdriver-manager
Description-Content-Type: text/markdown

# Echo MCP Server

[![PyPI Version](https://img.shields.io/pypi/v/echo-mcp?style=flat-square&logo=pypi&logoColor=white&label=PyPI)](https://pypi.org/project/echo-mcp/)
[![Python Version](https://img.shields.io/pypi/pyversions/echo-mcp?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/echo-mcp/)
[![License](https://img.shields.io/pypi/l/echo-mcp?style=flat-square&label=License)](https://pypi.org/project/echo-mcp/)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/echo-mcp?period=total&units=ABBREVIATION&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/echo-mcp)
[![GitHub](https://img.shields.io/badge/GitHub-repo-blue?style=flat-square&logo=github)](https://github.com/bala-2305/echo-mcp)
[![MCP](https://img.shields.io/badge/MCP-2.x%20Ready-brightgreen?style=flat-square)](https://modelcontextprotocol.io)
[![What's New in v0.1.9](https://img.shields.io/badge/What's%20New-v0.1.9-8A2BE2?style=flat-square&logo=sparkles&logoColor=white)](#-whats-new-in-v019)

A Model Context Protocol (MCP) server that provides autonomous GUI automation capabilities to LLM clients (like Claude Desktop, Antigravity, Cursor, and Windsurf). This tool allows an AI to interact directly with your computer's screen, mouse, keyboard, apps, databases, and browser.

---

## 🚀 What's New in v0.1.9

> [!TIP]
> **Echo MCP v0.1.9** brings **76 total automation tools**, featuring native **MCP 2.x SDK support**, **SQLite database interactions**, **Windows application discovery & control**, and **advanced agentic perception & workflow capabilities**!

- ⚡ **MCP Python SDK v2.x Architecture**: Migrated to the modern `MCPServer` specification with async `server_lifespan` resource cleanup.
- 🗄️ **Database Interaction Tools**:
  - `db_query`: Execute parameterized SQL queries returning structured JSON rows and columns.
  - `db_execute`: Run `INSERT`, `UPDATE`, `DELETE`, `CREATE`, or multi-statement scripts with automated transaction commits.
  - `db_list_tables`: List all database tables and views with row counts.
  - `db_table_schema`: Inspect column definitions, types, primary keys, and foreign keys.
  - `db_export_query`: Export query results directly to CSV, JSON, or Excel.
- 🖥️ **Installed App Discovery & Smart Launch**:
  - `find_installed_apps`: Search installed software across Windows Start Menu and Registry (64-bit and 32-bit).
  - `launch_app`: Launch applications or automatically focus/restore existing open windows.
  - `list_running_apps`: Discover active GUI applications with open desktop windows and process info.
- 🤖 **Advanced Agentic Autonomy**:
  - `execute_command`: Run timeout-bounded shell commands (PowerShell/CMD) with stdout/stderr capture.
  - `find_files` & `search_in_files`: Fast recursive file pattern matching and code/text grep.
  - `get_file_info`: Inspect file size, modification dates, and SHA-256 hashes.
  - `wait_for_text_on_screen` & `wait_for_pixel_color`: Perception loops for asynchronous UI loading.
  - `snap_window`: Snap and organize windows across screen sectors (`left`, `right`, `top`, `bottom`, `center`, etc.).
  - `speak_text` & `show_notification`: Native Windows TTS voice synthesis and desktop notifications.

---

## Features

- **Computer Vision & OCR**: Extract text from screen regions and find UI elements visually.
- **Mouse & Keyboard Control**: Perform clicks, typing, hotkeys, and precise movements.
- **Window Management**: Focus, minimize, maximize, and query open windows.
- **System Automation**: Manage processes, execute system commands, adjust volume, and check system health.
- **Browser Automation**: Full web browsing capabilities (Selenium) for navigating, finding elements, extracting text, and clicking.
- **File System**: Read/write files, list directories, download files.

## Setup Instructions

### 1. Environment Requirements
- Python 3.12 or higher
- Windows (recommended for PyAutoGUI compatibility)

### 2. Installation
You can install the package directly from PyPI (https://pypi.org/project/echo-mcp/):

```powershell
pip install echo-mcp
```

### 3. Configuration
You can automatically configure your AI apps and IDEs (Google Antigravity, Claude Desktop, Cursor, Windsurf, VS Code / Cline) to use the MCP server by running:
```powershell
python -m echo_mcp.config
```
To configure all supported apps automatically without interactive prompts:
```powershell
python -m echo_mcp.config --all
```

This setup wizard configures your client settings files (e.g. `~/.gemini/config/mcp_config.json` for Antigravity). Restart your app/IDE after configuration for the new tools to take effect.

## Available Tools

The server provides a comprehensive suite of tools spanning multiple categories:

### AI Computer Control (Anthropic / OpenAI Operator Standard)
- `computer`: Unified action tool supporting `screenshot`, `mouse_move`, `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click`, `left_click_drag`, `mouse_down`, `mouse_up`, `type` (Unicode clipboard paste), `key`, `hotkey`, `scroll`, and `cursor_position`. Includes an automatic action-observation feedback loop returning updated screenshots.
- **Multimodal Screen Perception**: High-visibility pointer crosshair rendered on captured screenshots, Windows DPI auto-scaling, and native MCP `Image` output format.

### Mouse & Keyboard
- `mouse_click`, `mouse_double_click`, `move_mouse`, `mouse_drag`, `mouse_scroll`, `get_mouse_position`
- `type_text`, `press_key`, `hotkey`

### Screen & Vision
- `take_screenshot` (native MCP Image output with cursor overlay), `get_screen_size`, `get_text_at_coords`, `find_text_on_screen`, `click_element`

### Window & Process Management
- `list_all_windows`, `focus_window`, `maximize_window`, `minimize_window`, `get_window_geometry`, `close_all_windows_by_title`, `get_active_window_info`, `snap_window`
- `list_processes`, `kill_process`, `get_process_stats`, `wait_for_process`

### Application Discovery & Control
- `find_installed_apps` (searches Start Menu shortcuts & Windows Registry Uninstall keys for installed software), `launch_app` (smart launch with auto-focus if already running), `list_running_apps` (active visible GUI windows with process info)

### Database & Tabular Data (SQLite)
- `db_query` (safe SELECT queries with parameterized inputs), `db_execute` (INSERT/UPDATE/DELETE/CREATE transactions and multi-statement scripts), `db_list_tables`, `db_table_schema` (PRAGMA table definitions and foreign keys), `db_export_query` (export query results to CSV, JSON, or Excel)

### Agentic Capabilities & Workflow Autonomy
- `execute_command` (timeout-guarded PowerShell/CMD execution with stdout/stderr capture)
- `find_files` (fast wildcard/pattern search), `search_in_files` (code/text grep with line excerpts), `get_file_info` (file size, timestamps, and SHA-256 hash)
- `wait_for_text_on_screen` (perception polling loop with OCR), `wait_for_pixel_color` (RGB screen coordinate perception loop)
- `speak_text` (Windows TTS voice synthesizer), `show_notification` (desktop toast notifications)

### System Utilities
- `system_power`, `set_volume`, `get_system_health`, `get_disk_usage`, `ping`, `list_network_interfaces`
- `launch_application`, `get_environment_variable`, `get_clipboard`, `set_clipboard`, `wait`

### File System
- `list_directory`, `read_file_content`, `write_to_file`, `delete_file`, `create_directory`, `download_file`

### Browser Automation
- `browser_open`, `browser_close`, `browser_navigate`, `browser_get_url`, `browser_get_title`, `browser_get_page_source`
- `browser_find_element`, `browser_click`, `browser_fill_form`, `browser_extract_text`
- `browser_screenshot`, `browser_scroll`, `browser_execute_script`, `browser_wait_for_element`, `web_scrape_to_file`

## Security Warning
**Giving an LLM control over your mouse and keyboard is powerful but risky.** Only run this server with prompts you trust, and never leave the automation unattended while active.
