Файловый анализ MCP (file-insight-mcp)

Это персональный локальный MCP-сервер, который читает неструктурированные документы в указанной папке, анализирует их структуру, составляет сводку по каждому документу и итоговый сводный отчёт по всей папке.

Все документы в data/sample_docs/ этого пакета — синтетические данные, созданные для демонстрации.

Справочная основа

• Структура сервера (FastMCP, stdio, комбинация нескольких MCP-серверов): https://github.com/kyopark2014/mcp

• Соглашения harness (поэтапные stage/next_actions, якоря обоснования, границы одобрения): переиспользуется подход, выработанный в проекте personal-meeting-mcp-training той же серии

• Список принципов harness-инжиниринга: https://github.com/walkinglabs/awesome-harness-engineering (пункты о бюджете контекста, хуках предварительного одобрения, детерминированном eval и статическом сканере безопасности применены выборочно под масштаб этого проекта)

• MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk

Related MCP server: file-analyzer

Что делает этот сервер

1. Сканирует структуру фиксированной целевой папки (data/sample_docs/).

2. Читает только документы с разрешёнными расширениями (.txt .md .csv .log).

3. Извлекает из документов оглавление (структуру заголовков), кандидатов в даты, числовые значения и ключевые термины на основе правил.

4. Составляет сводный промпт, объединяющий все документы. Саму сводку пишет хостовая LLM (Claude/Codex), а этот MCP не вызывает LLM API.

5. Проверяет структуру составленного сводного отчёта и сверяет, что упомянутые в нём имена файлов действительно существуют.

6. Сохраняет отчёт в файл только после явного одобрения пользователя.

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

Требуемое окружение: Python 3.11 или новее, uv

uv sync --extra dev

После установки убедитесь, что все четыре команды из раздела Проверка ниже проходят успешно.

Чтобы визуально проверить инструменты через MCP Inspector:

uv run mcp dev src/file_insight_mcp/server.py

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

Доменная логика и соглашения об инструментах разделены, чтобы при изменении правил проверки не затрагивать слой инструментов.

Рекомендуемый поток

SCAN → LIST → READ → EXTRACT → DRAFT → CHECK → PREVIEW → [사용자 승인] → SAVED

Ресурсы и промпты

Проектирование harness

Этот сервер рассматривает как объект проектирования не только функциональность, но и способ, которым модель использует инструменты.

• В каждом ответе есть stage и next_actions, поэтому модель выбирает следующий инструмент, глядя только на ответ. blocking: true — это подсказка «не пропускай этот этап». Фактически сохранение блокируют проверка структуры и токен одобрения; подсказка не берёт на себя эту роль.

• Ошибки возвращаются через ToolFailure вместе с кодом причины, способом восстановления и доступными вариантами. Цель — чтобы модель могла восстановиться сама, не переспрашивая.

• Схемы аргументов остаются плоскими ({"relative_path": "..."}). Если использовать Pydantic-модель как тип аргумента, она вложится как {"params": {...}}, и форма вызова изменится.

• Возвращаемые значения — Pydantic-модели, поэтому outputSchema генерируется автоматически.

• Все инструменты снабжены readOnlyHint / destructiveHint, чтобы хост мог показывать другой UI одобрения для инструментов записи.

• Сохранение блокируют только надёжные проверки (структура), а эвристические проверки (сверка имён файлов) лишь сообщаются как предупреждения.

Бюджет контекста

Следуя принципу «окно контекста — это не место для выброса, а бюджет рабочей памяти», все инструменты имеют явные верхние пределы размера ответа.

• scan_folder_structure: при превышении MAX_SCAN_ENTRIES (500) сообщает truncated: true и обрезает.

• read_document: файлы больше MAX_FILE_BYTES (200 КБ) целиком не читаются; вместо этого возвращается ошибка с указанием читать частями через read_document_chunk.

• extract_key_terms: ограничивает количество элементов по категориям через max_terms.

• preview_save_report: по умолчанию include_preview=False, поэтому уже имеющийся черновик не дублируется в ответе. Когда включить нужно, длина ограничивается через max_preview_chars.

• harness.truncate() / harness.number_lines(): всегда явно указывают факт обрезки и якоря цитирования (номера строк), чтобы модель не гадала, «это целиком или часть».

Границы безопасности

• Сервер работает только с одним security.TARGET_DIR (data/sample_docs/). Доступ наружу невозможен даже через .., абсолютные пути, буквы дисков или символические ссылки (security.safe_relative_path).

• Файлы вне allowlist расширений (.txt .md .csv .log) не читаются. Исполняемые/скриптовые расширения всегда исключаются из рассмотрения.

• Если размер файла превышает MAX_FILE_BYTES (200 КБ), файл целиком не читается; вместо этого возвращается ошибка.

• Скрытые файлы и папки, имя которых начинается с ., исключаются из сканирования.

• Инструмент записи только один — save_approved_report, и он срабатывает лишь при совпадении хэш-токена (report_id, текст), выданного preview_save_report.

• Этот сервер только читает документы. Если в исходный код попадут вызовы выполнения кода или shell-команд, такие как eval/exec/subprocess, scripts/validate_package.py завершится с ошибкой.

Проверка

uv run pytest -q
uv run python scripts/smoke_stdio.py
uv run python scripts/run_evals.py
uv run python scripts/validate_package.py

Роли четырёх команд различны, поэтому должны пройти все.

run_evals.py содержит весь поток сохранения, включая случаи, когда сохранение при правильном токене одобрения успешно, а при неправильном — отклоняется. При каждом исправлении ошибки в evals/cases.jsonl добавляется одна строка с кейсом, воспроизводящим эту ошибку. Синтаксис кейсов описан в evals/README.md.

Если нужно анализировать другую папку

В целях безопасности этот проект фиксирует целевую папку в TARGET_DIR (папка data/sample_docs/ внутри пакета) в src/file_insight_mcp/security.py. Чтобы анализировать реальную рабочую папку:

1. Замените TARGET_DIR на нужный абсолютный путь или измените код так, чтобы он внедрялся через переменную окружения.

2. Отразите в ALLOWED_EXTENSIONS расширения, которые реально есть в этой папке.

3. Сначала убедитесь, что в папке нет чувствительных подпапок (учётные данные, персональные данные и т.п.).

Подключение к Claude Desktop

Замените ABSOLUTE_PROJECT_PATH в config/claude_desktop_config.example.json на абсолютный путь к этой папке и примените в настройках Claude Desktop. После этого приложение нужно полностью закрыть и запустить заново.

Принципы проектирования

• MCP не вызывает отдельный LLM API. Сводные предложения создаёт Claude или Codex, а этот MCP отвечает за исходный текст, структуру, проверку и сохранение.

• Не выдумываются имена файлов, числа и даты, не подтверждённые в документах; проверка обоснованности сверяет их механически.

• Для окончательного сохранения требуются и токен одобрения, выданный при предпросмотре, и явное одобрение пользователя.

• Доменная логика (core, outline, grounding) отделена от соглашений об инструментах (server, harness, security).