# Linkr KVM MCP Server

Linkr KVM MCP Server exposes Radxa Linkr KVM controls through the Model Context Protocol (MCP). It lets an MCP client capture screenshots, crop screen areas, send keyboard and mouse events, type text, wait for on-screen text, and ask vision/OCR models about the current screen.

## Requirements

- Python 3.11 or newer is recommended.
- A reachable Radxa Linkr KVM device.
- A Linkr API key.
- Vision/OCR provider API keys if using `ask_vl` or `ocr_area`.

## Installation

Create and activate a virtual environment, then install dependencies:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

On POSIX-like shells:

```sh
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
```

## Configuration

Copy the example configuration and fill in real credentials:

```sh
cp config.example.yaml config.yaml
```

Do not commit real secrets. Keep `config.example.yaml` sanitized.

## Running

Recommended direct launch:

```powershell
python main.py
```

The default transport is `stdio`. You can also select a transport explicitly:

```powershell
python main.py --transport stdio
python main.py --http --host 127.0.0.1 --port 8000 --path /mcp
python main.py --transport sse --host 127.0.0.1 --port 8000 --sse-path /sse --message-path /messages/
```

Environment variables can also set defaults:

- `MCP_TRANSPORT`
- `MCP_HOST`
- `MCP_PORT`
- `MCP_PATH`
- `MCP_SSE_PATH`
- `MCP_MESSAGE_PATH`

The helper scripts forward arguments to the Python launcher:

```powershell
.\start.ps1 --http
```

```bat
start.bat --transport stdio
```

```sh
./start.sh --http
```

## MCP Tools

| Tool                   | Description                                                                     |
| ---------------------- | ------------------------------------------------------------------------------- |
| `snapshot`             | Capture the current KVM screen.                                                 |
| `snapshot_area`        | Capture a selected screen area.                                                 |
| `batch_events`         | Validate and send multiple Linkr KVM control events.                            |
| `keyboard`             | Send keyboard press or release events using `KeyboardEvent.code`.               |
| `mouse_abs`            | Send absolute-position mouse events with normalized `x` and `y`.                |
| `mouse_rel`            | Send relative-position mouse events in pixels.                                  |
| `text`                 | Type printable ASCII text, Tab, and Enter.                                      |
| `delay`                | Wait for a specified number of milliseconds.                                    |
| `ask_vl`               | Ask a vision-language model about a captured screen area.                       |
| `ocr_area`             | Recognize text in a captured screen area with the OCR model.                    |
| `find_text_pos`        | Find text positions on screen with local OCR.                                   |
| `wait_text_appear`     | Poll local OCR until text appears or a timeout is reached.                      |

## License

This project is licensed under the `GPL-3.0-or-later` License. See [LICENSE](LICENSE) for details.