file-analysis

Персональный локальный MCP, который читает неструктурированные документы (pdf docx pptx svg png) из указанной папки и помогает с кратким изложением основного содержания и анализом структуры файлов. Подключается к Claude Code · Codex · Claude Desktop.

Если один и тот же факт указан в двух местах, источником является AGENTS.md.

Этот сервер не делает резюме

Это самое важное проектное решение.

Если бы сервер делал резюме сам, ему пришлось бы снова вызывать модель со своим API-ключом, а хост получал бы только результат резюме и не мог бы сверить обоснование. Открывается путь, по которому неверное резюме тихо проходит. Поэтому сервер выдаёт только исходный текст и якоря.

Related MCP server: file-analyzer

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

Обязательное окружение: Python 3.11 и выше, uv

uv sync --extra dev

uv run python scripts/make_samples.py

uv run python scripts/smoke_stdio.py

Если smoke_stdio.py выдаёт PASS, сервер в порядке — он запускается по реальному протоколу MCP, проверяются 17 контрактов харнеса, и выполняется полный цикл от DISCOVER до SAVED.

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

uv run mcp dev src/file_mcp/server.py

Указание папки для анализа

Измените allowed_roots в config/roots.toml. Этот файл — граница безопасности сервера.

allowed_roots = [
  "data/samples",
  "C:/Users/<사용자>/Desktop/분석대상",
]

Не указывайте целиком родительские папки вроде C:/Users/<пользователь> — это практически то же самое, что отсутствие защиты. Сервер ни при каких обстоятельствах не открывает пути вне этого списка.

Подключение хоста

Claude Code

claude mcp add file-analysis -- uv --directory "<이-저장소를-클론한-절대경로>" run python src/file_mcp/server.py

Codex — в ~/.codex/config.toml вставьте содержимое config/codex-config.example.toml.

Claude Desktop — см. config/claude_desktop_config.example.json.

Конвейер

flowchart LR
    S["scan_folder<br/><i>추정 등급 B?</i>"] --> I["inspect_document<br/><i>확정 등급 A/B/C</i>"]
    I --> P["build_analysis_prompt<br/><i>앵커 붙은 원문</i>"]
    P --> D(["초안 작성<br/><i>호스트 모델</i>"])
    D --> G["check_summary_grounding<br/><i>GR-01 … GR-04</i>"]
    G --> V["preview_save_report<br/><i>승인 토큰 발급</i>"]
    V --> H{{"사람의 승인"}}
    H --> W["save_approved_report<br/><i>유일한 쓰기</i>"]

    classDef server fill:#ddf4ff,stroke:#54aeff,color:#1f2328
    classDef notserver fill:#ffffff,stroke:#afb8c1,stroke-dasharray:5 4,color:#656d76
    classDef write fill:#fff8c5,stroke:#d4a72c,color:#1f2328
    class S,I,P,G,V server
    class D,H notserver
    class W write

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

Инструмент записи только один — save_approved_report. Без токена утверждения запись не выполняется. scripts/smoke_stdio.py проверяет список инструментов записи, поэтому при добавлении новых инструментов нужно вместе обновлять и смоук-тест.

Класс определяется не расширением, а содержимым

flowchart TD
    X["파일"] --> Y{"확장자"}
    Y -->|"docx · pptx"| A["<b>등급 A</b><br/>구조까지"]
    Y -->|"png"| C1["<b>등급 C</b><br/>이미지 판독"]
    Y -->|"pdf"| PQ{"공백 제거 후 페이지 텍스트<br/>8자 이상?"}
    Y -->|"svg"| SQ{"내용 있는<br/>text 노드?"}
    PQ -->|"있음"| B1["<b>등급 B</b><br/>본문만"]
    PQ -->|"없음"| C2["<b>등급 C</b><br/>스캔 PDF"]
    SQ -->|"있음"| B2["<b>등급 B</b><br/>본문만"]
    SQ -->|"없음"| C3["<b>등급 C</b><br/>그림"]

    classDef ga fill:#dafbe1,stroke:#2da44e,color:#1f2328
    classDef gb fill:#ddf4ff,stroke:#54aeff,color:#1f2328
    classDef gc fill:#fff8c5,stroke:#d4a72c,color:#1f2328
    class A ga
    class B1,B2 gb
    class C1,C2,C3 gc

scan_folder не открывает файлы, поэтому не может определить класс. pdf·svg остаются B?, а inspect_document открывает и определяет. Не читайте B? в результатах сканирования как определённое значение.

Примеры размещены так, чтобы это доказывать — в 흐름도.svg есть узлы text, поэтому B, а 도형만.svg содержит только фигуры, поэтому C. Одно расширение, разные классы.

Читается зрением модели хоста. Никаких дополнительных зависимостей, точность корейского выше, чем у tesseract. Если понадобится офлайн-пакетная обработка, отдельно добавляется инструмент extract_text_ocr.

Сканированные PDF также читаются без растеризатора. Сканированная страница целиком является одним встроенным изображением, поэтому достаточно извлечь это изображение через pypdf — не нужны ни PyMuPDF (AGPL), ни бинарники poppler.

Страницы, нарисованные только векторами, извлечь нельзя; в этом случае ошибка PDF_PAGE_HAS_NO_IMAGE сообщает, что «человек должен сделать скриншот экрана». Пустой результат тихо не возвращается.

Он даёт только оглавление · количество блоков · количество символов · определённый класс и estimated_read_calls (количество вызовов, необходимых для чтения всего). Смысл его существования — предотвратить выливание текста 300-страничного PDF в контекст, чтобы узнать его структуру.

Стоимость открытия файла такая же, как у read_document — экономится не время, а контекст.

Соглашение о якорях цитирования

Единицы различаются по форматам, но интерфейс read_document один. Все форматы уплощаются в одномерный список блоков, поэтому достаточно использовать start/end. Что такое один блок, сообщает unit в ответе.

Если изменить формат якорей, нужно вместе обновить grounding.ANCHOR_PATTERN и золотой набор. При расхождении все корректные цитаты будут заблокированы ошибкой GR-02.

Что проверка обоснования может и не может подтвердить

• Цитирует ли предложение якорь — GR-01

• Существует ли этот якорь в документе — GR-02

• Есть ли числа·даты в исходном тексте цитируемого блока — GR-03

• Совпадает ли прямая цитата (в кавычках) с исходным текстом — GR-04

• Правильно ли резюме передаёт смысл исходного текста

• Не упущено ли что-то важное

• Является ли процитированный якорь подходящим (GR-05 — лишь подсказка по лексическому пересечению)

Прохождение не означает «правильно». Поле not_verifiable в ответе каждый раз явно указывает это ограничение — если притворяться, что непроверяемое проверено, человек поверит, что «раз прошло, значит верно», а это опаснее, чем отсутствие проверки.

Перефразирование исходного текста — это нормально. Проверка смотрит только на якоря, числа и прямые цитаты.

Шлюз сохранения

preview_save_report проверяет и структуру (ST-*), и обоснование (GR-*), и выдаёт токен утверждения только когда нет ни одной ошибки. Токен — это sha256(исходный относительный путь + черновик), поэтому изменение даже одного символа в черновике делает его недействительным — путь «сделать предпросмотр с чистым черновиком, а сохранить другой» блокируется.

save_approved_report полностью повторно проверяет шлюз. Он не верит словам модели о том, что предпросмотр прошёл.

Если существующий результат есть, он перезаписывается, а хэш предыдущего содержимого сохраняется в журнале аудита. Журнал аудита (data/outputs/_audit.jsonl) — append-only.

Иерархия харнеса (CAR)

Разделяется на три оси: Control–Agency–Runtime. Сначала определите, к какой оси относится файл, который вы меняете. Если ось неясна — это признак неправильного проектирования.

Подробные контракты по осям и направления зависимостей — в главе 2 AGENTS.md.

Прогресс (сколько уже прочитано) сервер не хранит. Им владеет модель, а сервер в next_actions лишь сообщает «продолжить с start=N». Поэтому сервер не имеет состояния, и инструментов записи остаётся ровно один — сохранение.

Самопроверка

Непосредственно перед возвратом ответа проверяются инварианты; при нарушении вместо неверного ответа выдаётся ошибка.

То, что здесь задерживается, — это не проблема пользовательского ввода, а баг сервера. Поэтому сообщение об ошибке говорит не «проверьте файл», а «это дефект сервера, остановите работу и сообщите».

Наблюдаемость

Каждый вызов инструмента сохраняется одной строкой в data/traces/YYYY-MM-DD.jsonl.

uv run python scripts/trace_report.py

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

Принуждение не соглашением, а кодом, проверяемым тестами (tests/test_trace.py). Если trace_dir находится внутри allowed_roots, трейс сам отключается — чтобы не загрязнять папку анализа собственными записями.

Все 8 инструментов чтения имеют readOnlyHint: True, но трейс пишет файлы.

Эта подсказка означает, что анализируемые документы не изменяются. Трейс — это журнал инструментирования вне allowed_roots, и через инструменты он не раскрывается. Через инструменты записи раскрывается только save_approved_report, и смоук-тест проверяет этот список.

Оценка

uv run python scripts/eval_extract.py

Сопоставляются ожидаемые значения из evals/golden/samples.json с фактическими результатами извлечения, результаты сохраняются в evals/reports/. pytest сообщает только «проходит ли сейчас», а этот отчёт фиксирует когда и что прошло.

Ожидаемые значения вручную записаны на основе того, что scripts/make_samples.py положил в файлы. Это не копия вывода экстрактора. Если подгонять золотой набор под результаты, оценка будет пропускать саму себя. Единственные оправданные случаи правки — когда изменились соглашение о якорях, определение классов или содержимое образцов.

Зависимости

svg читается стандартным xml.etree — зависимостей 0.

Почему не используется PyMuPDF (fitz): производительность лучше, но лицензия AGPL-3.0, поэтому при включении во внутренний инструмент возникают условия распространения. Если извлечение таблиц действительно понадобится, добавьте pdfplumber (MIT).

Что не коммитится

Не размещайте реальные анализируемые документы внутри этого репозитория.