#  Notion agent

MCP-сервер, через который Notion AI работает с одной папкой на твоём ПК: читает и правит файлы, а в полном режиме запускает команды и агентов Codex, Claude Code и Gemini CLI. Каждое действие ты подтверждаешь сам.

Есть два варианта:

- **консольная версия** для Windows: `start.bat` и `tunnel.bat`, подтверждения клавишами в окне консоли;
- **расширение для VS Code** в папке [`vscode/`](vscode): кнопка в статус-баре, подтверждения уведомлениями, сравнение файла до и после правки.

Оба варианта используют один и тот же `server.mjs`.

## Как это работает

```
Notion AI ──HTTPS──> туннель (cloudflared или Tailscale) ──> 127.0.0.1:8787 PC Bridge ──> C:\Games\Projects
                                                                   │
                                                     подтверждение на ПК: Y / A / N
```

- Сервер слушает только `127.0.0.1`. Из интернета он доступен, только пока открыт туннель.
- Без токена запрос получает 401.
- Файловые инструменты работают только внутри рабочей папки. Пути наружу, ссылки и папка самого моста закрыты.
- Удаление идёт в корзину Windows.
- Каждый запрос и решение пишутся в `audit.log`.

## Консольная версия

Нужны Node.js 18+ и cloudflared:

```
winget install OpenJS.NodeJS.LTS
winget install --id Cloudflare.cloudflared
```

1. Скачай репозиторий и выполни `npm install` в его папке. Не клади его внутрь рабочей папки.
2. Укажи рабочую папку в `config.json`, поле `root`. Обратные слеши пишутся двойными: `C:\\Games\\Projects`.
3. Запусти `start.bat` (чтение и запись) или `start-full.bat` (плюс команды и агенты). В окне появится токен, он же в `token.txt`.
4. Во втором окне запусти `tunnel.bat`. Он покажет адрес вида `https://xxxx.trycloudflare.com/mcp`.
5. В Notion: Settings → Notion AI → AI connectors → добавить свой MCP-сервер. Укажи адрес, способ входа Bearer token и вставь токен. Custom MCP servers должен включить владелец рабочего пространства.

Адрес cloudflared меняется при каждом запуске `tunnel.bat`. Токен остаётся прежним. Новый токен создаёт `new-token.bat`.

### Клавиши

| Клавиша | Действие |
|---|---|
| `Y` или `Н` | разрешить один раз |
| `A` или `Ф` | разрешать этот тип всегда |
| `N`, `Т` или `Esc` | отклонить |

Без ответа за 120 секунд запрос отклоняется. Если Notion AI отменил запрос, он не выполнится.

## Расширение для VS Code

Ничего не запускается само. Мост и туннель включаются кнопкой **Bridge** внизу слева, закрываются кнопкой или вместе с VS Code.

- Запросы приходят уведомлениями с кнопками «Изменения», «Разрешить», «Отклонить», «Всегда».
- «Изменения» открывает сравнение файла сейчас и после правки.
- Если уведомление скрылось, кнопка Bridge становится жёлтой, и ответить можно через неё.
- «Спросить Notion AI о выделенном» в меню правой кнопки копирует вопрос с кодом, путём и номерами строк и открывает Notion.
- Туннель cloudflared идёт по HTTP/2 через TCP 443.
- Токен, разрешения и журнал лежат в `%USERPROFILE%\.pc-bridge`. При первом запуске можно взять `token.txt` от консольной версии.

Сборка `.vsix`:

```
cd vscode
npm install
npm run package
```

Установка: Extensions → `···` → Install from VSIX. Настройки и подробности в [`vscode/README.md`](vscode/README.md).

## Режимы

| Режим | Что доступно |
|---|---|
| `ro` | чтение, поиск, сведения о ПК |
| `rw` | плюс запись, правка, перемещение, удаление, открытие в редакторе |
| `full` | плюс команды и агенты |

## Инструменты

| Инструмент | Режим | Что делает |
|---|---|---|
| `system_info` | ro | ОС, Node, рабочая папка, какие CLI есть в PATH |
| `list_dir` | ro | дерево папки, `node_modules` и `.git` не раскрываются |
| `read_file` | ro | файл целиком или диапазон строк |
| `search_text` | ro | поиск строки или регулярного выражения |
| `write_file` | rw | создать или перезаписать файл |
| `edit_file` | rw | заменить точный фрагмент |
| `make_dir`, `move_path` | rw | создать папку, переместить или переименовать |
| `delete_path` | rw | удалить в корзину |
| `open_in_editor` | rw | открыть в VS Code, Cursor или Antigravity |
| `run_command` | full | команда cmd или PowerShell, длинные работают в фоне |
| `ask_agent` | full | задание для Codex, Claude Code или Gemini CLI |
| `job_output`, `list_jobs`, `stop_job` | full | вывод и остановка фоновых задач |

## Типы подтверждений

- `чтение` и отдельно `чтение секретов` для `.env`, `.pem`, `.key`, `credentials.json` и похожих; поиск такие файлы пропускает.
- `запись`, `удаление`, `редактор`.
- `команда: npm` для любой команды, начинающейся с `npm`; у `git`, `python` и других свой тип.
- `команда целиком: …` для команд с `&&`, `|`, `;`, `>`, `%`; «всегда» разрешает только эту строку целиком.
- `агент: codex (правка файлов)` и `агент: codex (полный доступ)` разделены, так же для claude и gemini.

Разрешения «всегда» хранятся в `approvals.json`. Удали файл или нажми «Сбросить» в расширении, и всё снова будет спрашиваться.

## Агенты

| | `edit` | `full` |
|---|---|---|
| Codex | `--sandbox workspace-write` | `--sandbox danger-full-access` |
| Claude Code | `--permission-mode acceptEdits` | `--permission-mode bypassPermissions` |
| Gemini CLI | `--approval-mode auto_edit` | `--approval-mode yolo` |

Каждого агента нужно один раз поставить и войти в аккаунт на ПК.

## Туннель и VPN

Некоторые VPN блокируют P2P-трафик. Tailscale соединяет узлы напрямую по UDP и может попасть под такую блокировку. Тогда добавь `tailscaled.exe` в исключения VPN или используй cloudflared по HTTP/2.

## Важно

Команды и агенты работают с правами твоего пользователя Windows и могут выйти за пределы рабочей папки. «Всегда» для `команда: git` разрешает любую команду git. Нажимай «Всегда» только для того, чему доверяешь.

## Лицензия

MIT