file-analysis-mcp

Reads unstructured documents (pdf, docx, pptx, txt, svg, png, csv, xlsx) in a specified folder, understands their structure, and is a personal local MCP that saves nothing without approval.

Real-world example

Actual results from running against the included synthetic sample folder (sample_docs/).

list_folder_contents()
→ count: 8, entries: data.csv, diagram.svg, notes.docx, photo.png,
  readme.txt, report.pdf, sheet.xlsx, slides.pptx

describe_file(relative_path="slides.pptx")
→ {"slide_count": 3, "slide_titles": ["팀 소개", "구성원", "다음 스프린트"]}

The report written from actually reading these files is at data/outputs/onboarding-overview-report.md — it passed structure validation VALID and filename-based grounding check GROUNDED (100 points).

I also validated it against a real lecture materials folder (PPTX, 9MB, 16 slides), and in the process found and fixed a bug where trying to read a lock file (~$*.pptx) created while PowerPoint is open caused the format library exception to surface directly. Now it's handled as an error containing the cause code and recovery method.

[INVALID_REQUEST] '~$파일.pptx' 파일을 열지 못했습니다: Package not found ...
복구 방법: list_folder_contents로 파일 목록과 지원 형식을 다시 확인하세요.

Related MCP server: local-docs-mcp

What it is

Point it at a folder and it reads the documents inside, first figures out the structure such as page/slide/sheet counts, and helps write a summary report. It handles 8 formats with dedicated parsers (pypdf/python-docx/python-pptx/openpyxl/Pillow).

Why it's different

• MCP does not call the LLM. The actual summary sentences are written by the Host (Claude/Codex). The server only handles data lookup, structure analysis, validation, and saving.

• Both an approval token and the user's explicit approval are required before saving. The only write tool is save_approved_report; the other 10 are read-only.

• PNG is delivered as real image content, without OCR. The Host's vision capability sees and interprets it directly.

• Errors always return a cause code + recovery method + selectable values (see example above).

How it works

list_folder_contents → describe_file → read_file_text(또는 read_image_file)
  → build_summary_prompt → validate_report_draft → check_report_grounding
  → preview_save_report → [사용자 승인] → save_approved_report

Getting started

python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"
.venv/Scripts/python scripts/generate_samples.py
.venv/Scripts/python -m pytest -q
.venv/Scripts/python scripts/smoke_stdio.py

Analyzing a real folder

The default is sample_docs/. Just change one environment variable before starting the server.

FILE_ANALYSIS_ROOT="D:\내 문서 폴더" .venv/Scripts/python src/file_analysis_mcp/server.py

To register with Codex CLI:

codex mcp add file-analysis --env FILE_ANALYSIS_ROOT="D:\내 문서 폴더" -- \
  "<프로젝트경로>\.venv\Scripts\python.exe" "<프로젝트경로>\src\file_analysis_mcp\server.py"

Limitations

• Images are not OCR'd. Instead of extracting text, the image content is passed to the Host as-is.

• Files over 20MB can only have their structure checked; the body text cannot be read.

• check_report_grounding is a regex-based heuristic, so false positives are possible (it's advisory only and does not block saving).

• Encrypted, corrupted, or files in use by another program are reported as errors with a cause code — the server does not crash.

Underlying patterns

Follows the same design principles as personal-meeting-mcp-training (layer separation, stage/next_actions, approval boundaries). For detailed tool contracts, see the module docstrings in src/file_analysis_mcp/.