Análisis de archivos MCP (file-insight-mcp)

Es un servidor MCP local de uso personal que lee documentos no estructurados dentro de una carpeta especificada, analiza su estructura y genera un resumen por documento y un informe de resumen general de la carpeta.

Todos los documentos dentro de data/sample_docs/ de este paquete son datos sintéticos creados para fines de demostración.

Referencias base

• Estructura del servidor (FastMCP, stdio, combinación de múltiples servidores MCP): https://github.com/kyopark2014/mcp

• Convenciones del harness (stage/next_actions por pasos, anclas de fundamentación, límites de aprobación): se reutiliza el enfoque establecido en el proyecto personal-meeting-mcp-training de la misma familia

• Lista de principios de ingeniería de harness: https://github.com/walkinglabs/awesome-harness-engineering (se aplican de forma selectiva los elementos de presupuesto de contexto, hooks de preaprobación, eval determinista y escáner estático de seguridad, adaptados a la escala de este proyecto)

• SDK de Python para MCP: https://github.com/modelcontextprotocol/python-sdk

Related MCP server: file-analyzer

Qué hace este servidor

1. Escanea la estructura de la carpeta objetivo fija (data/sample_docs/).

2. Lee únicamente los documentos con extensiones permitidas (.txt .md .csv .log).

3. Extrae de los documentos la tabla de contenido (estructura de títulos), fechas, cifras y candidatos a términos clave mediante reglas.

4. Construye un prompt de resumen que combina todos los documentos. El resumen en sí lo redacta el LLM del host (Claude/Codex); este MCP no realiza llamadas a la API del LLM.

5. Valida la estructura del informe de resumen generado y contrasta que los nombres de archivo mencionados existan realmente.

6. Solo guarda el informe en un archivo después de que el usuario lo apruebe explícitamente.

Inicio rápido

Entorno requerido: Python 3.11 o superior, uv

uv sync --extra dev

Tras la instalación, comprueba que se superan los cuatro comandos de la sección Verificación siguiente.

Para inspeccionar visualmente las herramientas con MCP Inspector:

uv run mcp dev src/file_insight_mcp/server.py

Estructura del proyecto

Se separa la lógica de dominio de las convenciones de las herramientas para que, al cambiar las reglas de validación, no sea necesario tocar la capa de herramientas.

Flujo recomendado

SCAN → LIST → READ → EXTRACT → DRAFT → CHECK → PREVIEW → [사용자 승인] → SAVED

Recursos y prompts

Diseño del harness

Este servidor considera como objeto de diseño no solo la funcionalidad, sino también la forma en que el modelo utiliza las herramientas.

• Todas las respuestas incluyen stage y next_actions, de modo que el modelo puede elegir la siguiente herramienta solo con ver la respuesta. blocking: true es una pista informativa de "no omitas este paso". Lo que realmente bloquea el guardado son la validación de estructura y el token de aprobación; la pista no sustituye esa función.

• Los errores se devuelven mediante ToolFailure junto con el código de causa, el método de recuperación y los valores seleccionables. El objetivo es que el modelo pueda recuperarse por sí mismo sin tener que volver a preguntar.

• Los esquemas de argumentos se mantienen planos ({"relative_path": "..."}). Si se usan modelos Pydantic como tipo de argumento, se anidan como {"params": {...}} y cambia la forma de la llamada.

• Los valores de retorno son modelos Pydantic, por lo que outputSchema se genera automáticamente.

• Todas las herramientas llevan readOnlyHint / destructiveHint para que el host pueda mostrar una interfaz de aprobación diferente para las herramientas de escritura.

• Solo las comprobaciones seguras (estructura) bloquean el guardado; las comprobaciones heurísticas (contraste de nombres de archivo) solo se notifican como advertencia.

Presupuesto de contexto

Siguiendo el principio de que "la ventana de contexto no es un lugar para desechar, sino un presupuesto de memoria de trabajo", todas las herramientas establecen un límite explícito en el tamaño de la respuesta.

• scan_folder_structure: si supera MAX_SCAN_ENTRIES(500), lo notifica con truncated: true y lo trunca.

• read_document: los archivos que superan MAX_FILE_BYTES(200KB) no se leen completos; se indica mediante un error que se lea solo una parte con read_document_chunk.

• extract_key_terms: limita el número de elementos por categoría con max_terms.

• preview_save_report: include_preview=False es el valor predeterminado, por lo que no vuelve a incluir en la respuesta el borrador que ya se tiene. Solo cuando es necesario incluirlo, limita la longitud con max_preview_chars.

• harness.truncate() / harness.number_lines(): siempre indica explícitamente si hay truncamiento y las anclas de cita (números de línea), para que el modelo no tenga que adivinar "si esto es todo o solo una parte".

Límites de seguridad

• El servidor solo maneja security.TARGET_DIR(data/sample_docs/). No se puede acceder fuera de él ni con .., rutas absolutas, letras de unidad ni enlaces simbólicos (security.safe_relative_path).

• No se leen archivos fuera de la allowlist de extensiones (.txt .md .csv .log). Las extensiones ejecutables/de script siempre se excluyen del objetivo.

• Si el tamaño del archivo supera MAX_FILE_BYTES(200KB), no se lee completo y se indica mediante un error.

• Los archivos y carpetas ocultos cuyo nombre comienza con . se excluyen del escaneo.

• La única herramienta de escritura es save_approved_report, y solo funciona cuando coincide el token hash (report_id, contenido) emitido por preview_save_report.

• Este servidor solo lee documentos. Si en el código fuente aparecen llamadas de ejecución de código o shell como eval/exec/subprocess, scripts/validate_package.py falla.

Verificación

uv run pytest -q
uv run python scripts/smoke_stdio.py
uv run python scripts/run_evals.py
uv run python scripts/validate_package.py

Los cuatro comandos tienen funciones diferentes, por lo que deben superarse todos.

run_evals.py incluye todo el flujo de guardado, incluido que el guardado tenga éxito o se rechace según si el token de aprobación es correcto o incorrecto. Cada vez que se corrige un error, se añade una línea en evals/cases.jsonl con un caso que reproduzca ese error. Consulta la sintaxis de los casos en evals/README.md.

Si quieres analizar otra carpeta

Por seguridad, este proyecto fija la carpeta objetivo en TARGET_DIR de src/file_insight_mcp/security.py (data/sample_docs/ dentro del paquete). Para analizar una carpeta de trabajo real:

1. Cambia TARGET_DIR a la ruta absoluta deseada, o modifícalo para inyectarlo mediante una variable de entorno.

2. Añade a ALLOWED_EXTENSIONS las extensiones que realmente existan en esa carpeta.

3. Comprueba primero que no haya subcarpetas sensibles (credenciales, datos personales, etc.).

Conexión con Claude Desktop

Sustituye ABSOLUTE_PROJECT_PATH de config/claude_desktop_config.example.json por la ruta absoluta de esta carpeta y aplícalo en la configuración de Claude Desktop. Debes cerrar la aplicación por completo y volver a ejecutarla.

Principios de diseño

• MCP no realiza llamadas a una API de LLM independiente. Claude o Codex redactan las frases del resumen; este MCP se encarga del texto original, la estructura, la validación y el guardado.

• No se inventan nombres de archivo, cifras ni fechas que no estén verificados en los documentos; el verificador de fundamentación los contrasta mecánicamente.

• El guardado final requiere tanto el token de aprobación emitido en la vista previa como la aprobación explícita del usuario.

• Se separa la lógica de dominio (core, outline, grounding) de las convenciones de herramientas (server, harness, security).