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: Docalyze

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/asuramama-hue/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 nueva sesión pides «resume los documentos de esta carpeta», Claude invocará directamente las 3 herramientas siguientes.

Herramientas

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 escapes de ruta e inyección de rutas absolutas, los 5 extractores, el tiempo de espera, el registro de auditoría y la integración del servidor. Para el tamaño de este proyecto, consideramos que ejecutar pytest localmente sin un pipeline de CI es suficiente para la verificación de regresiones, y así lo mantenemos.

Por qué se diseñó así

• Sin función de resumen — para que funcione sin una clave de API de LLM adicional, se eligió una estructura mínima en la que el servidor extrae y el anfitrión resume.

• PNG: OCR, no visión — en lugar de pasar la imagen en base64 al anfitrión, solo se extrae texto, reduciendo el volumen de respuesta y la complejidad de implementación (no ve el significado visual de los dibujos).

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

Limitaciones conocidas

• El tiempo de espera se basa en hilos, por lo que el hilo en segundo plano de la llamada que excedió el límite puede seguir ejecutándose hasta el final incluso después de devolver el error.

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

Licencia

Es un proyecto personal sin un archivo de licencia independiente.