# G connect

Универсальное ядро доступа агента к Google Drive / Docs / Sheets и к локальным папкам,
одинаково работающее из Cursor, Claude Desktop, Claude Code и любого другого MCP-клиента.

Два равноправных контура:

- **читающий** — агент видит и анализирует документы, листы, файлы на Диске и расшаренное
  (карта файла, профиль колонок, сканирование корпуса с бюджетом и индексом);
- **пишущий** — правки вместе с человеком: превью до записи, адресация по именам колонок,
  уточняющий вопрос вместо догадки, откат в пределах сессии.

Ядро универсально: работает с произвольной таблицей и документом без предварительной
настройки. Привязка к конкретным таблицам и рецепты — оверлей поверх ядра.

**Мозг подключаемый.** Один и тот же механизм работает в трёх режимах: агент в чате или
IDE (Claude Code, Cursor, Claude Desktop — модель у клиента, доступ через MCP), локальная
модель (Ollama) через собственный агент-раннер, и любая модель по API-ключу через тот же
раннер. Правила работы с документами лежат в репозитории (`policy/`) и доходят до всех
трёх режимов из одного места; машинная часть правил исполняется в ядре — то есть работает
даже если модель правило проигнорировала.

**UI — для локальной модели и для работы по API-ключу.** Там, где нет чата, панель на
`127.0.0.1` держит весь контур в одном окне: задача, шаги раннера, превью диффа,
уточняющий вопрос, применить / откатить, история. В чате и IDE интерфейсом служит сам
чат, и дублировать его формой не нужно. Подключение Google — кнопкой (обмен кода на токен
делает ядро, секреты в браузер не попадают), ключ провайдера — полем с проверкой пробным
вызовом. Ошибки приходят человеку названием проблемы и кнопкой действия, а не кодом.

## Документы

- [DESIGN.md](DESIGN.md) — дизайн: решения D-1…D-10, контракт инструментов, план работ.
- [delivery/](delivery/) — процессный контур поставки (Agent Delivery Harness).
- [delivery/LIVE-RUN.md](delivery/LIVE-RUN.md) — живой прогон вторым агентом: зачем, три
  роли, чего он не заменяет. Практика проекта, а не часть канона.
- [AGENTS.md](AGENTS.md) — что читать агенту перед работой.

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

Сначала собрать: `npm ci && npm run build`. Профиль Google уже должен существовать
(`~/.gconnect/<account>/` с `credentials.json`; вход — `npm run gc -- login`).

**Claude Code / VS Code** — конфиг уже в репозитории: [.mcp.json](.mcp.json).
Открой проект и перезапусти клиент.

**Cursor** — `.mcp.json` он не читает: Cursor смотрит `.cursor/mcp.json` в проекте либо
`~/.cursor/mcp.json` глобально. Нужен **проектный** файл, чтобы сервер был виден только
здесь; в репозиторий он не положен, потому что путь машинно-зависимый:

```json
{
  "mcpServers": {
    "g-connect": {
      "command": "node",
      "args": ["/абсолютный/путь/к/G connect/dist/mcp/server.js"],
      "env": { "GCONNECT_ACCOUNT": "default" }
    }
  }
}
```

Путь абсолютный намеренно: рабочий каталог, из которого клиент запускает процесс, не
гарантирован. Дальше — Settings → Tools & MCP, включить `g-connect`; чат в режиме Agent.

**Claude Desktop** — в `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "g-connect": {
      "command": "node",
      "args": ["/абсолютный/путь/к/G connect/dist/mcp/server.js"],
      "env": { "GCONNECT_ACCOUNT": "default" }
    }
  }
}
```

Проверка, что клиент видит сервер: в списке инструментов должно быть ровно шесть —
`gc_targets`, `gc_read`, `gc_search`, `gc_scan`, `gc_apply`, `gc_undo`, — и ресурс
`policy://rules` с правилами работы с документами.

## Состояние

Фаза 1 (ядро) закрыта и заархивирована: профили и OAuth, типизированные ошибки, карта
листа, профиль колонок, резолвер целей и колонок, `appendRow` / `upsertRow` / `setCells`.

Фаза 2 (MCP) — слайсы 1–4 сделаны: stdio-сервер с шестью инструментами, политика из 20
машинных правил и ресурс `policy://rules`, журнал и откат, HTML-превью «было → станет»,
сборка `dist/`. 190 тестов, мутационный гейт 58% при пороге 50.

Открыто: живой прогон одной формулировки во втором клиенте (B13, Cursor) и передача
поставки. Порядок дальнейших работ — DESIGN.md §16.

## Лицензия

Не определена.