# MCP-ассистент — руководство оператора

Локальный офлайн-ассистент на базе MCP: работа с файлами, памятью, офисными
документами, PDF, кодом, базами данных, вебом и когнитивными движками.
Проект живёт в одной папке (по умолчанию `C:\Tools`) и переносится на другой
компьютер целиком. **338 инструментов**, ~65 серверных модулей. Интернет нужен
для веб-поиска и сетевых модулей (email — `send_email`/`fetch_emails`, загрузка
страниц/файлов, RSS, облачная синхронизация); всё остальное работает офлайн.

---

## 1. Установка на новом компьютере

Запустите `setup.bat` и выберите пункт меню:

- **1. Full automatic setup** — скачать переносимый Python + инструменты и
  установить все зависимости (нужен интернет один раз).
- Пошагово: **3** (скачать Python + инструменты) → **4** (установить из
  локального комплекта) → **7** (доустановить недостающие зависимости).
- Полностью офлайн (если пакеты уже скачаны на другом ПК): **5** заранее
  скачивает пакеты в `python_deps`, затем на целевом ПК — **6** (установка из
  `python_deps`) и **4**.
- **8** — зависимости RAG и полнотекстового индексирования (chromadb,
  sentence-transformers и т.д.).
- **9** — когнитивные плагины (граф, модель мира, гипотезы, эпизодическая память).
- **B** — автогенерация конфигурации LM Studio с переносимыми путями.
- **C** — создать файл `.env`.

После установки: **D** — запустить/остановить сервер; **E/F** —
добавить/убрать из автозапуска.

## 2. Проверка работоспособности

Пункт меню **H — Run self-test** (или `python selftest.py`).
Самопроверка использует временные БД (реальные данные не трогает), импортирует
все серверы и прогоняет ключевые пути: файловые операции + граница безопасности,
выполнение Python, PDF, защита от повторов/галлюцинаций, инструменты БД, память,
рефлексия, плагины, оркестратор, кэш поиска, планировщик. Норма — `FAIL=0`
(`SKIP` означает «пакет не установлен», не ошибку).

Сверка промпта с инструментами: `python check_prompt_tools.py`.
Общий статус системы (в чате): инструмент `health_check`.

## 3. Перенос на другой компьютер

Два способа:

1. **Целиком**: остановите сервер (**D**) и скопируйте всю папку `C:\Tools` на
   другой ПК. На целевом — `setup.bat` → **4** (или **6**+**4**), затем **B**.
2. **Только состояние** (память, граф, цели, планы и т.д.): в чате вызовите
   `backup_state` — получите один zip со снимком всех БД. На целевом ПК
   положите zip и вызовите `restore_state(archive_path, confirm=true)`
   (перед перезаписью он сам сделает резервную копию текущего состояния).
   Восстановление делайте при **остановленном** сервере.

## 4. Что умеет (ключевые инструменты)

- **Файлы**: `read_file`, `write_file`, `move_file`, `copy_file`, `delete_file`,
  `search_files`, `search_content`, `find_duplicates`, индексирование.
- **Офис**: `read_docx/read_excel/read_pptx`, `create_docx`, `excel_set_cell`
  (поддерживает формулы вида `=SUM(A1:A2)`), `excel_sort`, `docx_replace_text`,
  `pptx_add_slide`, `export_to_pdf`.
- **PDF**: `read_pdf`, `pdf_info`, `merge_pdfs`, `extract_pages`, `create_pdf`.
- **Код / вычисления**: `run_python`, `run_python_file`, `calc`, `list_packages`.
- **Базы данных**: `sql_query` (SELECT свободно; запись — `allow_write=true`),
  `list_tables`, `db_info`, `optimize_all_databases` (VACUUM всех БД).
- **Командная строка**: `run_shell`.
- **Веб/браузер**: `web_search`, `fetch_url`, `fetch_dynamic_js`,
  `capture_screenshot`, `webpage_to_pdf`, `download_file`, `read_rss`.
- **Память**: `smart_search`, `mem_query`, `mem_search_dialogs`,
  `mem_search_archive`, `explain_fact`, `verify_fact`, `merge_duplicate_facts`.
- **Граф знаний / когнитивные**: `graph_query_facts`, `graph_get_beliefs`,
  цели/планы/гипотезы/модель мира.
- **Надёжность**: `check_grounding` (проверка факта по памяти),
  `check_repetition` (защита от повторов).
- **Обслуживание**: `health_check`, `backup_state`, `mem_optimize`,
  `optimize_all_databases`.

## 5. Надёжность (защита от галлюцинаций и повторов)

Промпт инструктирует модель: перед утверждением неуверенного факта вызывать
`check_grounding` (вердикт `unknown` → не выдавать за факт; `contradicted` →
предупредить); при подозрении на повтор — `check_repetition`; для вычислений —
`calc`/`run_python`, а не «в уме». Рефлексия периодически повышает confidence
подтверждённых фактов и помечает противоречия; `merge_duplicate_facts`
схлопывает дубли.

## 6. Обслуживание баз данных

- `optimize_all_databases` — сжатие (VACUUM) и ANALYZE по всем БД проекта.
- `mem_optimize` — то же для основной БД памяти + очистка кэша чанков.
- `mem_purge_archive` — очистка архива старых записей.
- `merge_duplicate_facts(dry_run=true)` — предпросмотр слияния дублей; затем
  `dry_run=false` для применения.

## 6a. OCR отсканированных PDF (русские документы)

`read_pdf` сам распознаёт сканы (страницы-изображения без текстового слоя),
если установлены:
1. Python-пакеты `pypdfium2` и `pytesseract` (входят в зависимости, ставятся
   установщиком).
2. **Программа Tesseract-OCR** (отдельный бинарник, не pip):
   - Windows: установщик от UB Mannheim. При установке **отметьте русский язык**.
   - Сервер ищет tesseract автоматически в `C:\Program Files\Tesseract-OCR\`,
     `Program Files (x86)`, `%LOCALAPPDATA%` — PATH править не обязательно.
     Можно явно указать путь переменной `MCP_TESSERACT_CMD`.
   - Для кириллицы нужен языковой пакет `rus` (файл `rus.traineddata` в папке
     `tessdata`). Без него русский текст распознаётся плохо.

Если Tesseract не найден, `read_pdf`/`ocr_pdf` вернут понятную подсказку, а не
пустой результат. Принудительный OCR: `ocr_pdf(path)`; язык по умолчанию
`rus+eng`.

## 6b. Веб-поиск без капч (SearXNG / Brave)

Чтобы поиск был стабильным и не упирался в капчи, используйте источники с
официальным доступом, а не парсинг выдачи:

- **SearXNG** (рекомендуется, без ключей): поднимите свой инстанс (Docker:
  `searxng/searxng`), включите в его `settings.yml` вывод JSON (`formats: [json]`),
  и укажите адрес в переменной `MCP_SEARXNG_URL` (по умолчанию
  `http://localhost:8888`). Затем ищите с источником `searxng`:
  `web_search_enhanced(query, sources=["searxng"])`. Капч нет.
- **Brave Search API** (простой ключ, щедрый лимит): получите ключ и задайте
  `BRAVE_SEARCH_API_KEY`. Источник `brave`.
- Можно комбинировать: `sources=["searxng","brave","duckduckgo"]` — результаты
  объединяются и дедуплицируются.

Обход Cloudflare/капч и парсинг Google в обход защиты НЕ используются и не
поддерживаются: это и нестабильно, и нарушает правила сайтов. SearXNG/Brave дают
тот же результат без этих проблем.

**Уточнение про `fetch_dynamic_js(bypass_cloudflare=True)`:** этот режим только
*ожидает*, пока JS-челлендж Cloudflare пройдёт сам (плюс эмуляция обычного
браузера: ротация User-Agent, маскировка `navigator.webdriver`). Он НЕ решает
капчи и не «продавливает» защиту; авто-переключения на него при блокировке тоже
нет — вызывается только вручную. Если стоит реальная капча — вернётся страница
как есть.

### Источники в smart_search
`smart_search` умеет искать сразу по нескольким источникам, включая веб-движки:
`smart_search(query, sources=["searxng","brave","memory","kb"])`. Движки
`searxng`/`brave`/`duckduckgo` передаются в `web_search_enhanced`.

### Переменные окружения (веб и не только)
- `MCP_SEARXNG_URL` — адрес инстанса SearXNG (по умолч. `http://localhost:8888`);
  `MCP_SEARXNG_LANG` — язык результатов.
- `BRAVE_SEARCH_API_KEY` — ключ Brave Search API.
- `MCP_USER_AGENT` — зафиксировать свой User-Agent (иначе ротация из списка).
- `MCP_PROXY` — прокси для веб-запросов (`http://[user:pass@]host:port`).
- `MCP_TESSERACT_CMD` — путь к tesseract (если не в PATH).
- `MCP_RAG_EMBEDDING_MODEL` (по умолч. `all-MiniLM-L6-v2`), `MCP_RAG_DB_PATH` — RAG.
- `MCP_OFFLINE_MODE` (`auto`/`force_offline`), `MCP_ALLOWED_PATHS`,
  `MCP_CODE_EXEC_DIR`, `MCP_BACKUP_DIR`.

### Обслуживание кэшей поиска
- `clear_search_cache(older_than_days=N)` — очистить кэш результатов поиска
  (`~/.mcp_search_cache.db`); без аргумента — весь.
- `clear_web_cache(older_than_days=N)` — очистить кэш сохранённых страниц
  (`~/.mcp_web_cache.db`, FTS5); без аргумента — весь.

### Полнотекстовый поиск по офисным файлам
- `index_office_files(folder)` — построить индекс по DOCX/XLSX/PPTX в папке;
- `search_indexed_office_files(query)` — искать по содержимому проиндексированных
  офисных файлов (работает офлайн).

## 7. Диагностика

- Сервер не стартует / «Python not found» → выполните пункты **3** и **4**.
- RAG/индексатор пропускаются (`SKIP` в self-test) → установите зависимости
  пунктом **8** (нужны `chromadb`, `sentence-transformers`).
- Создание PDF не работает → нужен `reportlab` (входит в зависимости, ставится
  пунктами **1/5+6**).
- Общая картина: `health_check`; полная проверка: пункт **H**.

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

- `run_python`, `run_python_file`, `run_shell` выполняют **реальный код** на
  машине. Это ожидаемо для локального ассистента, но учитывайте при автоматизации.
- Файловые операции ограничены списком разрешённых путей
  (`MCP_ALLOWED_PATHS`, по умолчанию — доступные диски). Запись вне списка
  блокируется.
- `restore_state` и `merge_duplicate_facts(dry_run=false)` изменяют данные —
  требуют явного подтверждения.

---

*Проверка качества: `selftest.py` (пункт H) и `check_prompt_tools.py`. Норма —
`FAIL=0`. После любых изменений в коде или промптах прогоняйте обе проверки.*