Content
---
license: mit
language:
- en
tags:
- mcp
- model-context-protocol
- desktop-automation
- llm
- ollama
- openai
- anthropic
- pyautogui
- python
pipeline_tag: text-generation
library_name: mcp
---
# sonu-davinceResolve-mcp
A Model Context Protocol (MCP) server that acts as a desktop automation assistant. It connects local or cloud LLMs (Ollama, OpenAI, Claude/Anthropic) with desktop automation capabilities (PyAutoGUI mouse, keyboard, shortcuts, screenshots) and implements an exclusive task lock to ensure tasks run to completion without interruption.
## Features
1. **Multi-LLM Router**:
- Query local models run through **Ollama** (e.g. Llama 3, Mistral, Gemma).
- Route query requests to **OpenAI** (GPT-4o, etc.) and **Anthropic** (Claude 3.5 Sonnet, etc.).
- Unified interface for all local and cloud prompt routing.
2. **Desktop Control & Shortcuts**:
- Complete keyboard control: write text, press specific keys, or dispatch multi-key hotkey combos (like `Ctrl + Alt + T` or `Ctrl + S`).
- Mouse control: clicks (left, right, middle), dragging, relative or absolute moves, and scroll wheel actions.
- Screen capture utility to take snapshots and save to files.
3. **Exclusive Task Locking**:
- Prevent parallel task execution or concurrent client requests.
- Once a task starts via `start_task`, an exclusive cross-process lock is acquired. All subsequent automation tools are guarded and verified against this lock.
- Once complete, `complete_task` releases the lock, restoring the server to an idle state.
---
## Architecture Flow
The operational flow of the server is represented in the diagram below:
*(For raw vector format, see [docs/architecture.svg](docs/architecture.svg))*
---
## Setup & Installation
### 1. Prerequisites
- Python >= 3.10
- [Ollama](https://ollama.com/) (Optional, for running free local models)
### 2. Install Dependencies
Initialize a virtual environment and install dependencies:
```bash
python -m venv venv
source venv/Scripts/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
```
### 3. Environment Configuration
Copy `.env.example` to `.env` and fill in your API credentials:
```bash
cp .env.example .env
```
Update any API keys:
- `OPENAI_API_KEY`: Required if routing to GPT models.
- `ANTHROPIC_API_KEY`: Required if routing to Claude models.
- `OLLAMA_BASE_URL`: Defaults to `http://localhost:11434`.
---
## Usage
### Run the Server
The server runs over standard I/O (stdio). You can start it using python:
```bash
python -m src.server
```
Or install it as a package and use the console entry point:
```bash
pip install -e .
sonu-mcp-server
```
### Client Simulation Test
We provide a standalone test script to simulate client-side tool activation, task locking, mouse movement, key combos, and model list querying:
```bash
python examples/client_example.py
```
---
## MCP Tool Definition Registry
The following tools are exposed by this MCP server:
| Tool Category | Tool Name | Parameters | Description |
| :--- | :--- | :--- | :--- |
| **Lifecycle** | `start_task` | `task_id` (str), `description` (str) | Start a task and lock the automation session. |
| | `complete_task` | `task_id` (str), `success` (bool), `details` (str) | Complete the active task and release the lock. |
| | `get_task_status` | None | Get current active task status. |
| | `force_unlock` | None | Reset and clear locks in case of error. |
| **Automation** | `click_mouse` | `x` (int), `y` (int), `button` (str), `clicks` (int) | Mouse click at coordinates. Guarded. |
| | `move_mouse` | `x` (int), `y` (int), `duration` (float) | Cursor move. Guarded. |
| | `drag_mouse` | `x` (int), `y` (int), `duration` (float), `button` (str) | Mouse drag. Guarded. |
| | `scroll_mouse` | `clicks` (int) | Scroll up/down. Guarded. |
| | `type_keyboard` | `text` (str), `interval` (float) | Type string. Guarded. |
| | `press_key` | `key` (str) | Press single keyboard button. Guarded. |
| | `press_hotkey` | `keys` (list[str]) | Press hotkey combo (e.g. `['ctrl', 'c']`). Guarded. |
| | `take_screenshot` | `filename` (str) | Capture screen snapshot. Guarded. |
| **LLM Router** | `route_llm_query` | `provider` (str), `model` (str), `prompt` (str), `system_prompt` (str) | Query a provider (ollama/openai/anthropic). |
| | `list_llm_models` | None | List active provider models. |
---
## Integration with Claude Desktop
To integrate with Claude Desktop, add the server to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"sonu-davinceResolve-mcp": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "C:/Users/janmw/.gemini/antigravity-ide/scratch/sonu-davinceResolve-mcp",
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"ANTHROPIC_API_KEY": "your-anthropic-api-key"
}
}
}
}
```
