file-analysis-mcp

Личный локальный MCP, который читает неструктурированные документы (pdf, docx, pptx, txt, svg, png, csv, xlsx) в указанной папке, анализирует их структуру и не сохраняет ничего без одобрения.

Пример реальной работы

Это реальные результаты запуска на включённой папке с синтетическими образцами (sample_docs/).

list_folder_contents()
→ count: 8, entries: data.csv, diagram.svg, notes.docx, photo.png,
  readme.txt, report.pdf, sheet.xlsx, slides.pptx

describe_file(relative_path="slides.pptx")
→ {"slide_count": 3, "slide_titles": ["팀 소개", "구성원", "다음 스프린트"]}

Отчёт, составленный на основе реального чтения этих файлов, находится в data/outputs/onboarding-overview-report.md — он прошёл проверку структуры VALID и проверку обоснованности имён файлов GROUNDED (100 баллов).

Я также проверил на реальной папке с учебными материалами (PPTX, 9 МБ, 16 слайдов) и в процессе обнаружил и исправил баг: при попытке прочитать файл блокировки (~$*.pptx), который создаётся, пока PowerPoint открыт, исключение библиотеки форматов вылетало как есть. Теперь это обрабатывается как ошибка с кодом причины и способом восстановления.

[INVALID_REQUEST] '~$파일.pptx' 파일을 열지 못했습니다: Package not found ...
복구 방법: list_folder_contents로 파일 목록과 지원 형식을 다시 확인하세요.

Related MCP server: local-docs-mcp

Что это

Указываете одну папку — он читает документы внутри, сначала определяет структуру (число страниц/слайдов/листов) и помогает составить сводный отчёт. 8 форматов обрабатываются отдельными парсерами (pypdf/python-docx/python-pptx/openpyxl/Pillow).

Чем отличается

• MCP не вызывает LLM. Фактические предложения сводки пишет Host (Claude/Codex). Сервер отвечает только за запрос данных, анализ структуры, проверку и сохранение.

• Перед сохранением требуются и токен одобрения, и явное одобрение пользователя. Инструмент записи только один — save_approved_report, остальные 10 — только для чтения.

• PNG передаётся как настоящее содержимое изображения, без OCR. Vision-способности Host видят и интерпретируют его напрямую.

• Ошибки всегда возвращаются вместе с кодом причины + способом восстановления + допустимыми значениями (см. пример выше).

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

list_folder_contents → describe_file → read_file_text(또는 read_image_file)
  → build_summary_prompt → validate_report_draft → check_report_grounding
  → preview_save_report → [사용자 승인] → save_approved_report

Начало работы

python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"
.venv/Scripts/python scripts/generate_samples.py
.venv/Scripts/python -m pytest -q
.venv/Scripts/python scripts/smoke_stdio.py

Анализ реальной папки

По умолчанию используется sample_docs/. Достаточно изменить одну переменную окружения перед запуском сервера.

FILE_ANALYSIS_ROOT="D:\내 문서 폴더" .venv/Scripts/python src/file_analysis_mcp/server.py

Чтобы зарегистрировать в Codex CLI:

codex mcp add file-analysis --env FILE_ANALYSIS_ROOT="D:\내 문서 폴더" -- \
  "<프로젝트경로>\.venv\Scripts\python.exe" "<프로젝트경로>\src\file_analysis_mcp\server.py"

Ограничения

• Изображения не проходят OCR. Вместо извлечения текста содержимое изображения передаётся Host как есть.

• Для файлов больше 20 МБ доступна только проверка структуры, содержимое прочитать нельзя.

• check_report_grounding — эвристика на основе регулярных выражений, поэтому возможны ложные срабатывания (это лишь консультация и не блокирует сохранение).

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

Базовый паттерн

Следует тем же принципам проектирования, что и personal-meeting-mcp-training (разделение слоёв, stage/next_actions, границы одобрения). Подробные контракты инструментов см. в docstring каждого модуля в src/file_analysis_mcp/.