file-analysis-mcp

Un MCP local personal que lee documentos no estructurados (pdf, docx, pptx, txt, svg, png, csv, xlsx) dentro de una carpeta especificada, comprende su estructura y no guarda nada sin aprobación.

Ejemplo de funcionamiento real

Resultados reales de la ejecución sobre la carpeta de muestras sintéticas incluida (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": ["팀 소개", "구성원", "다음 스프린트"]}

El informe redactado tras leer realmente estos archivos está en data/outputs/onboarding-overview-report.md: superó la validación de estructura VALID y la comprobación de fundamento de nombres de archivo GROUNDED (100 puntos).

También lo validé apuntando a una carpeta real de materiales de clase (PPTX, 9 MB, 16 diapositivas), y en ese proceso descubrí y corregí un error: al intentar leer el archivo de bloqueo (~$*.pptx) que se genera al tener PowerPoint abierto, la excepción de la biblioteca de formatos salía tal cual. Ahora se gestiona como un error que incluye el código de causa y el método de recuperación.

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

Related MCP server: local-docs-mcp

Qué es

Al especificar una carpeta, lee los documentos que contiene, primero comprende la estructura (número de páginas/diapositivas/hojas, etc.) y ayuda a redactar un informe resumido. Gestiona los 8 formatos con analizadores dedicados (pypdf/python-docx/python-pptx/openpyxl/Pillow).

Por qué es diferente

• El MCP no llama al LLM. Las frases de resumen reales las escribe el Host (Claude/Codex). El servidor solo se encarga de la consulta de datos, el análisis de estructura, la validación y el guardado.

• Antes de guardar se requieren tanto el token de aprobación como la aprobación explícita del usuario. Solo hay una herramienta de escritura, save_approved_report; las otras 10 son de solo lectura.

• El PNG se entrega como contenido de imagen real, sin OCR. La capacidad de visión del Host lo ve e interpreta directamente.

• Los errores siempre devuelven código de causa + método de recuperación + valores seleccionables (ver el ejemplo anterior).

Cómo funciona

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

Cómo empezar

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

Analizar una carpeta real

El valor predeterminado es sample_docs/. Solo hay que cambiar una variable de entorno antes de ejecutar el servidor.

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

Para registrarlo en Codex CLI:

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

Limitaciones

• Las imágenes no pasan por OCR. No se extrae texto; el contenido de la imagen se entrega tal cual al Host.

• Los archivos de más de 20 MB solo permiten comprobar la estructura; no se puede leer el contenido.

• check_report_grounding es una heurística basada en expresiones regulares, por lo que puede dar falsos positivos (es solo asesoramiento; no bloquea el guardado).

• Los archivos cifrados, dañados o en uso por otro programa se notifican como errores con su código de causa: el servidor no se cae.

Patrón base

Sigue los mismos principios de diseño que personal-meeting-mcp-training (separación de capas, stage/next_actions, límites de aprobación). Para el contrato detallado de las herramientas, consulta el docstring de cada módulo en src/file_analysis_mcp/.