file-analysis

지정한 폴더의 비정형 문서(pdf docx pptx svg png)를 읽어, 주요 내용 요약과 파일 구조 분석을 돕는 개인용 로컬 MCP입니다. 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

분석할 폴더 지정

config/roots.toml의 allowed_roots를 고칩니다. 이 파일이 서버의 보안 경계입니다.

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의 인터페이스는 하나입니다. 모든 형식을 블록의 1차원 목록으로 평탄화하므로 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 세 축으로 나눕니다. 변경할 파일이 어느 축인지 먼저 정하세요. 축이 불분명하면 설계가 틀린 신호입니다.

축별 상세 계약과 의존 방향은 AGENTS.md 2장에 있습니다.

진행 상태(어디까지 읽었나)는 서버가 들지 않습니다. 모델이 소유하고, 서버는 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)를 추가하세요.

커밋하지 않는 것

분석 대상 실제 문서를 이 저장소 안에 두지 마세요.