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

개요

폴더 안의 모든 것(PDF, Word, PowerPoint, SVG, PNG)을 읽어 구조와 원본 콘텐츠를 호출한 에이전트(Claude Code, Claude Desktop, Codex)에 돌려주는 개인용 MCP 서버입니다. 자체적으로 요약하지는 않습니다.

설계의 전부입니다. 서버는 추출하고 호스트는 해석합니다. 이 서버에는 LLM API 키가 없습니다. PNG는 캡션이 아닌 base64 이미지 콘텐츠로 반환되며, 호스트 자체의 비전이 읽습니다. 스캔된 PDF는 요청할 때만 OCR 처리됩니다.

도구

큰 문서는 페이지 단위로 나뉩니다. PDF는 page_start/page_end, PPTX는 slide_start/slide_end입니다. 기본 상한은 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로 설치했다면 Claude의 PATH에 없을 것입니다. 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를 참조하세요. 이 모든 것에 더해 50MB 파일 크기 상한이 적용됩니다.

이 서버를 확장하는 사람을 위한 규칙은 AGENTS.md에 있습니다.

오류

모든 실패는 코드, 평이한 이유, 복구 방법과 함께 ToolFailure를 발생시킵니다. 메시지는 사람만을 위한 것이 아니라 호출한 모델이 읽고 행동할 수 있도록 작성됩니다.

스캔된 PDF OCR

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는 모듈을 격리된 상태로 검사하고, 스모크 테스트는 실제 MCP 프로토콜을 실행하고 스키마 수준의 손상을 잡아내는 유일한 것입니다.

제한 사항