# Total PC Control

An MCP (Model Context Protocol) server that provides control over your screen, mouse, and keyboard using [nut.js](https://nutjs.dev/).

## ⚠️ Warning: Use with Caution

This software enables programmatic control of your mouse, keyboard, and other system operations. By using this software, you acknowledge and accept that:

- Giving AI models direct control over your computer through this tool can lead to unintended consequences
- The software can control your mouse, keyboard, and other system functions
- You are using this software entirely at your own risk
- The creators and contributors of this project accept NO responsibility for any damage, data loss, or other consequences that may arise from using this software

## Features

- 📷 **Screen Capture**: Capture screenshots of your entire screen or specific regions
- 🖱️ **Mouse Control**: Move the mouse cursor, click, double-click, and scroll
- ⌨️ **Keyboard Input**: Type text and press keyboard shortcuts
- 🪟 **Window Management**: Find, focus, and manipulate application windows
- 📋 **Clipboard Access**: Copy and paste text

## Prerequisites

- Node.js 16 or higher
- npm or yarn
- cmake-js (for building native dependencies)

## Installation

1. Clone the repository:
```bash
git clone https://github.com/jasondsmith72/total-pc-control.git
cd total-pc-control
```

2. Install cmake-js globally (required for building native dependencies):
```bash
npm install -g cmake-js
```

3. Install the libnut core library (required for nut.js):
```bash
git clone https://github.com/nut-tree/libnut.git libnut-core
cd libnut-core
npm install
cmake-js rebuild
cd ..
```

4. Install dependencies and build the project:
```bash
npm install
npm run build
```

## Using with Claude for Desktop

1. Edit your Claude for Desktop configuration file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add the following to your configuration:

```json
{
  "mcpServers": {
    "total-pc-control": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/total-pc-control/build/index.js"
      ]
    }
  }
}
```

Replace `/ABSOLUTE/PATH/TO/` with the actual path to where you cloned the repository.

3. Restart Claude for Desktop

4. Look for the hammer icon in the Claude interface to indicate available tools.

## Available Tools

### Screen Capture

- `capture_screen`: Capture the entire screen as an image. Supports `format` (png/jpeg) and `quality` (jpeg only) parameters.
- `capture_region`: Capture a specific region of the screen. Requires `left`, `top`, `width`, `height`. Supports `format` and `quality`.
- `get_screen_size`: Get the dimensions (width and height) of the screen.

### Mouse Control

- `move_mouse`: Move the mouse cursor to a specific `x`, `y` position.
- `get_mouse_position`: Get the current `x`, `y` position of the mouse cursor.
- `click_mouse`: Click the mouse at the current position. Optional `button` (left, middle, right).
- `click_at`: Click the mouse at a specific `x`, `y` position. Optional `button`.
- `double_click`: Double-click the mouse at the current position.
- `double_click_at`: Double-click the mouse at a specific `x`, `y` position.
- `scroll_mouse`: Scroll the mouse wheel. Requires `direction` (up/down). Optional `amount`.
- `drag_mouse`: Drag the mouse from the current position to a target `x`, `y` position.
- `drag_mouse_from_to`: Drag the mouse from a `startX`, `startY` position to an `endX`, `endY` position.

### Keyboard Input

- `type_text`: Type text at the current cursor position. Requires `text`.
- `type_text_with_delay`: Type text with a delay between keystrokes. Requires `text`. Optional `delayMs`.
- `press_key`: Press a specific keyboard key. Requires `key`.
- `press_key_shortcut`: Press a keyboard shortcut (combination of keys). Requires `keys` array.
- `hold_key`: Hold down a keyboard key. Requires `key`.
- `release_key`: Release a held keyboard key. Requires `key`.

### Clipboard Operations

- `get_clipboard_text`: Get text from the clipboard.
- `set_clipboard_text`: Set text to the clipboard. Requires `text`.
- `copy_selected_text`: Copy selected text to clipboard and return it (uses Ctrl+C/Cmd+C).
- `paste_text`: Paste text at current cursor position (uses Ctrl+V/Cmd+V). Requires `text`.
- `get_clipboard_image`: Get image from the clipboard (if available) as base64 data.

### UI Automation Tools (Windows Only)

These tools use Windows UI Automation via PowerShell to interact with UI elements.

- `get_ui_element_info`: Finds a UI element within a specified window and returns its properties (Name, AutomationId, ClassName, ControlType, BoundingRectangle, IsEnabled, IsOffscreen, Value, Children).
  - Requires `windowTitle` (can be partial match).
  - Requires at least one of `elementName`, `automationId`, or `className` to find a specific element.
  - If no element identifier is provided, it lists the direct children of the window.
- `invoke_ui_element_action`: Performs an action on a specified UI element.
  - Requires `windowTitle`.
  - Requires `action` (`Click`, `SetValue`, or `Focus`).
  - Requires at least one of `elementName`, `automationId`, or `className`.
  - Requires `valueToSet` (string) if `action` is `SetValue`.

## Development

To run the server in development mode:

```bash
npm run dev
```

To run tests:

```bash
npm test
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.