file-analyzer-mcp

Servidor MCP stdio personal que extrae solo texto/estructura de PDF·DOCX·PPTX·SVG·PNG en una carpeta local. No resume ni interpreta — leer y resumir los resultados extraídos es tarea del LLM anfitrión (Claude Code, etc.) que invoca esta herramienta.

Qué hace / Qué no hace

Related MCP server: file-analysis-mcp

Ejemplo de ejecución

> read_document("quarterly-report.pdf")
{
  "type": "pdf",
  "num_pages": 12,
  "text": "Q3 Revenue Summary\n..."
}

> read_document("../../etc/passwd")
{ "error": "'../../etc/passwd' resolves outside the allowed root folder" }

Inicio rápido

git clone https://github.com/saewookkangboy/fileanalyzer_mcp_testmonial.git
cd fileanalyzer_mcp_testmonial
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
brew install tesseract   # PNG OCR용 (한국어는 brew install tesseract-lang 추가)

Registro en Claude Code:

claude mcp add file-analyzer --env FILE_ANALYZER_ROOT=/분석할/폴더 -- \
  "$(pwd)/.venv/bin/python" "$(pwd)/server.py"
claude mcp list   # ✔ Connected 확인

Después del registro, si en una sesión nueva pides «resume los documentos de esta carpeta», Claude invocará directamente las 3 herramientas siguientes.

Herramientas (Tools)

Estructura del proyecto

server.py                    # FastMCP 앱 진입점, 툴 등록, 루트 폴더 검증
file_analyzer/
  security.py                #  경로 격리(resolve_safe_path), 크기 제한
  timeout.py                 #  추출 작업 하드 타임아웃
  audit.py                   #  로컬 감사 로그(logs/audit.jsonl)
  tree.py, metadata.py       #  list_directory / get_file_metadata 로직
  extractors/                #  pdf · docx · pptx · svg · image(OCR) 추출기
tests/                       # pytest 회귀 스위트
AGENTS.md                    # 호출 에이전트(Claude Code)를 위한 운영 지침

Seguridad y restricciones

Observabilidad — registro de auditoría

Cada invocación de herramienta se registra localmente, una línea por llamada, en logs/audit.jsonl (sin transmisión externa).

{"timestamp": "2026-08-26T06:03:35Z", "tool": "read_document", "params": {"relative_path": "report.pdf"}, "status": "ok", "duration_ms": 251.3}

Para vaciar el registro, basta con eliminar logs/audit.jsonl.

Desarrollo

pip install -e ".[dev]"
pytest -q

tests/ cubre el bloqueo de la salida de rutas y de la inyección de rutas absolutas, los 5 extractores, el timeout, el registro de auditoría y la integración del servidor. Dado el tamaño de este proyecto, consideramos que basta la ejecución local de pytest, sin un pipeline de CI, para la verificación de regresiones, y así lo hemos mantenido.

Por qué se diseñó así

• Sin función de resumen — para que funcione sin una clave de API de LLM aparte, optamos por una estructura mínima en la que el servidor se encarga de la extracción y el anfitrión, del resumen.

• PNG: OCR, no envío a vision — en lugar de pasar la imagen en base64 al anfitrión, extraemos solo el texto para reducir el volumen de respuesta y la complejidad de implementación (no capta el significado visual de las imágenes).

• Solo pytest local, sin git/CI — consideramos que una infraestructura de CI es excesiva para una herramienta local de una sola persona.

Limitaciones conocidas

• El timeout está basado en hilos; el hilo en segundo plano de la propia llamada que excedió el límite puede seguir ejecutándose hasta el final incluso después de devolverse la respuesta.

• No se admite .ppt — conviértalo a .pptx antes de usarlo.

Licencia

Es un proyecto personal sin archivo de licencia aparte.