file-analysis-mcp

«Lee y resume todos los documentos pdf/docx/pptx/svg/png de esta carpeta.» Un servidor MCP personal para que Claude Code cumpla esa única petición.

Cuando se le indica una carpeta, abre los documentos que contiene y extrae solo el texto tal cual. El resumen y la interpretación no los hace este servidor, sino Claude, que lo invoca durante la conversación; por eso funciona completamente en local y de forma privada, sin necesidad de una clave API de LLM.

Índice

• Cómo funciona en realidad

• Inicio rápido

• Las 5 herramientas

• Registro en Claude Code

• Estructura del proyecto

• Principio de diseño: ingeniería de arnés

Related MCP server: file-analyzer

Cómo funciona en realidad

Este es el resultado de pedírselo a Claude Code con una carpeta real (una carpeta con documentos PRD internos).

Yo: resume los documentos de la carpeta docs y analiza la estructura de archivos

Claude llama sucesivamente a analyze_folder_structure → analyze_folder y, basándose en el texto original devuelto, responde así.

[analyze_folder_structure] pdf 2개, 총 455KB, 최대 파일 prd.pdf(231KB)
[analyze_folder]           2개 파일 모두 추출 성공 (succeeded: 2, failed: 0)

→ Claude의 요약:
두 문서는 같은 프로젝트("ParameterCheck")의 서로 다른 산출물입니다.
- proposal.pdf: RF솔루션 파트의 CAB 파라미터 검증 자동화 기획서
- prd.pdf: 같은 아이디어의 정식 PRD. 목표는 검증 시간 10분→5분 단축,
  MVP는 "파라미터 엑셀 입력 시 집계시트 자동 생성 + 오류 빨강 표시"
공통점: 사람 검토·승인은 항상 최종 단계로 남겨둔다는 원칙이 두 문서 모두에 명시됨.

El servidor solo pasó el texto; todas las frases del resumen anterior las creó Claude. Esta es la separación de roles que persigue este proyecto.

Inicio rápido

# 1) 의존성 설치 (uv 사용)
uv sync --extra dev

# 2) 확인
uv run pytest                        # 유닛테스트
uv run python scripts/smoke_stdio.py # 실제 MCP 프로토콜로 서버를 띄워보는 스모크 테스트

Si necesitas OCR (análisis de PNG), instala Tesseract-OCR por separado; más abajo, en la parte inicial de Registro en Claude Code, tienes las instrucciones. Las otras 4 herramientas funcionan con normalidad incluso sin instalarlo.

Las 5 herramientas

Todas las herramientas son de solo lectura y no modifican ni eliminan archivos. Aunque se alcance el límite (max_files), no omiten archivos en silencio; dejan constancia en la respuesta de cuántos no se pudieron ver, y status pasa a ser PARTIAL para que lo sepas de inmediato.

Registro en Claude Code

Instalación del motor OCR (solo necesario para el análisis de PNG)

pytesseract no es más que el binding de Python para el motor Tesseract-OCR; el motor en sí debe instalarse por separado.

1. Descarga e instala en Windows la compilación de Tesseract de UB-Mannheim. (Si necesitas reconocer coreano, marca Korean en "Additional language data" durante la instalación).

2. Añade la ruta de instalación (por defecto C:\Program Files\Tesseract-OCR) a la variable de entorno PATH del sistema.

3. Comprueba la instalación con tesseract --version.

Registro del servidor

Este repositorio ya incluye un .mcp.json en la raíz. Si ejecutas Claude Code en la carpeta file-analysis-mcp (o en una carpeta superior), se detectará automáticamente. Tras reiniciar, comprueba que ves las 5 herramientas de file-analysis en el comando /mcp o en la lista de herramientas.

Para registrarlo manualmente:

claude mcp add file-analysis -- uv --directory "C:\Users\20223\Desktop\file-analysis-mcp" run python src/file_analysis_mcp/server.py

Flujo recomendado: primero entiende la estructura con analyze_folder_structure → extrae el texto completo de los documentos con analyze_folder → Claude resume a partir del texto extraído.

Estructura del proyecto

file-analysis-mcp/
├── pyproject.toml
├── .mcp.json
├── src/file_analysis_mcp/
│   ├── server.py        # FastMCP 서버, 도구 5개
│   ├── harness.py        # 응답/오류 계약 (BaseResponse, ToolFailure 등)
│   ├── scanner.py         # 폴더 스캔/구조 분석
│   └── extractors/        # pdf/docx/pptx/svg/image 텍스트 추출기
├── scripts/smoke_stdio.py
├── tests/
│   ├── test_scanner.py           # 도메인 로직(순수 함수) 유닛테스트
│   ├── test_extractors.py        # 포맷별 추출기 유닛테스트
│   └── test_server_contract.py   # 하네스 규약(도구 계약) 테스트
└── data/sample_docs/       # 테스트용 샘플 문서

Principio de diseño: ingeniería de arnés

Este servidor prioriza hacer que el modelo, con solo ver la respuesta, sepa qué hacer a continuación por encima de "añadir más funcionalidades". De los principios presentados en awesome-harness-engineering, hemos aplicado selectivamente solo los que encajan con el carácter de este proyecto: local, de un solo usuario y de solo lectura. (La observabilidad con OpenTelemetry, el sandboxing contra inyección de prompts o el gating de aprobación de alcance tipo mcp-guardian están pensados para agentes multiusuario y de larga ejecución; resultan excesivos para una herramienta personal de este tamaño, así que no se han aplicado).

Lo que se ha decidido no aplicar

• Resumen/grounding (verificación de fuentes): no aplica, porque este servidor está diseñado para "solo extraer" (el resumen corresponde al modelo anfitrión).

• Anclas de cita con número de línea (L12 | ...): no se han aplicado porque, sin una herramienta aparte que verifique la base de las citas, solo ensucian el texto. Si llegaran a hacer falta, se pueden añadir reutilizando harness.number_lines().

• Flujo de guardado basado en tokens de aprobación: no aplica, porque este servidor no escribe archivos.