file-analysis-mcp

Персональный MCP-сервер, который читает неструктурированные документы (PDF, PPTX, DOCX, SVG, PNG и другие изображения) в указанной папке и передаёт исходный текст/изображения как есть, чтобы вызывающий хост (Claude Code, Codex CLI и т.п.) мог выполнить сводку содержимого и анализ структуры папки.

Этот сервер не выполняет сводку напрямую — он лишь извлекает текст и возвращает изображения как есть; фактическую сводку выполняет LLM (Claude Code/Codex), вызвавший этот инструмент. Отдельный API-ключ не требуется.

Предоставляемые инструменты

• list_folder_structure(path, max_depth=5) Рекурсивно обходит указанную папку и возвращает в JSON древовидную структуру, количество файлов по расширениям и общий объём.

• read_document(path, max_chars=20000, max_pages=30) Извлекает содержимое в зависимости от расширения и возвращает его в виде текста/изображения.

  • .pdf → текст постранично

  • .pptx → текст по слайдам + заметки

  • .docx → текст абзацев/заголовков/таблиц

  • .svg → исходный XML + растеризованное PNG-изображение (если возможно)

  • .png / .jpg / .jpeg / .bmp / .gif / .webp → изображение как есть (после изменения размера)

Related MCP server: File Context MCP Server

Установка

uv управляет и интерпретатором Python, и зависимостями.

cd file-analysis-mcp
uv sync

Локальное тестирование (MCP Inspector)

npx @modelcontextprotocol/inspector uv run --directory . python server.py

В открывшемся в браузере интерфейсе Inspector можно напрямую вызывать list_folder_structure и read_document. В папке test_samples/ подготовлены образцы файлов PDF/PPTX/DOCX/SVG/PNG, так что можно сразу тестировать.

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

claude mcp add file-analysis -s user -- uv run --directory "C:\Users\20210\Desktop\testmcp\file-analysis-mcp" python server.py

Уже зарегистрирован указанной выше командой в области пользователя (user scope) и доступен во всех проектах. Новые MCP-серверы загружаются при запуске сессии, поэтому необходимо перезапустить Claude Code (или начать новую сессию), чтобы инструменты появились. Проверка статуса регистрации: claude mcp list

Регистрация в Codex CLI

codex mcp add file-analysis -- uv run --directory "C:\Users\20210\Desktop\testmcp\file-analysis-mcp" python server.py

Уже зарегистрирован глобально (global). Проверка: codex mcp list

Пример использования (в новой сессии после регистрации)

При запросе

«Проанализируй структуру папки C:\Users\me\Documents\보고서 и обобщи документы в ней»

Claude Code/Codex сначала определит структуру с помощью list_folder_structure, затем вызовет read_document для нужных файлов, прочитает содержимое и сам выполнит сводку.

Примечания / ограничения

• Путь передаётся аргументом при каждом вызове, поэтому ограничения доступа к папкам (allowlist) не установлены. Предполагается личное использование в доверенном локальном окружении.

• Длина текста ограничена параметром max_chars, а PDF — параметром max_pages, чтобы предотвратить переполнение контекста. Если нужно более длинное содержимое, увеличьте значения при вызове.

• Растеризация SVG (svglib) может не полностью поддерживать некоторые сложные функции SVG (фильтры, часть градиентов и т.п.). Даже при сбое исходный XML-текст возвращается всегда.