Skip to main content
Glama
file-analysis-mcp

file-analysis-mcp

file-analysis-mcp

“请把这个文件夹里的 pdf/docx/pptx/svg/png 文档都读一遍并总结一下。” 这是一个个人用 MCP 服务器,只为让 Claude Code 执行这一句话。

Python 3.11+ MCP read--only tests

指定文件夹后,它会打开其中的文档,只把文本原样提取出来返回。 摘要、解读不是由这个服务器完成,而是在对话中由调用它的 Claude 完成——因此无需单独的 LLM API 密钥,完全在本地以个人方式运行。


目录


Related MCP server: file-analyzer

实际运行效果

这是在 Claude Code 中指定实际文件夹(存放公司内部 PRD 文档的文件夹)提问后的结果。

我:帮我总结一下 docs 文件夹里的文档,并分析文件结构

Claude 依次调用 analyze_folder_structure → analyze_folder,并基于返回的原文文本这样回答。

[analyze_folder_structure] pdf 2개, 총 455KB, 최대 파일 prd.pdf(231KB)
[analyze_folder]           2개 파일 모두 추출 성공 (succeeded: 2, failed: 0)

→ Claude의 요약:
두 문서는 같은 프로젝트("ParameterCheck")의 서로 다른 산출물입니다.
- proposal.pdf: RF솔루션 파트의 CAB 파라미터 검증 자동화 기획서
- prd.pdf: 같은 아이디어의 정식 PRD. 목표는 검증 시간 10분→5분 단축,
  MVP는 "파라미터 엑셀 입력 시 집계시트 자동 생성 + 오류 빨강 표시"
공통점: 사람 검토·승인은 항상 최종 단계로 남겨둔다는 원칙이 두 문서 모두에 명시됨.

服务器只是传回了文本,上面这些摘要语句全部由 Claude 生成——这正是本项目所追求的角色分工。

快速开始

# 1) 의존성 설치 (uv 사용)
uv sync --extra dev

# 2) 확인
uv run pytest                        # 유닛테스트
uv run python scripts/smoke_stdio.py # 실제 MCP 프로토콜로 서버를 띄워보는 스모크 테스트

如果需要 OCR(PNG 分析),请另行安装 Tesseract-OCR——下面在 Claude Code 中注册的开头部分有说明。即便不安装,其余 4 个工具也能正常工作。

5 个工具

工具

说明

护栏

scan_folder

返回文件夹内目标文件列表(路径/大小/修改日期)及按扩展名统计的数量

超过 max_files(默认 300)时返回 list_truncated=True

analyze_folder_structure

返回包含子文件夹的树形结构、按扩展名统计、容量、最大文件列表

仅树形结构受 max_files 上限限制(统计始终基于全部文件)

read_document

提取单个 pdf/docx/pptx/svg 文档的文本

以 max_chars 截断,并用 truncated=True 明确标示

read_image_text

通过 OCR 读取单个 png 图片并提取文本

同上 + 若 OCR 结果为空,会在 next_actions 中说明原因

analyze_folder

一次性提取文件夹内所有目标文件并以报告形式返回(无需多次调用)

超过 max_files(默认 50)时,通过 skipped_due_to_limit 明确标注数量

所有工具均为只读,不会修改/删除文件。即使触达上限(max_files),也不会悄悄漏掉文件,而是在响应中如实标注有多少个文件未能读取;同时 status 会变成 PARTIAL,让你立即知晓这一情况。

在 Claude Code 中注册

安装 OCR 引擎(仅 PNG 分析需要)

pytesseract 只是 Tesseract-OCR 引擎的 Python 绑定,引擎本身需要另外安装。

  1. 下载 UB-Mannheim Tesseract 安装包并安装到 Windows。(如果需要韩语识别,请在安装过程中的“Additional language data”里勾选 Korean。)

  2. 将安装路径(默认 C:\Program Files\Tesseract-OCR)添加到系统 PATH。

  3. 用 tesseract --version 确认安装成功。

注册服务器

本仓库根目录已备好 .mcp.json。在 file-analysis-mcp 文件夹(或其上级文件夹)中运行 Claude Code 时会自动识别。重启后请在 /mcp 命令或工具列表中确认能否看到 file-analysis 的 5 个工具。

如需手动注册:

claude mcp add file-analysis -- uv --directory "C:\Users\20223\Desktop\file-analysis-mcp" run python src/file_analysis_mcp/server.py

推荐流程:先用 analyze_folder_structure 了解结构 → 再用 analyze_folder 批量提取全部文档文本 → 由 Claude 基于提取出的文本进行总结。

项目结构

file-analysis-mcp/
├── pyproject.toml
├── .mcp.json
├── src/file_analysis_mcp/
│   ├── server.py        # FastMCP 서버, 도구 5개
│   ├── harness.py        # 응답/오류 계약 (BaseResponse, ToolFailure 등)
│   ├── scanner.py         # 폴더 스캔/구조 분석
│   └── extractors/        # pdf/docx/pptx/svg/image 텍스트 추출기
├── scripts/smoke_stdio.py
├── tests/
│   ├── test_scanner.py           # 도메인 로직(순수 함수) 유닛테스트
│   ├── test_extractors.py        # 포맷별 추출기 유닛테스트
│   └── test_server_contract.py   # 하네스 규약(도구 계약) 테스트
└── data/sample_docs/       # 테스트용 샘플 문서

设计原则:harness 工程

这个服务器的优先目标不是“增加功能”,而是让模型只看响应就知道下一步该做什么。在 awesome-harness-engineering 介绍的诸多原则中,只选择了真正符合本项目“本地、单用户、只读”特性的部分加以应用。(OpenTelemetry 观测、提示注入沙箱、mcp-guardian 之类的范围审批门控等,是为多用户、长期运行的代理设计的,对这样规模的个人工具来说过于沉重,因此没有采用。)

应用的内容

在本项目中的形态

明确的工具边界

在工具 docstring 中写明目的 + Returns + “使用 / 不使用”示例,让模型能从 5 个工具中选出正确的一个

下一步行动指引

所有响应都包含 status + next_actions。针对成功/部分成功/空结果等不同情况,具体给出下一步应调用的工具及原因

可操作的错误

ToolFailure 强制包含原因代码 + 恢复方法 + 可选值。例:不支持的扩展名 → 可用扩展名列表

上下文节省(单次响应)

read_document/read_image_text/analyze_folder 以 max_chars(每个文件)截断,并用 truncated 明确标识

上下文节省(护栏)

为 scan_folder/analyze_folder_structure/analyze_folder 设置文件数量上限(max_files),即使文件夹中文件非常多,单次调用也不会无限膨胀

将有价值的失败保留在上下文中

analyze_folder 即使有某个文件失败也不会中止整个批次,而是按文件记录成功/失败情况,供下一步判断使用

禁止静默丢失

即使超过上限也不会偷偷跳过文件,而是通过 list_truncated/skipped_due_to_limit 在响应中如实记录未能读取的文件数量

工具契约测试

tests/test_server_contract.py 用代码验证“所有工具是否都有描述/annotations”“参数 schema 是否扁平”“所有工具是否都为 read-only”“护栏是否真正生效”

有意未采用的内容

  • 总结/依据验证(grounding)功能:本服务器设计为“只做提取”(总结是宿主模型的职责),因此不适用。

  • 行号引用锚点(L12 | ...):在没有单独的引用依据验证工具的情况下,只会让文本变得杂乱,因此没有采用。如果以后需要,可以复用 harness.number_lines() 来添加。

  • 基于审批令牌的保存工作流:本服务器不写入文件,因此不适用。

Available Tools

5 tools
analyze_folderA
Read-onlyIdempotent

폴더 안의 모든 대상 파일(pdf/docx/pptx/svg/png)을 한 번에 추출해 리포트로 반환합니다.

파일마다 read_document/read_image_text를 따로 호출하지 않아도 되는 배치 도구입니다. 한 파일이 실패해도 나머지 파일 처리는 계속되며, 실패 이유는 파일별로 남습니다. 파일 수가 max_files를 넘으면 앞쪽부터 max_files개만 처리하고, 넘겨받지 못한 개수는 skipped_due_to_limit로 투명하게 알려줍니다(조용히 누락되지 않습니다).

Returns: AnalyzeFolderResponse: reports[]의 각 항목은 status(OK/ERROR)와 함께 text 또는 error를 담습니다. status가 PARTIAL이면 일부 실패했거나(failed>0) 상한 때문에 스킵된 파일(skipped_due_to_limit>0)이 있다는 뜻입니다.

Examples: - 사용: "이 폴더 문서들 다 요약해줘", "폴더 구조 분석하고 내용도 정리해줘" - 사용하지 않음: 파일 목록만 필요할 때 → scan_folder - 사용하지 않음: 특정 파일 하나만 자세히 → read_document / read_image_text

Inputs: folder_path (required), max_files, recursive, extensions, +1 more. Returns: failed, folder, status, reports, +5 more

analyze_folder_structureA
Read-onlyIdempotent

폴더의 하위 디렉터리 트리와 확장자별 통계, 용량, 최대 파일을 분석합니다.

scan_folder보다 한 단계 더 깊은 "구조" 파악용 도구입니다. 폴더가 어떻게 구성돼 있는지(하위 폴더별 파일 분포, 가장 큰 파일 등)를 먼저 감 잡고 싶을 때 사용하세요.

Returns: FolderStructureResponse: tree는 {"하위폴더명": {...}, "_files": [...]} 형태의 중첩 딕셔너리입니다. 파일이 max_files보다 많으면 tree에는 앞쪽 max_files개만 반영되고 list_truncated=True가 되지만, total_files/ by_extension/total_size_bytes 등 통계는 항상 전체 파일 기준입니다.

Examples: - 사용: "이 폴더 구조 좀 분석해줘", "가장 큰 파일이 뭐야?" - 사용하지 않음: 파일 목록만 빠르게 보고 싶을 때 → scan_folder

Inputs: folder_path (required), max_files, extensions. Returns: tree, folder, status, max_depth, +6 more

read_documentA
Read-onlyIdempotent

문서 파일(pdf/docx/pptx/svg) 하나의 텍스트를 추출합니다. 요약은 하지 않습니다.

scan_folder/analyze_folder에서 찾은 파일 중 하나를 더 자세히 보고 싶을 때, 또는 analyze_folder의 일괄 요약이 잘렸을 때(truncated=True) 이어서 읽을 때 씁니다.

Returns: ReadDocumentResponse: text에 원문(잘렸으면 앞부분)이 담깁니다. truncated=True면 max_chars를 늘려 다시 호출해 나머지를 볼 수 있습니다.

Examples: - 사용: "이 pdf 파일 내용 좀 자세히 보여줘" - 사용하지 않음: png 이미지 → read_image_text - 사용하지 않음: 폴더 전체를 한 번에 훑고 싶을 때 → analyze_folder

Inputs: file_path (required), max_chars. Returns: path, text, status, metadata, +3 more

read_image_textA
Read-onlyIdempotent

PNG 이미지 하나를 OCR로 읽어 텍스트를 추출합니다(Tesseract-OCR 필요).

스크린샷, 스캔한 메모, 다이어그램에 박힌 라벨처럼 이미지 안의 문자를 읽어야 할 때 사용하세요. 순수 그림/사진처럼 텍스트가 없는 이미지는 빈 결과가 나올 수 있습니다(비전 해석이 아니라 OCR이므로 그림 자체의 의미는 파악하지 못합니다).

Returns: ReadImageTextResponse: text에 인식된 문자열이 담깁니다. 결과가 비어 있으면 next_actions에서 그 이유를 안내합니다.

Examples: - 사용: "이 스크린샷에 뭐라고 적혀 있어?" - 사용하지 않음: pdf/docx/pptx/svg 문서 → read_document

Inputs: file_path (required), max_chars. Returns: path, text, status, metadata, +2 more

scan_folderA
Read-onlyIdempotent

폴더 안의 대상 파일(pdf/docx/pptx/svg/png) 목록과 확장자별 개수를 조회합니다.

문서 내용을 읽지 않고 메타데이터(경로/크기/수정일)만 가볍게 훑어보는 도구입니다. 폴더 안에 어떤 파일이 몇 개 있는지 빠르게 확인하고 싶을 때 사용하세요.

Returns: ScanFolderResponse: files[]에 경로/이름/확장자/크기/수정일이 담깁니다. 파일이 max_files보다 많으면 list_truncated=True이고, by_extension의 개수는 상한과 무관하게 항상 전체 매칭 파일 기준입니다.

Examples: - 사용: "이 폴더에 어떤 문서들이 있어?", "pdf 몇 개야?" - 사용하지 않음: 파일 내용까지 요약하고 싶을 때 → analyze_folder - 사용하지 않음: 하위 폴더 구조/통계까지 보고 싶을 때 → analyze_folder_structure

Inputs: folder_path (required), max_files, recursive, extensions. Returns: files, folder, status, total_files, +4 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: read_document handles individual text documents, scan_folder lists metadata, analyze_folder_structure provides hierarchical stats, read_image_text does OCR, and analyze_folder batch-processes all files. Descriptions explicitly state what not to use each tool for, reinforcing boundaries.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern (read_document, scan_folder, analyze_folder_structure, read_image_text, analyze_folder). The verbs are distinct and descriptive, and the pattern is uniform across the set.

    Tool Count5/5

    With 5 tools, the server is well-scoped for file and folder analysis. Each tool covers a distinct aspect (single read, metadata scan, structure analysis, OCR, batch processing) without redundancy or missing essentials, making the count ideal for its purpose.

    Completeness5/5

    The tool surface covers the full lifecycle of file analysis: listing, detailed reading (both text and OCR), structural analysis, and batch processing. Error handling and truncation are addressed. No obvious gaps for the stated domain, such as missing file deletion or modification, which are out of scope.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      Provides LLMs with secure, read-only access to local documentation by scanning directories, extracting content from PDF, DOCX, Markdown, and text files, and performing keyword searches.
      3
      4 npm
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables read-only analysis of local unstructured documents by scanning a folder, extracting text and structural metadata, and passing content with truncation and error-awareness to an LLM for summarization.
      9
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables local, read-only extraction of text and structure from PDF, DOCX, PPTX, SVG, and PNG files, including OCR for images, directory tree and metadata reporting, with strict path isolation and audit logging.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables local folder analysis of unstructured documents (PDF, DOCX, PPTX, TXT, SVG, PNG, CSV, XLSX) by extracting structure, reading content, and generating reports, with a strict approval gate before any save operation.
      -