SheetForge MCP

SheetForge MCP: leer, escribir y reestructurar libros de Excel a través de MCP

GitHub
2
Prueba este MCPPatrocinado

Documentación

SheetForge MCP

Servidor Excel MCP local-first para agentes de IA que necesitan lecturas estructuradas, introspección de libros de trabajo y mutación .xlsx más segura.

SheetForge MCP es un servidor Excel MCP para automatización .xlsx a través del Protocolo de Contexto de Modelo. Está construido para agentes de IA, clientes MCP y flujos de automatización que necesitan más que acceso bruto a celdas: lecturas estructuradas compactas, guía consciente del libro de trabajo, inspección consciente del diseño y rutas de escritura más seguras con Python y openpyxl, sin lanzar Microsoft Excel ni LibreOffice.

Si buscas un servidor Excel MCP para automatización de hojas de cálculo, inspección de libros de trabajo, generación de informes Excel, creación de paneles o edición .xlsx desde herramientas de IA, SheetForge MCP está construido para ese flujo de trabajo.

En lugar de tratar cada hoja como una cuadrícula de celdas ciega, SheetForge ayuda a los agentes a distinguir tablas Excel nativas, conjuntos de datos con forma de hoja de cálculo, paneles con mucho diseño y hojas de gráficos, y luego elegir la ruta de lectura o mutación correcta para cada tarea del libro de trabajo.

Nombre del paquete: sheetforge-mcp Comando CLI: sheetforge-mcp Versión publicada del paquete: 0.10.0 Los documentos del repositorio siguen la superficie de herramientas de la rama principal actual, que actualmente expone 78 herramientas MCP.

Por qué SheetForge

  • lecturas amigables para agentes mediante suggest_read_strategy, describe_dataset, query_table y aggregate_table
  • ediciones de múltiples pasos verificadas mediante apply_workbook_changeset: previsualiza el candidato completo, aserciones de valores/tablas/diseño, diff estructural y cambios de celdas muestreados, luego confirma ese plan exacto solo si el libro de trabajo fuente sigue coincidiendo
  • creación de libros de trabajo y líneas base más seguras: create_workbook se niega a sobrescribir un .xlsx existente, mientras que create_workbook_snapshot crea una copia verificada sin sobrescritura para validación antes/después
  • mutación de libros de trabajo serializada: los escritores del mismo host bloquean cada libro de trabajo antes de cargarlo y mantienen el bloqueo a través del reemplazo atómico y la verificación de reapertura para que los agentes concurrentes no se sobrescriban silenciosamente entre sí
  • límites de hojas de cálculo más inteligentes con presets de lectura acotados strict, default y extended más metadatos compactos para cualquier bloque final omitido intencionalmente
  • conciencia del libro de trabajo y del diseño mediante profile_workbook, describe_sheet_layout, list_tables, list_charts y analyze_range_impact
  • mutación local más segura mediante dry_run, respuestas de escritura compactas, flujos de agregar/actualizar en tablas nativas protegidos y bucles de diff/auditoría/reparación de libros de trabajo
  • rendimiento y privacidad local-first con openpyxl, sin dependencia de Excel de escritorio y sin requisito de autenticación en la nube

Características del Servidor Excel MCP

  • creación de libros de trabajo y metadatos
  • creación, renombrado, copiado, eliminación y visibilidad de hojas de cálculo
  • lecturas estructuradas, lecturas de tablas compactas, consultas de tablas declarativas, agregados agrupados y búsqueda de celdas
  • mutaciones de filas, columnas y rangos
  • fórmulas y comprobaciones de validación
  • formato, paneles congelados, autofiltros, combinaciones y formato condicional
  • tablas Excel nativas, gráficos y resúmenes dinámicos
  • transportes stdio, streamable-http y sse obsoleto

Casos de Uso Comunes

  • agentes de IA que necesitan acceso seguro y estructurado a libros de trabajo Excel a través de MCP
  • flujos de automatización de hojas de cálculo que leen y actualizan informes .xlsx
  • generación de paneles Excel con formato, tablas, gráficos, paneles congelados y configuración de impresión
  • flujos de control de calidad e inspección de libros de trabajo que necesitan metadatos, rangos con nombre, tablas, gráficos y estado de protección
  • extracción de datos de tablas Excel nativas o conjuntos de datos con forma de hoja de cálculo sin scripts openpyxl escritos a mano

Requisitos

  • Python 3.10+
  • libros de trabajo .xlsx
  • ya sea uvx o una instalación local del paquete

Inicio Rápido

Instala y ejecuta directamente desde PyPI con uvx, o instala el paquete localmente en tu entorno Python.

Stdio

Usa stdio cuando el cliente MCP inicia el servidor localmente.

uvx sheetforge-mcp stdio

{
  "mcpServers": {
    "excel": {
      "command": "uvx",
      "args": ["sheetforge-mcp", "stdio"]
    }
  }
}

Streamable HTTP

Usa streamable-http cuando quieras un proceso de servidor local de larga duración.

EXCEL_FILES_PATH=/path/to/excel-files uvx sheetforge-mcp streamable-http

Endpoint predeterminado:

http://127.0.0.1:8017/mcp

Ejemplo de configuración de cliente:

{
  "mcpServers": {
    "excel": {
      "url": "http://127.0.0.1:8017/mcp"
    }
  }
}

La vinculación remota es una opción explícita porque los transportes HTTP no proporcionan autenticación integrada:

FASTMCP_HOST=0.0.0.0 \
SHEETFORGE_ALLOW_REMOTE=true \
EXCEL_FILES_PATH=/path/to/excel-files \
uvx sheetforge-mcp streamable-http

Solo expón un listener remoto detrás de un límite de red autenticado y con control de acceso.

SSE

SSE se mantiene por compatibilidad, pero las nuevas integraciones deberían preferir streamable-http.

EXCEL_FILES_PATH=/path/to/excel-files uvx sheetforge-mcp sse

Endpoint predeterminado:

http://127.0.0.1:8017/sse

Reglas de Rutas de Archivo

  • En modo stdio, los valores filepath deben ser rutas absolutas.
  • En modo streamable-http y sse, las rutas relativas se resuelven bajo EXCEL_FILES_PATH.
  • En modo streamable-http y sse, las rutas absolutas se aceptan solo cuando permanecen dentro de EXCEL_FILES_PATH; se rechazan la navegación al directorio padre y los escapes de enlaces simbólicos.
  • En modo streamable-http y sse, el servidor crea EXCEL_FILES_PATH automáticamente si no existe.

Variables de Entorno

VariablePredeterminadoUsado porPropósito
FASTMCP_HOST127.0.0.1HTTP y SSEDirección de vinculación para el proceso del servidor
FASTMCP_PORT8017HTTP y SSEPuerto para el proceso del servidor
EXCEL_FILES_PATH./excel_filesHTTP y SSEDirectorio base para rutas de libros de trabajo relativas
SHEETFORGE_ALLOW_REMOTEsin establecerHTTP y SSEOpción explícita requerida para cualquier vinculación fuera de loopback; no agrega autenticación

Resumen de Herramientas

El servidor actualmente registra 78 herramientas MCP en estos grupos:

  • resumen del libro de trabajo: create_workbook, create_worksheet, create_workbook_snapshot, get_workbook_metadata, profile_workbook, describe_sheet_layout, audit_workbook, plan_workbook_repairs, apply_workbook_repairs, apply_workbook_changeset, diff_workbooks, analyze_range_impact, explain_formula_cell, detect_circular_dependencies, create_named_range, inspect_named_range, list_named_ranges, delete_named_range, list_all_sheets, list_tables
  • acceso a datos: suggest_read_strategy, describe_dataset, query_table, aggregate_table, bulk_aggregate_workbooks, bulk_filter_workbooks, union_tables, cross_workbook_lookup, quick_read, read_excel_table, read_data_from_excel, read_excel_as_table, search_in_sheet, write_data_to_excel, append_table_rows, append_excel_table_rows, upsert_excel_table_rows, update_rows_by_key
  • cambios en hojas de cálculo y rangos: copy_worksheet, delete_worksheet, rename_worksheet, set_worksheet_visibility, get_worksheet_protection, set_worksheet_protection, copy_range, delete_range, insert_rows, insert_columns, delete_sheet_rows, delete_sheet_columns
  • formato y diseño: format_range, format_ranges, read_range_formatting, freeze_panes, set_autofilter, set_print_area, set_print_titles, set_column_widths, autofit_columns, set_row_heights, merge_cells, unmerge_cells, get_merged_cells
  • fórmulas y validación: apply_formula, validate_formula_syntax, inspect_formula, validate_excel_range, get_data_validation_info, inspect_data_validation_rules, remove_data_validation_rules, inspect_conditional_format_rules, remove_conditional_format_rules
  • análisis y estructura: create_table, list_charts, find_free_canvas, create_chart, create_chart_from_series, create_pivot_table

Para la creación de gráficos, prefiere create_chart como punto de entrada principal:

  • usa data_range para la ruta simple de datos contiguos
  • usa series explícito más categories_range opcional para gráficos no contiguos o creados manualmente
  • usa width y height de nivel superior para controlar el tamaño del gráfico en centímetros; los valores predeterminados son 15 x 7.5
  • usa placement cuando quieras que SheetForge posicione el gráfico en relación con el contenido de la hoja de cálculo, un rango fuente o una tabla con nombre en lugar de adivinar target_cell manualmente
  • usa placement={"relative_to": "free_canvas"} cuando un panel ocupado necesite la primera ranura de gráfico sin superposición en lugar de una regla simple de colocación derecha/abajo
  • mantén create_chart_from_series para compatibilidad hacia atrás o prompts existentes que ya dependen de él

Las herramientas de lectura más amigables para agentes son:

  • suggest_read_strategy: recomienda la mejor herramienta de lectura siguiente para un libro de trabajo objetivo, incluyendo si SheetForge debe tratarlo como una tabla nativa de Excel, un conjunto de datos limpio de hoja de cálculo, una hoja de panel con mucho diseño o una hoja de gráficos
  • describe_dataset: muestrea una hoja de cálculo o tabla nativa de Excel y devuelve encabezados, sugerencias de esquema, conjeturas de claves candidatas, señales estructurales, metadatos de límites de hoja protegidos y una ruta de lectura de seguimiento recomendada
  • query_table: filtra, proyecta, ordena y limita datos con forma de hoja de cálculo o tablas nativas de Excel con una consulta JSON declarativa en lugar de bucles de celdas ad hoc
  • aggregate_table: calcula métricas agrupadas como count, sum, avg, min y max sobre datos con forma de hoja de cálculo o tablas nativas de Excel
  • bulk_aggregate_workbooks: calcula las mismas métricas agrupadas en muchos archivos de libro de trabajo en una sola llamada, con manejo explícito de esquema mediante strict, intersect o union
  • bulk_filter_workbooks: devuelve filas coincidentes en muchos archivos de libro de trabajo con columnas opcionales de procedencia de origen, de modo que las comprobaciones recurrentes de control de calidad y reportes entre archivos ya no necesiten bucles de una llamada de herramienta por archivo
  • union_tables: combina filas comparables de hojas de cálculo o tablas nativas en muchos archivos de libro de trabajo, con claves opcionales de deduplicación y manejo explícito de esquema para colecciones de libros de trabajo que cambian con el tiempo
  • cross_workbook_lookup: enriquece un conjunto de datos de un libro de trabajo con uno o más libros de trabajo de búsqueda con coincidencia estilo left-join, manejo opcional de coincidencias duplicadas y procedencia compacta por fila para filas de búsqueda coincidentes
  • profile_workbook: inventario en una sola llamada de hojas, tablas, gráficos, rangos con nombre y estado clave de diseño/protección, incluido occupied_range de gráficos para gráficos de hoja de cálculo anclados a la cuadrícula
  • describe_sheet_layout: resumen estructural a nivel de hoja de cálculo para ediciones seguras de paneles, incluidos paneles congelados, configuración de impresión, combinaciones, anclas de gráficos, metadatos de tablas, recuentos de formato condicional y validación, tamaño personalizado de filas/columnas y una pequeña vista previa de lienzo libre
  • audit_workbook: auditoría a nivel de libro de trabajo para problemas de alta señal como fórmulas #REF! rotas, celdas con errores, hojas ocultas, problemas de calidad de encabezados, hojas con mucho diseño y rangos con nombre que referencian hojas faltantes
  • plan_workbook_repairs: convierte los hallazgos de auditoría del libro de trabajo en próximos pasos priorizados, incluidas llamadas sugeridas de herramientas de SheetForge para inspección, ejecuciones de prueba seguras y flujos de reparación
  • apply_workbook_repairs: ejecuta en seco o aplica el subconjunto seguro de reparación de esos planes, incluidos rangos con nombre rotos, reglas de validación rotas, formatos condicionales rotos y revelación opcional de hojas ocultas
  • apply_workbook_changeset: previsualiza una mutación de reporte multiherramienta acotada en un candidato aislado, evalúa postcondiciones explícitas y la confirma con protección exacta contra escrituras obsoletas más instantánea verificada opcional y reversión
  • diff_workbooks: compara dos archivos de libro de trabajo e informa cambios estructurales más diferencias muestreadas de valores de celda, lo cual es útil para verificación antes/después en flujos de agente
  • create_workbook_snapshot: crea la línea base verificada y sin sobrescritura que hace que diff_workbooks sea utilizable sin un script de copia externo
  • analyze_range_impact: verificación previa del radio de impacto para un rango de hoja de cálculo, incluidas superposiciones con tablas, huellas de gráficos, celdas combinadas, rangos con nombre, validaciones de datos, formatos condicionales, autofiltros, áreas de impresión, celdas de fórmula dentro del rango y fórmulas o expresiones de reglas en otro lugar que dependan de él directa o transitivamente, a través de rangos con nombre o referencias estructuradas de tabla como Table1[Sales]
  • explain_formula_cell: resuelve las referencias directas de una celda de fórmula, muestra celdas de la cadena de fórmulas aguas arriba, devuelve un resumen compacto formula_chain con capas de profundidad y rutas muestreadas, e informa dependientes aguas abajo para que los agentes puedan depurar la lógica del libro de trabajo sin rastreo manual
  • detect_circular_dependencies: escanea los grafos de fórmulas del libro de trabajo, incluidos los bordes impulsados por rangos con nombre, e informa autorreferencias y grupos de dependencias circulares multicelda antes de que sorprendan a la automatización aguas abajo
  • create_named_range: crea rangos con nombre a nivel de libro de trabajo o con ámbito de hoja con soporte de dry_run y replace, de modo que los agentes puedan promover regiones importantes del libro de trabajo a referencias estables sin recurrir a Python ad hoc
  • inspect_formula: inspecciona una cadena de fórmula sin contexto de libro de trabajo, enumerando funciones, tipos de tokens de referencia, funciones volátiles y funciones riesgosas como INDIRECT
  • inspect_named_range: inspecciona un nombre definido, incluidos su ámbito, destinos y si apunta a hojas faltantes o referencias rotas
  • quick_read: lectura compacta de tabla en una sola llamada que selecciona automáticamente la primera hoja cuando es necesario, con límites protegidos de strict / default / extended, paginación start_row y ventanas de columna start_col / end_col para hojas grandes
  • read_excel_table: lee una tabla nativa de Excel por table_name sin adivinar límites de hoja, ahora con paginación start_row y ventanas opcionales de columna de tabla start_col / end_col
  • list_all_sheets: inventario rápido de libro de trabajo con tamaños de hoja, indicadores de vacío y sheet_type para hojas de cálculo frente a hojas de gráficos
  • read_excel_as_table: salida compacta headers + rows para conjuntos de datos estructurados, con presets de límites protegidos, compact=True para la carga útil más pequeña, start_row para lecturas tipo página y start_col / end_col para rebanadas de columna más estrechas
  • read_data_from_excel: lector de rango consciente de direcciones de celda que admite ventanas max_rows y max_cols para rangos grandes no tabulares, values_only=True para cargas útiles 2D más pequeñas y continuaciones basadas en cursor para recorrido 2D en varios pasos
  • read_range_formatting: lectura compacta de formato para un rango de hoja de cálculo, agrupada por firmas de estilo distintas en lugar de volcados ruidosos por celda, con resúmenes de superposición de rangos combinados y formato condicional
  • search_in_sheet: búsqueda de valores exacta o parcial en celdas de hoja de cálculo instanciadas, de modo que las celdas distantes solo de estilo no obliguen a escanear todo el rango rectangular usado

Las herramientas de inventario de libro de trabajo como list_all_sheets, profile_workbook y list_charts muestran tanto hojas de cálculo como hojas de gráficos. Las herramientas orientadas a cuadrícula como quick_read, read_excel_table, create_table, formato, fórmulas y validación requieren una hoja de cálculo real y devuelven un error claro de hoja de gráficos si apuntas al tipo de hoja incorrecto.

Los ayudantes de escritura más amigables para agentes para datos estructurados son:

  • upsert_excel_table_rows: actualiza filas coincidentes en una tabla nativa de Excel y agrega claves faltantes en una sola llamada Nota: las tablas con fila de totales son solo de actualización por ahora; los intentos de agregar se rechazan en lugar de desplazar filas no relacionadas.
  • append_excel_table_rows: agrega filas a una tabla nativa de Excel cuando quieres que el ref de la tabla crezca con los nuevos registros
  • append_table_rows: agrega filas conscientes de encabezados a datos con forma de hoja de cálculo cuando no tienes una tabla nativa de Excel
  • update_rows_by_key: actualiza datos con forma de hoja de cálculo por una columna de clave nombrada sin agregar claves faltantes

Para los lectores compactos de tablas (quick_read, read_excel_as_table, read_excel_table):

  • row_mode="arrays" mantiene la forma headers + rows más pequeña
  • row_mode="objects" devuelve records claveado por nombres de campo normalizados como first_name
  • los nombres de campo normalizados son transliteraciones seguras para ASCII, por lo que encabezados como Näyttökerrat se convierten en nayttokerrat
  • infer_schema=True añade sugerencias ligeras de schema inferidas de las filas devueltas
  • start_col / end_col te permiten recortar hojas de cálculo anchas o tablas nativas de Excel a solo las columnas que necesitas antes de la paginación o la inferencia de esquema
  • las páginas truncadas ahora incluyen next_start_row, que puedes pasar de vuelta a la misma herramienta para la siguiente página
  • las lecturas de rangos no tabulares también pueden devolver tokens de cursor continuations.down y continuations.right para que los agentes puedan continuar con ventanas 2D grandes sin recalcular coordenadas
  • suggest_read_strategy ayuda a los agentes a elegir entre lecturas conscientes de tablas, hojas, rangos y orientación de libro de trabajo antes de gastar contexto en la ruta incorrecta
  • describe_dataset proporciona un resumen de conjunto de datos más ligero que una lectura completa, incluyendo filas de muestra, calidad de encabezado, candidatos clave y la siguiente herramienta recomendada
  • describe_dataset, quick_read, read_excel_as_table y read_excel_table ahora también devuelven structure_token, content_token y snapshot_metadata, para que los agentes puedan llevar la identidad de lectura hacia adelante en escrituras más seguras de concurrencia optimista
  • los lectores compactos con forma de hoja de cálculo y los ayudantes de mutación de filas favorecen el primer bloque de datos contiguo después del encabezado, por lo que las notas de pie de página dispersas o las filas atípicas distantes no estiran silenciosamente total_rows, los objetivos de anexado o los escaneos de actualización basados en claves
  • las lecturas de hojas pueden optar por read_boundary_mode="strict" (0 filas en blanco), "default" (5) o "extended" (100); los ajustes preestablecidos acotados evitan deliberadamente un parámetro de brecha bruta ilimitado
  • describe_dataset, quick_read y read_excel_as_table exponen un objeto read_boundary con la tolerancia efectiva, el final de datos, el recuento de filas ignoradas y las ubicaciones compactas del bloque final
  • las vistas de límites no predeterminadas son diagnósticos de solo lectura y devuelven write_precondition_compatible=false; vuelve a leer con el modo predeterminado antes de llevar un token de estructura a una escritura
  • query_table es la forma más ligera de extraer solo las filas y columnas coincidentes que necesitas de un conjunto de datos de hoja de cálculo o una tabla nativa de Excel
  • query_table y bulk_filter_workbooks aceptan ne como abreviatura de neq, y los filtros de membresía pueden usar values o la forma de lista más corta value
  • aggregate_table permite a los agentes calcular resúmenes agrupados directamente en SheetForge en lugar de sobreleer el conjunto de datos completo en el contexto primero
  • bulk_aggregate_workbooks extiende ese patrón a muchos archivos de libro de trabajo cuando un flujo de trabajo de informes recurrente necesitaría Python ad hoc o llamadas repetidas a herramientas por archivo
  • las métricas agregadas aceptan tanto la forma canónica {"op": "sum", "field": "Sales", "as": "total_sales"} como la forma de alias más adivinable {"agg": "sum", "column": "Sales", "as": "total_sales"}
  • bulk_filter_workbooks hace lo mismo para la inspección a nivel de fila, manteniendo la procedencia del libro de trabajo visible por defecto
  • union_tables es la forma más rápida de normalizar muchos conjuntos de datos de libros de trabajo comparables en una carga tabular combinada antes del control de calidad posterior, exportación o agregación adicional
  • cross_workbook_lookup es la forma más rápida de enriquecer un libro de trabajo desde otro sin escribir un script de fusión ad hoc, especialmente para búsquedas de datos maestros, enriquecimiento de estado y flujos de trabajo de control de calidad entre archivos
  • append_excel_table_rows es la ruta de anexado correcta para tablas nativas de Excel cuando no necesitas comportamiento de actualización basado en claves
  • append_table_rows ahora se niega a escribir directamente debajo de una tabla nativa de Excel adyacente y te señala a append_excel_table_rows en lugar de dejar silenciosamente el rango de la tabla obsoleto
  • las escrituras estructuradas conscientes de tokens pueden pasar expected_structure_token para abortar en desviación estructural; las escrituras de estilo anexado requieren adicionalmente allow_structure_change=True, y las escrituras exitosas informan tanto los tokens de estructura/contenido anteriores como los nuevos
  • rename_worksheet ahora actualiza celdas de fórmula así como referencias de gráficos y rangos nombrados, y también renombra la hoja pivote hermana predeterminada (Data_pivot -> Revenue_pivot) cuando ese movimiento no tiene conflictos
  • copy_worksheet preserva tablas nativas con nombres copiados únicos en el libro, validaciones de datos, formato condicional, paneles congelados, autofiltros, configuración de impresión, protección, gráficos con su geometría de anclaje exacta y nombres con ámbito de hoja; las autorreferencias copiadas y las referencias de tablas estructuradas se reescriben a la nueva hoja
  • las entradas de color de formato aceptan RRGGBB, #RRGGBB, AARRGGBB o #AARRGGBB, por lo que las indicaciones no necesitan eliminar los prefijos de estilo CSS # primero
  • audit_workbook es la verificación previa más rápida a nivel de libro cuando necesitas saber si una hoja de cálculo es segura y predecible suficiente para edición autónoma
  • audit_workbook ahora trata las hojas dominantes de tablas nativas de manera más honesta cuando los artefactos de panel/diseño cercanos extienden el rango utilizado, por lo que las áreas de gráficos combinados no relacionados no crean un riesgo falso de encabezado en blanco en una tabla limpia
  • plan_workbook_repairs es la forma más rápida de convertir esos hallazgos de auditoría en una cola de acciones real en lugar de decidir manualmente la siguiente llamada a herramienta para cada problema
  • apply_workbook_repairs permite a los agentes previsualizar o aplicar el subconjunto seguro de esas reparaciones sin tener que orquestar manualmente cada artefacto roto del libro
  • diff_workbooks es el pase de control de calidad antes/después más rápido cuando un agente ha tocado la estructura del libro y quiere prueba de lo que realmente cambió

Flujos de Trabajo Recomendados para Agentes

  1. Libro desconocido -> mutación verificada de múltiples pasos Comienza con profile_workbook (o list_all_sheets para el inventario más ligero), inspecciona las pestañas con mucho diseño con describe_sheet_layout y ejecuta analyze_range_impact. Coloca las ediciones de construcción de informes compatibles y las condiciones posteriores explícitas en apply_workbook_changeset(mode="preview"); si ready_to_commit=true, repite el mismo plan con mode="commit", expected_workbook_sha256 y changeset_token desde la vista previa.
  2. Bucle de reparación de libros Usa audit_workbook para encontrar problemas de alta señal, plan_workbook_repairs para convertirlos en una cola de acciones, apply_workbook_repairs(..., dry_run=True) para previsualizar el subconjunto seguro, luego vuelve a ejecutar audit_workbook después de aplicar las reparaciones para confirmar que el libro ha vuelto a un estado de bajo riesgo.
  3. Informes de múltiples libros Usa bulk_aggregate_workbooks, bulk_filter_workbooks, union_tables o cross_workbook_lookup para construir primero el conjunto de datos de informes, luego escribe las filas resumidas en una pestaña nueva del libro y termina la capa de presentación con format_ranges, find_free_canvas, create_chart y autofit_columns.

Consulta TOOLS.md para la referencia completa. Las notas de versión están en CHANGELOG.md.

Formato de Respuesta

Cada herramienta ahora devuelve un sobre JSON con una forma superior consistente:

{
  "ok": true,
  "operation": "read_excel_as_table",
  "message": "read_excel_as_table completed",
  "data": {}
}

Las respuestas de error siguen el mismo contrato:

{
  "ok": false,
  "operation": "write_data_to_excel",
  "error": {
    "type": "DataError",
    "message": "No data provided to write"
  }
}

Para herramientas destructivas que admiten modo de vista previa, el sobre también puede incluir dry_run y changes. Las operaciones de escritura confirmadas ahora usan resúmenes compactos por defecto; pasa include_changes=True cuando quieras detalle por celda, por rango o por operación.

Desarrollo

Instala las dependencias:

uv sync --extra dev

Ejecuta las pruebas:

uv run --extra dev pytest -q

Ejecuta las verificaciones de lint:

uv run --extra dev ruff check src tests

Ejecuta el paquete localmente:

uv run sheetforge-mcp stdio

Construye distribuciones localmente:

uv build

Flujo de Publicación

  • Actualiza pyproject.toml, manifest.json y el paquete .mcpb rastreado juntos para cada publicación.
  • Mantén el nombre del archivo del paquete rastreado sincronizado con la versión del paquete, por ejemplo sheetforge-mcp-<version>.mcpb.
  • Cada flujo de trabajo de construcción de distribución verifica la rueda, la distribución fuente y el paquete MCPB rastreado contra listas de permitidos de artefactos públicos compartidos antes de la publicación.
  • Las publicaciones de GitHub ejecutan solo un flujo de trabajo de verificación de construcción.
  • La publicación en PyPI es un flujo de trabajo manual separado, por lo que las publicaciones no crean una implementación fallida antes de que Trusted Publisher esté configurado para el paquete.

Estructura del Repositorio

  • src/excel_mcp/server.py: servidor MCP, configuración de transporte y registro de herramientas
  • src/excel_mcp/workbook.py: ayudantes del ciclo de vida del libro y metadatos del libro
  • src/excel_mcp/changeset.py: transacciones verificadas de vista previa/confirmación de múltiples operaciones y aserciones
  • src/excel_mcp/data.py: ayudantes de lectura, escritura, tabla y búsqueda
  • src/excel_mcp/sheet.py: mutaciones de hojas y rangos
  • tests/: pruebas de regresión que cubren datos, diseño, gráficos, tablas dinámicas, formato, tablas y seguridad de recursos
  • scripts/verify_release_artifacts.py: verificador de contenido wheel/sdist/MCPB compartido utilizado por CI y flujos de publicación
  • manifest.json: metadatos del paquete MCP empaquetado
  • docs/index.html: página de destino estática del proyecto

Por Qué SheetForge MCP

  • Superficie MCP centrada en Excel: el conjunto de herramientas se enfoca en operaciones reales de libros de trabajo .xlsx, no en E/S de archivos genérica
  • respuestas amigables para agentes: sobres JSON consistentes, escrituras compactas y vistas previas dry_run reducen el desperdicio de contexto
  • introspección de libros: profile_workbook, list_all_sheets, list_tables y list_charts hacen que las hojas de cálculo desconocidas sean más fáciles de navegar
  • ediciones más seguras: analyze_range_impact da a los agentes una verificación previa de solo lectura antes de sobrescribir, eliminar o reestructurar un rango importante, incluyendo cadenas de fórmulas posteriores más referencias de reglas de validación y formato condicional en otras partes del libro incluso cuando las fórmulas apuntan al rango a través de rangos nombrados o referencias de tablas estructuradas
  • transacciones verificadas: apply_workbook_changeset vincula un plan acotado de operación/aserción a la ruta canónica de destino y al SHA-256 exacto de la fuente, lo prueba en un candidato aislado, verifica celdas, tablas, paneles congelados, autofiltros y colocación de gráficos, y reemplaza la fuente solo una vez después de que todas las verificaciones pasen
  • planificación de diseño: find_free_canvas sugiere espacios vacíos seguros para gráficos o bloques de panel antes de colocarlos, usando por defecto la huella estándar de gráficos cuando omites el tamaño explícito
  • salida práctica de Excel: formato, configuración de impresión, protección de hojas, actualizaciones de tablas, creación de gráficos y ayudantes de ajuste automático cubren flujos de trabajo de informes reales
  • ajuste al ecosistema Python: construido sobre openpyxl, empaquetado para uvx y fácil de ejecutar localmente sobre stdio o a través de una implementación HTTP deliberadamente restringida

Notas para Integradores

  • stdio tiene cuidado de no escribir texto no relacionado con el protocolo en stdout.
  • Todas las herramientas devuelven sobres JSON estructurados, lo que hace predecible el análisis en el lado del cliente.
  • Las respuestas de las herramientas ahora usan serialización JSON compacta para reducir el tamaño del payload de MCP manteniendo la misma forma de sobre.
  • read_data_from_excel(..., preview_only=True) limita la respuesta a las primeras 10 filas en el rango seleccionado y marca el payload como truncado cuando corresponde.
  • read_data_from_excel(..., compact=True) omite los stubs de validación predeterminados para celdas que no tienen reglas de validación.
  • read_data_from_excel(..., values_only=True) devuelve un arreglo 2D plano de values para lecturas de rango que no necesitan direcciones por celda ni metadatos de validación.
  • read_data_from_excel(..., max_rows=...) pagina rangos rectangulares altos y devuelve next_start_row más next_start_cell cuando quedan más filas.
  • read_data_from_excel(..., max_cols=...) pagina rangos rectangulares anchos y devuelve next_start_col más next_column_start_cell cuando quedan más columnas.
  • read_data_from_excel(..., cursor=...) se reanuda desde un token de continuación para que los agentes puedan seguir paginando sin recalcular la siguiente ventana manualmente; las ventanas 2D exponen continuaciones direccionales bajo continuations.down y continuations.right.
  • read_excel_as_table(..., compact=True) minimiza el payload tabular a headers y rows a menos que se necesiten metadatos de truncamiento, mientras sigue devolviendo metadatos de identidad del conjunto de datos.
  • Los lectores tabulares compactos aún incluyen structure_token, content_token y snapshot_metadata, incluso cuando el payload tabular en sí está minimizado.
  • quick_read(..., start_row=...) y read_excel_as_table(..., start_row=...) permiten a los agentes paginar hojas de cálculo profundas sin leer primero desde la parte superior.
  • quick_read(..., start_col=..., end_col=...) y read_excel_as_table(..., start_col=..., end_col=...) permiten a los agentes solicitar solo las columnas relevantes de hojas de cálculo anchas en lugar de traer todas las columnas al contexto.
  • read_excel_table(..., start_col=..., end_col=...) ahora admite los mismos cortes de columnas más estrechos para tablas nativas de Excel, siempre que las columnas solicitadas estén dentro del rango de la tabla.
  • quick_read(..., include_headers=False), read_excel_as_table(..., include_headers=False) y read_excel_table(..., include_headers=False) permiten que las páginas siguientes omitan el payload de encabezado repetido una vez que la primera página ya estableció el esquema.
  • read_excel_table(..., start_row=...) ahora admite paginación más profunda en tablas nativas de Excel en lugar de leer siempre desde la parte superior.
  • Las lecturas tabulares truncadas ahora devuelven next_start_row para que los agentes puedan continuar paginando sin recalcular desplazamientos.
  • Las respuestas de lectura sobredimensionadas ahora fallan temprano con ResponseTooLargeError más hints estructurado, para que los agentes puedan reintentar con rangos más pequeños o paginación antes de que el cliente trunque el payload.
  • quick_read, read_excel_as_table y read_excel_table ahora pueden devolver records más pistas de schema inferidas cuando se opta por row_mode="objects" y infer_schema=True.
  • Las herramientas de lectura no recalculan fórmulas de Excel; las celdas con fórmulas aparecen como texto de fórmula como =B2*C2, y el esquema inferido etiqueta las columnas respaldadas por fórmulas como formula para que los agentes no las confundan con valores numéricos frescos.
  • profile_workbook proporciona un inventario de libro de trabajo en una sola llamada con metadatos de tablas, gráficos, protección, impresión y filtros a nivel de hoja para una orientación más rápida del agente, y ahora incluye occupied_range de gráficos junto con anclas y dimensiones para gráficos de hoja anclados a la cuadrícula.
  • Las herramientas de mutación principales ahora usan respuestas compactas por defecto en escrituras confirmadas, incluyendo escrituras de datos, formato, ayudantes de diseño de hojas y ayudantes de combinar/dividir. Use include_changes=True para diferencias detalladas.
  • Las escrituras estructuradas conscientes de tokens ahora devuelven previous_structure_token, new_structure_token, previous_content_token, new_content_token y snapshot_metadata, lo que hace que los flujos multiagente o de lectura-luego-escritura sean más seguros sin agregar metadatos ocultos del libro de trabajo.
  • Las versiones dry_run de esas escrituras estructuradas ahora etiquetan los metadatos de vista previa como token_basis="dry_run_preview" y mantienen los hechos del archivo en disco bajo source_file_*, de modo que los tokens de vista previa ya no se mezclan con los metadatos del archivo en vivo.
  • Los guardados de libros de trabajo que pasan por safe_workbook(..., save=True) usan un bloqueo de libro de trabajo en el mismo host consciente de tiempo de espera más guardado en archivo temporal, fsync, reemplazo atómico, reversión ante fallo de verificación y verificación de reapertura. Las rutas de enlaces simbólicos actualizan su destino real sin reemplazar el enlace simbólico en sí. Si la reversión automática falla, la copia de seguridad de recuperación se conserva y se identifica en el error. Esto protege a los procesos cooperativos de SheetForge en una máquina; no es un bloqueo distribuido para proveedores de sincronización en la nube.
  • format_ranges agrupa múltiples operaciones de formato en una sola pasada del libro de trabajo e informa errors por rango sin descartar rangos exitosos. Un rango fallido se revierte a sus estilos, valores, comentarios, hipervínculos, estado de combinación y reglas de formato condicional previos a la operación antes de que el lote continúe.
  • validate_formula_syntax realiza validación estructural de tokens, verifica los límites de coordenadas de Excel y rechaza funciones riesgosas como INDIRECT, HYPERLINK, WEBSERVICE, DGET y RTD sin distinguir mayúsculas de minúsculas. No calcula fórmulas ni reemplaza el motor de cálculo propio de Excel.
  • write_data_to_excel sigue siendo una primitiva de escritura de celdas en bruto y puede almacenar cadenas de fórmula directamente; úsela solo con datos confiables, o use apply_formula cuando desee las verificaciones de seguridad de fórmulas de SheetForge.
  • Los registros del servidor rotan a 5 MiB con dos copias de seguridad en lugar de crecer sin límite.
  • autofit_columns estima anchos de columna prácticos a partir del contenido actual de las celdas, con filtros de columna opcionales y límites mínimos/máximos.
  • list_charts ahora informa width y height de gráficos en centímetros además de ancla, tipo y metadatos de serie.
  • get_worksheet_protection y set_worksheet_protection agregan un envoltorio seguro a nivel de hoja alrededor de los indicadores de protección de Excel.
  • set_print_area y set_print_titles hacen que la configuración de informes/exportación sea programable sin recurrir a los internos crudos de openpyxl del libro de trabajo.
  • list_tables ahora devuelve metadatos de esquema ligeros como encabezados, recuentos de filas y configuraciones de bandas además de nombres y rangos de tablas.
  • upsert_excel_table_rows expande automáticamente los rangos de tablas nativas de Excel cuando agrega claves faltantes, se niega a hacer crecer una tabla hacia celdas ya ocupadas y rechaza intentos de agregar cuando la tabla objetivo tiene una fila de totales habilitada.
  • Las herramientas de mutación principales admiten dry_run=True para que los clientes puedan previsualizar cambios antes de guardar un libro de trabajo.

Licencia

MIT. Ver LICENCIA.