Arquitectura de un MCP avanzado para manipulación de Excel

La mayoría de los servidores MCP (Model Context Protocol) desarrollados para hojas de cálculo sufren del mismo defecto fundamental: son simples envoltorios (wrappers) alrededor de librerías como openpyxl o pandas. Aunque exponer funciones atómicas como read_cell() o write_sheet() funciona para scripts de automatización estructurados, resulta ineficiente e inmanejable para agentes de IA modernos como OpenCode, Claude Code o Cursor.

Al enfrentarse a modelos financieros complejos, auditorías o libros con múltiples pestañas, un agente de IA no necesita modificar celdas a ciegas; requiere comprender la estructura general del archivo, el flujo de las fórmulas, las tablas existentes y el impacto directo de cualquier modificación. La clave para elevar este estándar consiste en construir un verdadero Excel Intelligence Engine expuesto mediante FastMCP en Python.

1. Cambiando el paradigma: Del CRUD al modelo semántico

Si diseñamos la herramienta pensando en cómo trabaja un analista financiero sobre un libro de trabajo, la arquitectura cambia por completo. El agente debe ser capaz de consultar aspectos semánticos de alto nivel sin agotar la ventana de contexto:

• ¿Qué hojas y tablas reales existen en el archivo?
• ¿Qué columnas parecen contener fechas o montos financieros?
• ¿Cuáles son las fórmulas críticas y qué relaciones existen entre pestañas?
• ¿Qué gráficos o tablas dinámicas dependen de un conjunto específico de datos?
• ¿Qué impacto tendría alterar el valor o formato de una columna en todo el modelo?

2. Arquitectura por capas del motor

Para lograr una separación clara de responsabilidades, estructuré el sistema en capas bien definidas que abarcan desde las operaciones básicas de entrada/salida hasta capacidades avanzadas de análisis e IA:

MCP
├── File Layer
├── Workbook Layer
├── Worksheet Layer
├── Table Layer
├── Formula Layer
├── Style Layer
├── Analysis Layer
├── Transformation Layer
├── Validation Layer
└── AI Layer

Cada capa ofrece abstracciones de alto nivel orientadas a las necesidades operativas de los agentes de IA:

Capas fundamentales de lectura y estructura

Además de las funciones estándar de apertura y guardado, la capa de Workbook y Worksheet no entrega únicamente arreglos de datos. Devuelve resúmenes ejecutivos con detección automática de complejidad:

{
  "worksheets": 8,
  "tables": 14,
  "charts": 5,
  "pivot_tables": 2,
  "named_ranges": 17,
  "external_links": 1,
  "macros": false,
  "estimated_complexity": "high"
}

Detección implícita y modelo semántico

Muchos archivos reales carecen de la estructura oficial de "Tabla de Excel", presentando datos dispuestos en rangos arbitrarios. El motor incluye algoritmos para detectar automáticamente tablas no declaradas (por ejemplo, identificando bloques continuos como A1:H320 o J1:Q90) e inferir tipos de datos por columna (fechas, claves primarias, monedas o valores nulos).

Motor de fórmulas y grafo de dependencias

Para evitar la modificación ciega de cálculos, se integraron herramientas como explain_formula(), audit_formula() e impact_analysis(). Al construir un grafo de dependencias entre celdas (A1 → B1 → C1 → Resumen!F4 → Dashboard!B8), el agente puede simular y prever el alcance de un cambio antes de ejecutarlo.

3. Gestión de contexto y Workbook Knowledge Graph

Enviar miles de celdas al contexto del LLM representa la causa principal de fallos, lentitud y costos altos en agentes autónomos. Para solucionar esto, la arquitectura implementa el patrón Workbook Knowledge Graph.

Al abrir un libro de Excel, el motor analiza el archivo y construye en memoria un grafo de conocimiento interno que representa las pestañas, tablas, rangos, fórmulas, validaciones e interrelaciones. Todas las herramientas del MCP consultan y manipulan este grafo antes de sincronizar los cambios en el archivo físico o mediante librerías underlying.

{
  "summary": {
    "worksheets": 12,
    "tables": 9,
    "charts": 7
  },
  "business_entities": [
    "Clientes",
    "Ventas",
    "Inventario"
  ],
  "relationships": [
    "Ventas.ClienteID -> Clientes.ID"
  ],
  "warnings": [
    "3 fórmulas con errores",
    "2 referencias externas"
  ],
  "recommended_entry_points": [
    "Dashboard",
    "Ventas"
  ]
}

Mediante una sola llamada a inspect_workbook(), el agente entiende el panorama completo antes de seleccionar qué herramientas específicas debe ejecutar.

4. De un servidor simple a un SDK modular

Para resolver esto, el diseño separa el proyecto en dos capas principales: un core o SDK independiente (excel-engine) y la capa de transporte del servidor MCP (excel-mcp). La estructura del proyecto organiza claramente cada responsabilidad:

excel-mcp/
├── server.py
├── pyproject.toml
├── requirements.txt
├── README.md
├── CHANGELOG.md
├── LICENSE
├── src/
│   └── excel_mcp/
│       ├── tools/
│       ├── services/
│       ├── analysis/
│       ├── models/
│       ├── cache/
│       ├── io/
│       ├── utils/
│       ├── validators/
│       ├── serializers/
│       ├── prompts/
│       ├── resources/
│       └── schemas/
├── tests/
├── benchmarks/
├── examples/
├── docs/
├── scripts/
└── skills/
    └── excel-engine.md

5. Subsistemas esenciales para producción

Para construir una solución sólida, identificamos subsistemas clave que habitualmente se omiten en integraciones de este tipo:

• Catálogo Central de Herramientas (tool_registry.py): Un registro unificado que define esquemas de entrada/salida, etiquetas, costos estimados y niveles de riesgo de cada función. A partir de este registro se auto-generan la documentación, OpenAPI y las Skills del agente.
• Planning Mode y Dry Run: Permite solicitar al motor un plan preliminar de cambios habilitando dry_run=True. El agente puede revisar cuántas celdas, fórmulas o gráficos serán modificados antes de confirmar la ejecución.
• Snapshots automáticos y Rollback: Creación de puntos de restauración temporales en memoria previa a cualquier lote de escritura, lo que permite revertir el libro a su estado inicial ante cualquier error de validación.
• Batch Operations y Cache de Sesión: En lugar de realizar miles de llamadas atómicas para actualizar datos, el motor expone batch_update() y mantiene un caché de sesión para manejar archivos voluminosos de manera eficiente.
• Golden Files Testing: Conjunto de pruebas automatizadas que compara archivos generados contra versiones de referencia esperadas (Golden Files) para garantizar que no existan regresiones en fórmulas o formatos.

6. El Prompt Maestro de orquestación

Para construir esta plataforma utilizando un agente generador de código como OpenCode o Claude Code, es fundamental proporcionar un prompt estructurado que imponga Clean Architecture y modularidad desde la primera fase:

# MASTER PROMPT — Excel Intelligence Engine MCP
Eres el arquitecto principal y desarrollador líder de un proyecto open source llamado **Excel Intelligence Engine MCP**.
Tu objetivo NO es construir un simple MCP para leer y escribir archivos Excel.
Tu objetivo es construir la mejor plataforma de ingeniería, análisis, comprensión y manipulación de workbooks de Excel, exponiendo todas sus capacidades mediante FastMCP para ser utilizada por agentes de IA como OpenCode, Claude Code, Cursor, VS Code, Windsurf y cualquier cliente compatible con MCP.

## Objetivos del proyecto
- Arquitectura limpia (Clean Architecture).
- Diseño modular y extensible.
- Código fuertemente tipado en Python 3.12+.
- FastMCP como interfaz MCP.
- Documentación generada automáticamente.
- Alta cobertura de pruebas.
- Alto rendimiento con workbooks grandes.
- Compatibilidad con .xlsx, .xlsm, .xlsb, .csv y preparación para .ods.
- Diseño orientado a agentes de IA, minimizando llamadas MCP y consumo de contexto.

## Principios
- Cada herramienta debe hacer una sola cosa.
- Ninguna herramienta debe duplicar funcionalidad.
- Todas las herramientas deben tener schemas de entrada y salida.
- Todas las operaciones modificadoras deben soportar: preview, dry_run, rollback, snapshots.
- Todas las herramientas deben documentarse automáticamente e incluir ejemplos de uso.
- El código debe seguir SOLID y separación estricta entre dominio, infraestructura e interfaz MCP.

## Entregables obligatorios
- server.py, requirements.txt, pyproject.toml, README.md, CHANGELOG.md, LICENSE
- Carpeta docs/, examples/, benchmarks/, tests/, prompts/, skills/, schemas/, resources/, cache/, analysis/, services/, models/, tools/
- Catálogo central de herramientas (tool_registry.py)

## Arquitectura y Capacidades
Capas: IO Layer, Workbook Layer, Worksheet Layer, Table Layer, Formula Layer, Style Layer, Validation Layer, Analysis Layer, AI Layer, Diff Layer, Planning Layer, Cache Layer, Serialization Layer.
Soporte completo para: lectura, escritura, análisis, auditoría, búsqueda, tablas, fórmulas, estilos, gráficos, imágenes, comentarios, hipervínculos, validaciones, nombres definidos, tablas dinámicas, exportación, comparación entre workbooks, generación de resúmenes, explicación de lógica de negocio, análisis de dependencias, detección automática de tablas, inferencia de tipos, detección de anomalías, linaje de datos, planificación de cambios, ejecución por lotes, snapshots, rollback, caché de sesiones.

## Modelo interno
Al abrir un workbook debe construirse un Knowledge Graph interno sobre el cual operarán todas las herramientas antes de guardar cambios físicos.

## Calidad y Forma de trabajo
Trabaja por fases. No avanzas a la siguiente fase sin pruebas, documentación, ejemplos y tipado completo. Revisa la arquitectura al cerrar cada fase.