# Umbrella MCP

[English](README.en.md)

Локальный MCP-сервер для работы с Lua-скриптами Umbrella и состоянием матча. Сервер запускается через stdio, а Lua bridge устанавливается в папку `scripts` выбранной установки Umbrella.

## Установка

Откройте PowerShell и выполните:

```powershell
& ([scriptblock]::Create((Invoke-RestMethod "https://raw.githubusercontent.com/madonchik123/umbrella-mcp/main/bootstrap.ps1")))
```

Установщик спросит путь к Umbrella, например `C:\Umbrella`. Путь можно передать сразу:

```powershell
& ([scriptblock]::Create((Invoke-RestMethod "https://raw.githubusercontent.com/madonchik123/umbrella-mcp/main/bootstrap.ps1"))) -UmbrellaDirectory "C:\Umbrella"
```

После установки перезагрузите скрипты Umbrella. Если Codex установлен, сервер уже будет добавлен в него. Для остальных клиентов используйте примеры ниже.

Локальная установка из клонированного репозитория:

```bat
install.cmd "C:\Umbrella"
```

Свой API reference можно передать вторым аргументом. Без него установщик скачает reference в папку сервера:

```bat
install.cmd "C:\Umbrella" "D:\UmbrellaAPI"
```

## Пути в примерах

Примеры ниже рассчитаны на установку Umbrella в `C:\Umbrella`. Если у вас другой путь, замените его в `command` и `args`.

```text
command: C:\Umbrella\tools\umbrella-mcp\.venv\Scripts\python.exe
args:    C:\Umbrella\tools\umbrella-mcp\umbrella_mcp\server.py
         --config
         C:\Umbrella\tools\umbrella-mcp\umbrella_mcp\config.json
```

## Управление из Umbrella

Установщик спросит общий токен. Нажмите Enter, чтобы сгенерировать его автоматически. После загрузки bridge откройте `Scripts` → `Main` → `Umbrella MCP`: там отображается статус подключения и можно указать адрес, порт и токен уже запущенного MCP-сервера.

## Codex

Обычно установщик добавляет сервер сам. Для ручной установки:

```powershell
codex mcp add umbrella -- "C:\Umbrella\tools\umbrella-mcp\.venv\Scripts\python.exe" "C:\Umbrella\tools\umbrella-mcp\umbrella_mcp\server.py" --config "C:\Umbrella\tools\umbrella-mcp\umbrella_mcp\config.json"
codex mcp get umbrella
```

## Claude Code

```powershell
claude mcp add --transport stdio --scope user umbrella -- "C:\Umbrella\tools\umbrella-mcp\.venv\Scripts\python.exe" "C:\Umbrella\tools\umbrella-mcp\umbrella_mcp\server.py" --config "C:\Umbrella\tools\umbrella-mcp\umbrella_mcp\config.json"
claude mcp get umbrella
```

Документация: [Claude Code MCP](https://code.claude.com/docs/en/mcp).

## Claude Desktop

Откройте `%APPDATA%\Claude\claude_desktop_config.json` и добавьте:

```json
{
  "mcpServers": {
    "umbrella": {
      "type": "stdio",
      "command": "C:\\Umbrella\\tools\\umbrella-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Umbrella\\tools\\umbrella-mcp\\umbrella_mcp\\server.py",
        "--config",
        "C:\\Umbrella\\tools\\umbrella-mcp\\umbrella_mcp\\config.json"
      ]
    }
  }
}
```

Полностью перезапустите Claude Desktop.

## Cursor

Создайте `%USERPROFILE%\.cursor\mcp.json` для глобальной установки или `.cursor\mcp.json` внутри проекта:

```json
{
  "mcpServers": {
    "umbrella": {
      "command": "C:\\Umbrella\\tools\\umbrella-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Umbrella\\tools\\umbrella-mcp\\umbrella_mcp\\server.py",
        "--config",
        "C:\\Umbrella\\tools\\umbrella-mcp\\umbrella_mcp\\config.json"
      ]
    }
  }
}
```

Перезапустите Cursor и проверьте сервер в Settings → Tools & MCP. Документация: [Cursor MCP](https://docs.cursor.com/context/model-context-protocol).

## VS Code

Выполните команду `MCP: Open User Configuration` или создайте `.vscode\mcp.json` в проекте:

```json
{
  "servers": {
    "umbrella": {
      "type": "stdio",
      "command": "C:\\Umbrella\\tools\\umbrella-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Umbrella\\tools\\umbrella-mcp\\umbrella_mcp\\server.py",
        "--config",
        "C:\\Umbrella\\tools\\umbrella-mcp\\umbrella_mcp\\config.json"
      ]
    }
  }
}
```

Запустите сервер через действие над ним в `mcp.json`. Документация: [MCP в VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers).

## Другие MCP-клиенты

Добавьте локальный stdio-сервер с именем `umbrella`, используя `command` и `args` из раздела «Пути в примерах». Если клиент принимает обычный MCP JSON, используйте блок `mcpServers` из примера для Cursor. Для клиентов с форматом VS Code используйте блок `servers`.

## MCP tools

```text
runtime_status
search_api
ping_runtime
get_game_snapshot
get_inventory
inspect_entity
list_loaded_scripts
set_event_filter
get_recent_events
clear_events
read_debug_log
clear_runtime_debug_log
run_script
reload_scripts
execute_console_command
run_panorama_javascript
```

## Проверка

После запуска клиента попросите модель вызвать `runtime_status`, затем `ping_runtime`. Если bridge не подключён, перезагрузите скрипты Umbrella и убедитесь, что загружен `umbrella_mcp_bridge.lua`.

## Разработка

```powershell
python -m pip install -r requirements.txt
python -m unittest discover -s tests -v
luau-compile --only-parse bridge\umbrella_mcp_bridge.lua
```

## Лицензия

[MIT](LICENSE)