file-analyzer-mcp

Персональный stdio MCP-сервер, который извлекает только текст/структуру из PDF·DOCX·PPTX·SVG·PNG в локальной папке. Он не делает резюме и не интерпретирует — читать и обобщать извлечённые результаты — задача хост-LLM (например, Claude Code), который вызывает этот инструмент.

Что делает / чего не делает

Related MCP server: Visual Document Forensics MCP Server

Пример запуска

> read_document("quarterly-report.pdf")
{
  "type": "pdf",
  "num_pages": 12,
  "text": "Q3 Revenue Summary\n..."
}

> read_document("../../etc/passwd")
{ "error": "'../../etc/passwd' resolves outside the allowed root folder" }

Быстрый старт

git clone https://github.com/saewookkangboy/fileanalyzer_mcp_testmonial.git
cd fileanalyzer_mcp_testmonial
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
brew install tesseract   # PNG OCR용 (한국어는 brew install tesseract-lang 추가)

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

claude mcp add file-analyzer --env FILE_ANALYZER_ROOT=/분석할/폴더 -- \
  "$(pwd)/.venv/bin/python" "$(pwd)/server.py"
claude mcp list   # ✔ Connected 확인

После регистрации в новом сеансе запросите «резюмируй документы в этой папке» — и Claude напрямую вызовет следующие 3 инструмента.

Инструменты (Tools)

Структура проекта

server.py                    # FastMCP 앱 진입점, 툴 등록, 루트 폴더 검증
file_analyzer/
  security.py                #  경로 격리(resolve_safe_path), 크기 제한
  timeout.py                 #  추출 작업 하드 타임아웃
  audit.py                   #  로컬 감사 로그(logs/audit.jsonl)
  tree.py, metadata.py       #  list_directory / get_file_metadata 로직
  extractors/                #  pdf · docx · pptx · svg · image(OCR) 추출기
tests/                       # pytest 회귀 스위트
AGENTS.md                    # 호출 에이전트(Claude Code)를 위한 운영 지침

Безопасность и ограничения

Наблюдаемость — журнал аудита

Каждый вызов инструмента записывается отдельной строкой только локально в logs/audit.jsonl (без внешней передачи).

{"timestamp": "2026-08-26T06:03:35Z", "tool": "read_document", "params": {"relative_path": "report.pdf"}, "status": "ok", "duration_ms": 251.3}

Чтобы очистить журнал, удалите logs/audit.jsonl.

Разработка

pip install -e ".[dev]"
pytest -q

tests/ охватывают блокировку выхода за пределы путей и инъекции абсолютных путей, 5 типов экстракторов, таймауты, журнал аудита и интеграцию сервера. Для масштаба этого проекта мы решили, что локального запуска pytest без CI-пайплайна достаточно для регрессионной проверки, и поддерживаем это так.

Почему такая архитектура

• Нет функции резюме — чтобы работать без отдельного ключа LLM API, выбрана минимальная структура: извлечение делает сервер, резюме — хост.

• PNG — это OCR, а не передача vision — вместо передачи изображения хосту в base64 извлекается только текст, что снижает объём возвращаемых данных и сложность реализации (визуальный смысл рисунков не виден).

• Только локальный pytest без git/CI — для масштаба личного локального инструмента CI-инфраструктура избыточна.

Известные ограничения

• Таймаут основан на потоках, поэтому фоновый поток превышенного вызова может продолжать выполняться до конца даже после возврата результата.

• .ppt не поддерживается — конвертируйте в .pptx перед использованием.

Лицензия

Это личный проект без отдельного файла лицензии.