local-docs-mcp

Персональный MCP-сервер, который читает документы на локальном ПК и помогает с их резюмированием и упорядочиванием. Извлекает текст из PDF, Word, Excel, PowerPoint, HWP, Markdown, CSV и других форматов, а сохранение резюме и упорядочивание файлов выполняет с процедурой подтверждения.

• Не использует сеть. API-ключи не требуются.

• Резюме пишет не этот сервер. Он точно извлекает исходный текст, а резюме составляет Claude. (machine_keypoints, которые выдаёт сервер, — это частотная машинная выжимка, а не резюме.)

• За пределами разрешённых папок чтение невозможно. Перемещение или сохранение файлов всегда требует подтверждения.

Поддерживаемые форматы

.doc, .xls, .ppt (старые бинарные форматы) не читаются; сервер подсказывает «сохраните в формат с x».

Related MCP server: Knowledge Assistant MCP

Установка

Требуется Python 3.11 или новее.

python -m venv .venv && .venv/Scripts/pip install -e ".[formats,dev]"

На macOS и Linux используется .venv/bin/pip. [formats] дополнительно устанавливает pypdf для PDF и olefile для .hwp (бинарного); без них остальные форматы всё равно работают.

Регистрация в Claude Code

<PROJECT_DIR> — это абсолютный путь к клонированному репозиторию, <HOME> — домашняя папка пользователя.

claude mcp add local-docs --scope user --env DOCS_MCP_ROOTS="<HOME>/Desktop;<HOME>/Documents" --env DOCS_MCP_OUTPUT="<HOME>/Desktop/docs-mcp-out" -- <PROJECT_DIR>/.venv/Scripts/python.exe -m docs_mcp.server

Если сервер нужен только внутри этого репозитория, скопируйте .mcp.json.example в .mcp.json и замените <PROJECT_DIR> и <HOME> на реальные пути. .mcp.json не отслеживается в репозитории, так как пути различаются на каждой машине.

Переменные окружения

11 инструментов

Инструменты регистрируются с разделением на read-only (R) и write (W), чтобы хост показывал разный UI подтверждения.

Рекомендуемый порядок действий

list_roots
  → scan_documents          어떤 문서가 있는지
  → outline_document        긴 문서는 뼈대부터
  → read_document           원문을 근거로 확보 (필요하면 이어 읽기)
  → (Claude가 요약 작성)
  → preview_save_summary    저장 내용 확인
  → [사용자 승인]
  → save_summary

Упорядочивание выполняется отдельно.

preview_organize   계획만 생성 — 파일은 하나도 건드리지 않음
  → [사용자가 계획 확인·승인]
  → apply_organize (기본 copy)
  → 문제가 있으면 undo_last_organize

Критериев упорядочивания четыре.

Механизмы безопасности

1. Блокировка путей — все входные пути проверяются через resolve(), затем проверяется, что они внутри разрешённых корней. .., символические ссылки и переходы между дисками блокируются здесь же.

2. Блокировка записи — сохранение возможно только внутри выходной папки. В корни чтения запись не выполняется.

3. Исключённые папки — .git, node_modules, .venv, AppData и т.п. не просматриваются и не читаются.

4. Токен подтверждения — это хэш содержимого предпросмотра. Если содержимое изменится хотя бы на один символ, токен ломается, и сохранение или упорядочивание отклоняется. Однако токен гарантирует только техническую целостность и не заменяет подтверждение пользователя.

5. По умолчанию — копирование — перемещение оригинала возможно только при DOCS_MCP_ALLOW_MOVE=1.

6. Никакого удаления — откат тоже не удаляет файлы, а перемещает их в папку _trash.

Проверка

.venv/Scripts/python.exe -m pytest -q

.venv/Scripts/python.exe scripts/smoke.py

.venv/Scripts/python.exe scripts/simulate.py

• pytest — извлечение по форматам, граничные проверки, поток подтверждения (модульные тесты)

• smoke.py — проверка через реальный stdio: initialize → tools/list → tools/call

• simulate.py — создаёт набор виртуальных документов и воспроизводит весь поток через реальное MCP-подключение. Создаются 12 виртуальных документов: протоколы совещаний, договоры, сметы, презентации, PDF, заметки в CP949 и т.д., затем выполняются обзор → сохранение резюме → упорядочивание → откат, и проверяется, что запрещённые действия (чтение вне корней, подделка токена, перемещение оригинала) действительно блокируются. Всё работает во временной папке и само удаляется по завершении. Чтобы сохранить результат, передайте папку аргументом.

Ограничения

• В отсканированных PDF-изображениях текста нет. OCR не выполняется, только предупреждение.

• Ячейки Excel с датами могут отображаться как внутренние серийные номера.

• .hwp (бинарный) — это наилучшее извлечение. Порядок таблиц и сносок может отличаться от оригинала.

• Текст внутри изображений не читается ни в одном формате.

Лицензия

MIT — LICENSE