file-analysis

MCP local de uso personal que lee documentos no estructurados (pdf docx pptx svg png) de una carpeta especificada y ayuda a resumir el contenido principal y a analizar la estructura de los archivos. Se conecta a Claude Code · Codex · Claude Desktop.

Si el mismo dato aparece en dos lugares, AGENTS.md es la fuente original.

Este servidor no resume

Es la decisión de diseño más importante.

Si el servidor también resumiera, tendría que volver a llamar a un modelo con su propia clave de API, y el anfitrión solo recibiría el resultado del resumen, sin poder contrastar la evidencia. Se abriría una vía por la que un resumen erróneo pasara silenciosamente. Por eso el servidor solo entrega el texto original y las anclas.

Related MCP server: file-analyzer

Inicio rápido

Entorno requerido: Python 3.11 o superior, uv

uv sync --extra dev

uv run python scripts/make_samples.py

uv run python scripts/smoke_stdio.py

Si smoke_stdio.py devuelve PASS, el servidor funciona correctamente: se lanza el servidor con el protocolo MCP real, se verifican las 17 reglas del harness y se recorre un ciclo completo desde DISCOVER hasta SAVED.

Para inspeccionar las herramientas visualmente con MCP Inspector:

uv run mcp dev src/file_mcp/server.py

Especificar la carpeta a analizar

Edite allowed_roots en config/roots.toml. Este archivo es el límite de seguridad del servidor.

allowed_roots = [
  "data/samples",
  "C:/Users/<사용자>/Desktop/분석대상",
]

No incluya carpetas superiores completas como C:/Users/<usuario> — sería como no tener salvaguardas. El servidor nunca abre rutas fuera de esta lista, bajo ninguna circunstancia.

Conexión con el anfitrión

Claude Code

claude mcp add file-analysis -- uv --directory "<이-저장소를-클론한-절대경로>" run python src/file_mcp/server.py

Codex — pegue el contenido de config/codex-config.example.toml en ~/.codex/config.toml.

Claude Desktop — consulte config/claude_desktop_config.example.json.

Pipeline

flowchart LR
    S["scan_folder<br/><i>추정 등급 B?</i>"] --> I["inspect_document<br/><i>확정 등급 A/B/C</i>"]
    I --> P["build_analysis_prompt<br/><i>앵커 붙은 원문</i>"]
    P --> D(["초안 작성<br/><i>호스트 모델</i>"])
    D --> G["check_summary_grounding<br/><i>GR-01 … GR-04</i>"]
    G --> V["preview_save_report<br/><i>승인 토큰 발급</i>"]
    V --> H{{"사람의 승인"}}
    H --> W["save_approved_report<br/><i>유일한 쓰기</i>"]

    classDef server fill:#ddf4ff,stroke:#54aeff,color:#1f2328
    classDef notserver fill:#ffffff,stroke:#afb8c1,stroke-dasharray:5 4,color:#656d76
    classDef write fill:#fff8c5,stroke:#d4a72c,color:#1f2328
    class S,I,P,G,V server
    class D,H notserver
    class W write

Las líneas discontinuas indican lo que el servidor no hace. El borrador lo escribe el modelo anfitrión y la aprobación la hace una persona.

La única herramienta de escritura es save_approved_report. No escribe sin el token de aprobación. scripts/smoke_stdio.py verifica la lista de herramientas de escritura, así que si se añade alguna herramienta más, hay que actualizar también la prueba de humo.

La clasificación se decide por el contenido, no por la extensión

flowchart TD
    X["파일"] --> Y{"확장자"}
    Y -->|"docx · pptx"| A["<b>등급 A</b><br/>구조까지"]
    Y -->|"png"| C1["<b>등급 C</b><br/>이미지 판독"]
    Y -->|"pdf"| PQ{"공백 제거 후 페이지 텍스트<br/>8자 이상?"}
    Y -->|"svg"| SQ{"내용 있는<br/>text 노드?"}
    PQ -->|"있음"| B1["<b>등급 B</b><br/>본문만"]
    PQ -->|"없음"| C2["<b>등급 C</b><br/>스캔 PDF"]
    SQ -->|"있음"| B2["<b>등급 B</b><br/>본문만"]
    SQ -->|"없음"| C3["<b>등급 C</b><br/>그림"]

    classDef ga fill:#dafbe1,stroke:#2da44e,color:#1f2328
    classDef gb fill:#ddf4ff,stroke:#54aeff,color:#1f2328
    classDef gc fill:#fff8c5,stroke:#d4a72c,color:#1f2328
    class A ga
    class B1,B2 gb
    class C1,C2,C3 gc

scan_folder no abre los archivos, por lo que no puede confirmar la clase. pdf·svg quedan como B? y inspect_document los abre para confirmarla. No trate el B? del resultado del escaneo como un valor confirmado.

Las muestras están dispuestas para demostrar esto: 흐름도.svg tiene nodos text, así que es B; 도형만.svg solo tiene formas, así que es C. Misma extensión, distinta clase.

Se lee con la visión del modelo anfitrión. No añade dependencias y la precisión en coreano es mejor que la de tesseract. Si en el futuro se necesita procesamiento por lotes offline, se añadirá la herramienta extract_text_ocr por separado.

Los PDF escaneados también se leen sin rasterizador. Como una página escaneada es una sola imagen incrustada, basta con extraer esa imagen con pypdf — no se necesitan ni PyMuPDF (AGPL) ni binarios de poppler.

Las páginas dibujadas solo con vectores no se pueden extraer; en ese caso, el error PDF_PAGE_HAS_NO_IMAGE avisa de que "una persona debe capturar la pantalla". No devuelve silenciosamente un resultado vacío.

Solo entrega el índice, el número de bloques, el número de caracteres, la clase confirmada y estimated_read_calls (número de llamadas necesarias para leer todo). Su razón de existir es evitar que se vierta el cuerpo de un PDF de 300 páginas en el contexto solo para conocer su forma.

El coste de abrir el archivo es el mismo que el de read_document — lo que se ahorra no es tiempo, sino contexto.

Convención de anclas de cita

Cada formato tiene una unidad distinta, pero la interfaz de read_document es una sola. Como todos los formatos se aplanan en una lista unidimensional de bloques, solo hay que usar start/end. La respuesta indica en unit qué es cada bloque.

Si se cambia el formato de las anclas, hay que actualizar también grounding.ANCHOR_PATTERN y el golden set. Si se desalinean, todas las citas válidas quedarán bloqueadas con GR-02.

Qué puede y qué no puede verificar el contraste de evidencia

• Si la frase cita una ancla — GR-01

• Si esa ancla existe en el documento — GR-02

• Si las cifras y fechas están en el texto original del bloque citado — GR-03

• Si la cita directa (entre comillas) coincide con el original — GR-04

• Si el resumen transmite correctamente el significado del original

• Si ha omitido algo importante

• Si la ancla citada es la ancla adecuada (GR-05 es solo una pista de solapamiento léxico)

Que pase no significa que sea correcto. El campo not_verifiable de la respuesta señala esta limitación cada vez — si se fingiera que se ha verificado lo que no se puede verificar, la persona creería que "como pasó, estará bien", y eso es más peligroso que no tener verificación.

Reescribir el texto original con otras palabras es normal. El contraste solo revisa anclas, cifras y citas directas.

Puerta de guardado

preview_save_report revisa tanto la estructura (ST-*) como la evidencia (GR-*) y solo emite el token de aprobación cuando no hay ningún error. El token es sha256(ruta relativa original + borrador), así que si se modifica el borrador aunque sea un solo carácter, el token queda invalidado — se bloquea la vía de previsualizar con un borrador limpio y guardar otro distinto.

save_approved_report vuelve a verificar todas las puertas. No se fía de lo que diga el modelo de que la previsualización pasó.

Si ya existe un artefacto anterior, se sobrescribe y se deja el hash del contenido previo en el registro de auditoría. El registro de auditoría (data/outputs/_audit.jsonl) es de solo añadidura (append-only).

Jerarquía del harness (CAR)

Se divide en tres ejes: Control–Agency–Runtime. Primero determine en qué eje está el archivo que va a cambiar. Si el eje no está claro, es señal de que el diseño está mal.

Los contratos detallados por eje y la dirección de las dependencias están en AGENTS.md, capítulo 2.

El servidor no lleva el estado de progreso (hasta dónde se ha leído). Lo posee el modelo; el servidor solo indica en next_actions "continúa con start=N". Así el servidor es sin estado y la herramienta de escritura se mantiene en una sola: guardar.

Autoverificación

Justo antes de devolver una respuesta se verifican los invariantes; si se rompen, se devuelve un error en lugar de una respuesta incorrecta.

Lo que se detecta aquí no es un problema de entrada del usuario, sino un bug del servidor. Por eso el mensaje de error tampoco dice "revise el archivo", sino "esto es un defecto del servidor; detenga el trabajo y repórtelo".

Observabilidad

Cada llamada a una herramienta queda registrada como una línea en data/traces/YYYY-MM-DD.jsonl.

uv run python scripts/trace_report.py

Lo más importante es lo que no se registra. Si se analizan documentos internos reales, el trace podría convertirse en una copia de esos documentos.

No es una convención, sino que se impone por código y se verifica con pruebas (tests/test_trace.py). Si trace_dir está dentro de allowed_roots, el trace se desactiva solo — para no contaminar la carpeta de análisis con el propio registro.

Las 8 herramientas de lectura tienen todas readOnlyHint: True, pero el trace escribe archivos.

Esa pista significa que no se modifican los documentos de análisis. El trace es un registro de instrumentación fuera de allowed_roots y no se expone a través de ninguna herramienta. Lo único que se expone como herramienta de escritura es save_approved_report, y la prueba de humo verifica esa lista.

Evaluación

uv run python scripts/eval_extract.py

Se contrastan los valores esperados de evals/golden/samples.json con los resultados reales de extracción y el resultado se guarda en evals/reports/. pytest solo indica "¿pasa ahora?", mientras que este informe registra qué pasó y cuándo.

Los valores esperados se escribieron a mano a partir de lo que scripts/make_samples.py introduce en los archivos. No son una copia de la salida del extractor. Si se ajusta el golden set a los resultados, la evaluación se aprueba a sí misma. Los únicos casos legítimos para modificarlo son cuando cambian la convención de anclas, la definición de clases o el contenido de las muestras.

Dependencias

El svg se lee con el xml.etree estándar — 0 dependencias.

Por qué no se usa PyMuPDF (fitz): el rendimiento es mejor, pero al ser AGPL-3.0, incluirlo en una herramienta interna impone condiciones de distribución. Si realmente se necesita extracción de tablas, añada pdfplumber (MIT).

Lo que no se commitea

No coloque los documentos reales de análisis dentro de este repositorio.