# Nik-Browser MCP

Локальный MCP-сервер, который даёт LLM собственный независимый Chromium. Браузер, профиль входов и снимки хранятся внутри папки проекта и не смешиваются с вашим обычным Chrome или Edge.

Подходит для Windows 10/11, LM Studio и других MCP-клиентов со стандартным транспортом `stdio`.

## Что умеет

- открывать сайты и вкладки;
- читать текст страниц и находить кнопки, ссылки и поля;
- нажимать кнопки и клавиши;
- заполнять текстовые поля;
- выбирать пункты списков и устанавливать флажки;
- прикреплять файлы и папки на GitHub, Яндекс Диск, Google Drive и другие сайты;
- делать PNG-снимки страниц;
- проверять Git-проекты на типичные секреты;
- дополнительно публиковать репозитории через GitHub CLI.

## Что будет создано на компьютере

Внутри папки проекта появятся:

- `.venv` — отдельное Python-окружение;
- `browser-runtime` — собственный Chromium;
- `browser-profile` — cookies и входы на сайты;
- `screenshots` — снимки страниц.

Все эти каталоги исключены из Git.

## Быстрая установка для Windows

### Шаг 1. Установите Python

Скачайте Python 3.10 или новее с <https://www.python.org/downloads/windows/>.

На первом экране установщика отметьте **Add Python to PATH**.

### Шаг 2. Скачайте проект

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

```powershell
cd "$HOME\Desktop"
git clone https://github.com/Nikolay-3D/nik-browser-mcp.git
cd nik-browser-mcp
```

Если Git не установлен, скачайте ZIP на странице GitHub через **Code → Download ZIP**, распакуйте его и откройте PowerShell в распакованной папке.

### Шаг 3. Запустите автоматическую установку

```powershell
powershell -ExecutionPolicy Bypass -File .\install-windows.ps1
```

Скрипт:

1. создаст `.venv`;
2. установит Python-зависимости;
3. скачает Chromium в `browser-runtime`;
4. запустит тесты и MCP-handshake;
5. напечатает готовый фрагмент конфигурации.

## Ручная установка venv

Если автоматический скрипт не подошёл:

```powershell
cd "ПОЛНЫЙ\ПУТЬ\К\nik-browser-mcp"
py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

Если `py -3.10` не найден, попробуйте `py -3`.

Chromium можно установить после подключения, попросив модель вызвать:

```text
browser_install_runtime с confirm="INSTALL_BROWSER"
```

Либо установить заранее:

```powershell
$env:PLAYWRIGHT_BROWSERS_PATH = "$PWD\browser-runtime"
.\.venv\Scripts\python.exe -m playwright install chromium
```

## Подключение к LM Studio

### Шаг 1. Узнайте полный путь

В PowerShell, находясь в папке проекта:

```powershell
$PWD.Path
```

Например, получилось:

```text
C:\Users\Ivan\Desktop\nik-browser-mcp
```

### Шаг 2. Откройте конфигурацию MCP

В LM Studio откройте раздел MCP Servers или файл:

```text
C:\Users\ВАШЕ_ИМЯ\.lmstudio\mcp.json
```

### Шаг 3. Добавьте сервер

Замените `C:\PATH\TO\nik-browser-mcp` на настоящий полный путь:

```json
{
  "mcpServers": {
    "Nik-Browser": {
      "command": "C:\\PATH\\TO\\nik-browser-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\PATH\\TO\\nik-browser-mcp\\run_server.py"
      ],
      "env": {
        "MCP_BROWSER_CDP_URL": "http://127.0.0.1:9333",
        "MCP_BROWSER_ALLOWED_ROOTS": "C:\\Users\\ВАШЕ_ИМЯ\\Desktop;C:\\Users\\ВАШЕ_ИМЯ\\Documents;C:\\Users\\ВАШЕ_ИМЯ\\Downloads",
        "PYTHONUTF8": "1"
      }
    }
  }
}
```

Если в `mcp.json` уже есть другие серверы, не удаляйте их. Добавьте только блок `"Nik-Browser": {...}` внутрь существующего `mcpServers`, поставив запятую между соседними блоками.

Готовый шаблон также находится в [mcp.example.json](mcp.example.json).

После сохранения обновите список MCP, выключите и включите сервер или перезапустите LM Studio.

## Первый запуск

Напишите модели:

```text
Запусти собственный браузер через browser_launch, открой github.com и покажи список вкладок.
```

Откроется отдельное окно Chromium. Войдите в нужные сервисы вручную. Входы сохранятся в `browser-profile`.

## Как пользоваться

Модель должна работать в таком порядке:

1. `browser_snapshot` — получить текст страницы и элементы `e1`, `e2` и так далее.
2. `browser_click`, `browser_fill`, `browser_select_option` или `browser_set_checked` — выполнить действие.
3. После перехода на другую страницу — снова вызвать `browser_snapshot`.

Идентификаторы `e1`, `e2` временные. Ошибка `Ref expired` означает, что нужен новый снимок.

### Пример поиска

```text
Открой сайт, найди поле поиска, введи запрос и покажи результаты.
```

### Пример загрузки файла

```text
Открой Яндекс Диск, найди загрузку и прикрепи файл C:\Users\Ivan\Desktop\report.pdf. Перед окончательной отправкой покажи выбранный файл.
```

Для прикрепления используется `browser_upload_files` с `confirm_external_upload=true`. Прикрепление не нажимает финальную кнопку отправки автоматически.

### Пример загрузки проекта

```text
Открой Google Drive и загрузи папку C:\Users\Ivan\Desktop\MyProject. Не отправляй ничего, пока не покажешь список файлов.
```

При загрузке папки автоматически пропускаются `.git`, `.venv`, `venv`, `node_modules` и `__pycache__`. Типичные секреты и приватные ключи блокируются.

## Публикация на GitHub

Небольшие файлы можно загружать через сайт GitHub обычными браузерными инструментами.

Для полноценного Git-репозитория удобнее дополнительный путь через GitHub CLI:

1. `github_cli_status` — проверить установку и вход;
2. `github_cli_install(confirm="INSTALL_GH")` — установить `gh` через winget;
3. один раз выполнить `gh auth login` в обычном PowerShell;
4. `git_project_status` — проверить проект и секреты;
5. `github_publish_project(..., confirm="PUBLISH")` — создать и отправить репозиторий.

По умолчанию используйте `visibility="private"`. Для открытого проекта укажите `visibility="public"` явно.

## Проверка установки

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe smoke_test.py
```

Успешный результат содержит строку вроде:

```text
MCP handshake OK: 19 tools
```

## Частые ошибки

### `Not connected`

- проверьте абсолютные пути в `command` и `args`;
- проверьте наличие `.venv\Scripts\python.exe`;
- запустите `smoke_test.py`;
- выключите и снова включите MCP;
- если не помогло — перезапустите LM Studio.

### `Private browser runtime is not installed`

Вызовите:

```text
browser_install_runtime(confirm="INSTALL_BROWSER")
```

### `Browser did not expose CDP`

Порт `9333` занят другим процессом. Закройте старое окно Nik-Browser либо укажите одинаковый свободный порт в `MCP_BROWSER_CDP_URL` и `browser_launch`.

### `Path is outside MCP_BROWSER_ALLOWED_ROOTS`

Добавьте нужную папку в `MCP_BROWSER_ALLOWED_ROOTS`. В Windows пути разделяются точкой с запятой. После изменения перезапустите MCP.

## Безопасность

- CDP доступен только через `localhost`.
- Никогда не публикуйте `browser-profile`: в нём находятся cookies и входы.
- Не добавляйте `browser-runtime` и `.venv` в Git.
- Разрешайте модели доступ только к нужным каталогам.
- Проверяйте сайт и список файлов перед `confirm_external_upload=true`.
- Подробнее: [SECURITY.md](SECURITY.md).

## Лицензия

MIT — можно использовать, изменять и распространять с сохранением текста лицензии.