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. После любых изменений в коде или промптах прогоняйте обе проверки.