file-analyzer-mcp

Prueba

Apúntalo a una carpeta y te devuelve un árbol real, no una suposición:

$ analyze_folder_structure({ "folder_path": "tests/fixtures" })

{
  "status": "OK",
  "file_count": 6,
  "supported_file_count": 6,
  "extension_stats": [
    { "extension": ".pdf",  "count": 2, "bytes": 723995 },
    { "extension": ".docx", "count": 1, "bytes": 35505 },
    { "extension": ".pptx", "count": 1, "bytes": 33067 },
    { "extension": ".svg",  "count": 1, "bytes": 319 },
    { "extension": ".png",  "count": 1, "bytes": 74 }
  ],
  "tree_text": "fixtures/\n├── sample.docx (34.7KB)\n├── sample.pdf (431B)\n├── sample.png (74B)\n├── sample.pptx (32.3KB)\n├── sample.svg (319B)\n└── sample_scanned.pdf (706.6KB)"
}

Luego lee uno de ellos: los encabezados, párrafos y tablas vuelven estructurados, no aplanados:

$ read_docx({ "file_path": "tests/fixtures/sample.docx" })

{
  "status": "OK",
  "headings": ["테스트 문서"],
  "text": "테스트 문서\n본문 첫 문단입니다.",
  "tables": [{ "index": 0, "rows": [["A", "B"], ["1", "2"]] }]
}

Ambas llamadas son reproducibles: clona este repositorio, ejecuta uv sync --extra dev y llámalas contra tests/fixtures/ tú mismo.

Related MCP server: Agent Helper

Qué es

Un servidor MCP personal que lee lo que haya en una carpeta — PDF, Word, PowerPoint, SVG, PNG — y devuelve la estructura y el contenido bruto al agente que lo haya llamado (Claude Code, Claude Desktop, Codex). No resume nada por sí mismo.

Ese es todo el diseño: el servidor extrae, el anfitrión interpreta. No hay ninguna clave de API de LLM viviendo en este servidor. Un PNG vuelve como contenido de imagen en base64, no como un pie de foto — la visión de tu propio anfitrión lo lee. Un PDF escaneado solo se somete a OCR cuando lo pides.

Herramientas

Los documentos grandes se paginan: page_start/page_end para PDF, slide_start/slide_end para PPTX. Los límites predeterminados son 30 páginas / 60 diapositivas — más allá de eso, el next_actions de la respuesta te indica el siguiente rango que debes pedir.

Instalación

uv sync --extra dev

Regístralo con Claude Code:

claude mcp add -s user file-analyzer -- "<uv.exe path>" --directory "<this folder>" run python src/file_analyzer_mcp/server.py

En Windows, si uv se instaló mediante pip, no estará en el PATH de Claude — usa la ruta completa de uv.exe (pip show uv para encontrarla). Los ejemplos de Claude Desktop y Codex están en config/: claude_code.example.md, claude_desktop_config.example.json, codex-config.example.toml.

Seguridad

Las rutas sensibles se rechazan de forma determinista — esto no depende de que el modelo decida no leerlas. Consulta paths.py.

Cada llamada también se audita: nombre de la herramienta, argumentos y resultado (éxito o bloqueo) se añaden a logs/audit.jsonl. Consulta audit.py. Se aplica un límite de tamaño de archivo de 50 MB además de todo esto.

Las convenciones para cualquiera que amplíe este servidor están en AGENTS.md.

Errores

Cada fallo lanza ToolFailure con un código, una razón en lenguaje sencillo y cómo recuperarse: el mensaje está escrito para que el modelo que llama lo lea y actúe, no solo para un humano.

OCR de PDF escaneados

read_pdf(ocr=True) necesita Tesseract:

winget install UB-Mannheim.TesseractOCR
uv run python scripts/setup_ocr.py   # copies eng/osd, downloads kor.traineddata

ocr_lang tiene como valor predeterminado "kor+eng". ¿Ruta de Tesseract incorrecta? Establece TESSERACT_CMD.

Pruebas

uv run pytest -q                        # parser / path / audit unit tests
uv run python scripts/smoke_stdio.py    # real stdio round-trip against the server

Ambas deberían pasar antes de que un cambio cuente como terminado: pytest comprueba los módulos de forma aislada; la prueba de humo es lo único que ejercita el protocolo MCP real y detecta roturas a nivel de esquema.

Límites