# MCP Cloud Gateway

**Windows-приложение, которое объединяет локальные MCP-серверы в одну защищённую ссылку и публикует её через Cloudflare Tunnel.**

Подключите к Notion, Claude, Cursor или другому MCP-клиенту один адрес:

```text
https://your-tunnel.trycloudflare.com/mcp?token=YOUR_TOKEN
```

Все включённые HTTP, SSE, stdio и встроенные серверы становятся доступны через этот единый endpoint.

## Возможности

- **Единый MCP endpoint `/mcp`** — инструменты всех включённых серверов в одном подключении.
- **Cloudflare Tunnel** — публичный HTTPS без проброса портов и белого IP.
- **Совместимость с Notion** — Streamable HTTP и legacy SSE, абсолютный callback endpoint и авторизация в URL.
- **HTTP/SSE и stdio** — проксирование запущенных серверов и запуск локальных серверов через `npx` или другую команду.
- **Автодетект** — поиск MCP на типовых локальных портах с настоящим `initialize`.
- **Управление инструментами** — понятные названия, метки `READ`/`WRITE` и отдельный переключатель каждого инструмента.
- **Встроенная файловая система** — доступ к пользовательским путям и дискам с блокировкой системных каталогов Windows/Linux.
- **Bearer-авторизация** — общий токен, сравнение постоянного времени, возможность перевыпуска.
- **Диагностика** — журнал запросов, события, поиск, фильтры и экспорт CSV/NDJSON.
- **Автоустановка** — приложение может самостоятельно установить Node.js и `cloudflared` в свою папку данных.

## Что исправлено в v1.0.7

- Длинная строка версии `cloudflared` больше не вылезает из зелёного индикатора и не перекрывает кнопку обновления.
- На главной показываются **запросы за текущий запуск приложения**, а не накопленный счётчик из старого файла логов.
- История за последние 24 часа по-прежнему доступна в подписи и разделе логов.
- Сообщение `Failed to proxy HTTP: context canceled` больше не отображается как авария туннеля: это штатное закрытие длинного SSE-соединения клиентом.
- Версия сборки берётся из `package.json`, поэтому имена Setup и Portable `.exe` совпадают с релизом.

## Быстрый старт для пользователя

### Готовый `.exe`

В GitHub Releases доступны два варианта:

- `MCP-Cloud-Gateway-Setup-1.0.7.exe` — обычный установщик Windows x64.
- `MCP-Cloud-Gateway-1.0.7-portable.exe` — портативная версия без установки.

1. Запустите приложение.
2. На первом экране установите Node.js и `cloudflared` автоматически.
3. Добавьте MCP-сервер вручную или через **Автодетект**.
4. Запустите шлюз и Cloudflare Tunnel.
5. На главной нажмите **Скопировать для Notion**.
6. Вставьте полученный адрес в настройках MCP-подключения Notion.

> При включённой авторизации используйте именно кнопку копирования: она добавляет токен к адресу `/mcp`.

## Подключение к Notion

В Notion нужен **единый URL шлюза**, а не адрес отдельного сервера:

```text
https://example.trycloudflare.com/mcp?token=YOUR_TOKEN
```

После подключения Notion получает инструменты всех включённых серверов. Для предотвращения конфликтов шлюз публикует имена в формате:

```text
server-slug__tool_name
```

Например:

```text
files__read_file
files__list_directory
github__search_repositories
```

## Встроенный файловый MCP

Встроенный сервер позволяет работать с пользовательскими файлами на доступных дисках. По умолчанию доступны:

| Инструмент | Режим | Назначение |
| --- | --- | --- |
| `list_roots` | READ | Список доступных дисков и расположений |
| `list_directory` | READ | Содержимое каталога |
| `read_file` | READ | Чтение текстового файла |
| `write_file` | WRITE | Создание или перезапись файла |
| `create_directory` | WRITE | Создание каталога |
| `delete_path` | WRITE | Удаление; по умолчанию выключено |
| `move_path` | WRITE | Перемещение; по умолчанию выключено |

### Защищённые системные области

На Windows блокируются `Windows`, `Program Files`, `Program Files (x86)`, `ProgramData`, `Recovery`, `Boot`, `$Recycle.Bin` и `System Volume Information`. На Linux блокируются основные системные каталоги: `/etc`, `/usr`, `/bin`, `/sbin`, `/boot`, `/proc`, `/sys`, `/dev`, `/lib`, `/run` и `/var`.

Проверяется как исходный путь, так и фактический путь после разрешения символических ссылок.

## Маршруты

| Маршрут | Назначение |
| --- | --- |
| `GET/POST /mcp` | Единый MCP всех включённых серверов |
| `POST /mcp/message` | Callback legacy SSE-сессии |
| `ANY /mcp/<slug>` | Прямое подключение к конкретному серверу |
| `GET /health` | Публичная проверка состояния |
| `GET /` | Краткий JSON-манифест шлюза |

Токен принимается тремя способами:

```http
Authorization: Bearer YOUR_TOKEN
X-Api-Key: YOUR_TOKEN
```

или в URL:

```text
/mcp?token=YOUR_TOKEN
```

## Добавление серверов

### HTTP / Streamable HTTP / SSE

Укажите название и локальный URL сервера, например:

```text
http://127.0.0.1:3000/mcp
```

### stdio

Укажите команду и аргументы, например:

```text
Команда:    npx
Аргументы:  -y @modelcontextprotocol/server-postgres POSTGRES_URL
```

Шлюз запустит процесс по первому запросу и преобразует stdio JSON-RPC в HTTP.

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

Требования:

- Node.js 18 или новее;
- npm;
- Windows 10/11 для сборки Windows `.exe`.

```bash
npm install
npm run dev
```

Проверка типов и production-сборка интерфейса:

```bash
npm run typecheck
npm run build
```

## Сборка Windows

Обычная сборка:

```bat
npm install
npm run dist
```

Или запустите:

```text
build-exe.bat
```

Если права администратора недоступны:

```text
build-exe-no-admin.bat
```

Артефакты появятся в `release/`:

```text
MCP-Cloud-Gateway-Setup-1.0.7.exe
MCP-Cloud-Gateway-1.0.7-portable.exe
```

Подробности и решение ошибки Windows symlink находятся в [`BUILD-WINDOWS.md`](BUILD-WINDOWS.md).

## Автоматический GitHub Release

В репозитории есть workflow `.github/workflows/release.yml`. Чтобы собрать `.exe` и создать релиз:

```bash
git tag v1.0.7
git push origin v1.0.7
```

GitHub Actions на Windows:

1. установит зависимости;
2. соберёт Setup и Portable `.exe`;
3. сформирует архив исходников;
4. прикрепит все файлы к GitHub Release.

## Где хранятся данные

```text
Windows: %APPDATA%\mcp-cloud-gateway\
macOS:   ~/Library/Application Support/mcp-cloud-gateway/
Linux:   ~/.config/mcp-cloud-gateway/
```

Основные файлы:

```text
config.json   настройки, серверы и токен
logs.ndjson   журнал, если включена запись на диск
runtime/      управляемые копии Node.js и cloudflared
```

## Решение проблем

### Notion бесконечно подключается

- Используйте ссылку с главной страницы, заканчивающуюся на `/mcp?token=...`.
- Перезапустите шлюз и туннель после обновления.
- Удалите старое MCP-подключение из Notion и создайте новое, если Notion закэшировал старую схему.

### `Invalid content type, expected text/event-stream`

Убедитесь, что используется `/mcp`, а не только домен туннеля. Версия 1.0.7 поддерживает legacy SSE и Streamable HTTP.

### `context canceled` в cloudflared

Это штатное закрытие SSE-соединения клиентом, а не падение туннеля. В v1.0.7 такие сообщения скрываются из красного статуса.

### Туннель не подключается через VPN

Выберите `http2` и IPv4 в настройках туннеля или запустите автоматический подбор параметров. QUIC использует UDP и часто блокируется VPN или корпоративной сетью.

### Порт 8787 занят

Измените порт в **Настройки → Шлюз**, затем перезапустите шлюз.

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

- По умолчанию шлюз слушает только `127.0.0.1`.
- Публичный доступ идёт через HTTPS Cloudflare Tunnel.
- Не публикуйте URL, содержащий токен.
- Перевыпустите токен, если он попал в логи, скриншот или публичный issue.
- Выключайте ненужные серверы и WRITE-инструменты.
- Быстрые домены `trycloudflare.com` меняются после перезапуска туннеля; для постоянного адреса используйте именованный туннель.

## Структура проекта

```text
electron/
  main.js
  preload.js
  lib/
    gateway.js
    cloudflared.js
    runtime.js
    detect.js
    stdio-bridge.js
    builtin-filesystem.js
    mcp-tools.js
    logs.js
    store.js
src/
  components/
  views/
  state/
  styles/
preview/
build/
```

## Лицензия

[MIT](LICENSE)