file-analyzer-mcp

Доказательство

Укажите папку — и он вернёт настоящее дерево, а не догадку:

$ analyze_folder_structure({ "folder_path": "tests/fixtures" })

{
  "status": "OK",
  "file_count": 6,
  "supported_file_count": 6,
  "extension_stats": [
    { "extension": ".pdf",  "count": 2, "bytes": 723995 },
    { "extension": ".docx", "count": 1, "bytes": 35505 },
    { "extension": ".pptx", "count": 1, "bytes": 33067 },
    { "extension": ".svg",  "count": 1, "bytes": 319 },
    { "extension": ".png",  "count": 1, "bytes": 74 }
  ],
  "tree_text": "fixtures/\n├── sample.docx (34.7KB)\n├── sample.pdf (431B)\n├── sample.png (74B)\n├── sample.pptx (32.3KB)\n├── sample.svg (319B)\n└── sample_scanned.pdf (706.6KB)"
}

Затем прочитайте один из файлов — заголовки, абзацы и таблицы возвращаются структурированными, а не сплющенными:

$ read_docx({ "file_path": "tests/fixtures/sample.docx" })

{
  "status": "OK",
  "headings": ["테스트 문서"],
  "text": "테스트 문서\n본문 첫 문단입니다.",
  "tables": [{ "index": 0, "rows": [["A", "B"], ["1", "2"]] }]
}

Оба вызова воспроизводимы — клонируйте этот репозиторий, выполните uv sync --extra dev и вызовите их против tests/fixtures/ самостоятельно.

Related MCP server: Agent Helper

Что это

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

В этом вся суть: сервер извлекает, хост интерпретирует. В этом сервере нет ключа LLM API. PNG возвращается как содержимое изображения в base64, а не как подпись — его читает собственное зрение вашего хоста. Отсканированный PDF получает OCR только когда вы об этом просите.

Инструменты

Большие документы разбиваются на страницы: page_start/page_end для PDF, slide_start/slide_end для PPTX. Ограничения по умолчанию: 30 страниц / 60 слайдов — после этого в ответе next_actions сообщает следующий диапазон для запроса.

Установка

uv sync --extra dev

Зарегистрируйте в Claude Code:

claude mcp add -s user file-analyzer -- "<uv.exe path>" --directory "<this folder>" run python src/file_analyzer_mcp/server.py

В Windows, если uv был установлен через pip, его не будет в PATH у Claude — используйте полный путь к uv.exe (pip show uv чтобы найти его). Примеры для Claude Desktop и Codex находятся в config/: claude_code.example.md, claude_desktop_config.example.json, codex-config.example.toml.

Безопасность

Чувствительные пути отклоняются детерминированно — это не зависит от того, решит ли модель не читать их. См. paths.py.

Каждый вызов также аудируется — имя инструмента, аргументы и результат (успех или блокировка) добавляются в logs/audit.jsonl. См. audit.py. Сверх всего этого действует ограничение размера файла в 50 МБ.

Соглашения для тех, кто расширяет этот сервер, находятся в AGENTS.md.

Ошибки

Каждый сбой вызывает ToolFailure с кодом, понятным объяснением и способом восстановления — сообщение написано для вызывающей модели, чтобы она могла прочитать и действовать, а не только для человека.

OCR для отсканированных PDF

read_pdf(ocr=True) требует Tesseract:

winget install UB-Mannheim.TesseractOCR
uv run python scripts/setup_ocr.py   # copies eng/osd, downloads kor.traineddata

ocr_lang по умолчанию равен "kor+eng". Неверный путь к Tesseract? Установите TESSERACT_CMD.

Тестирование

uv run pytest -q                        # parser / path / audit unit tests
uv run python scripts/smoke_stdio.py    # real stdio round-trip against the server

Оба должны проходить, прежде чем изменение считается завершённым — pytest проверяет модули изолированно, а smoke-тест — единственный, кто задействует реальный протокол MCP и ловит поломки на уровне схемы.

Ограничения