SheetForge MCP

Leia, escreva e reformate pastas de trabalho do Excel via MCP.

GitHub
2
Experimente este MCPPatrocinado

Documentação

SheetForge MCP

Servidor Excel MCP local-first para agentes de IA que precisam de leituras estruturadas, introspecção de pastas de trabalho e mutação .xlsx mais segura.

O SheetForge MCP é um servidor Excel MCP para automação de .xlsx através do Model Context Protocol. Ele é construído para agentes de IA, clientes MCP e fluxos de automação que precisam de mais do que acesso bruto a células: leituras estruturadas compactas, orientação ciente da pasta de trabalho, inspeção ciente do layout e caminhos de escrita mais seguros com Python e openpyxl, sem iniciar o Microsoft Excel ou o LibreOffice.

Se você está procurando um servidor Excel MCP para automação de planilhas, inspeção de pastas de trabalho, geração de relatórios Excel, criação de dashboards ou edição de .xlsx a partir de ferramentas de IA, o SheetForge MCP é construído para esse fluxo de trabalho.

Em vez de tratar cada planilha como uma grade de células cega, o SheetForge ajuda os agentes a distinguir tabelas Excel nativas, conjuntos de dados em formato de planilha, dashboards com muito layout e planilhas de gráfico, e então escolher o caminho certo de leitura ou mutação para cada tarefa na pasta de trabalho.

Nome do pacote: sheetforge-mcp Comando CLI: sheetforge-mcp Versão publicada do pacote: 0.10.0 A documentação do repositório acompanha a superfície de ferramentas do branch principal atual, que atualmente expõe 78 ferramentas MCP.

Por que SheetForge

  • leituras amigáveis para agentes via suggest_read_strategy, describe_dataset, query_table e aggregate_table
  • edições multi-etapas verificadas via apply_workbook_changeset: visualize o candidato completo, asserções de valor/tabela/layout, diff estrutural e amostras de alterações de células, depois confirme esse plano exato somente se a pasta de trabalho de origem ainda corresponder
  • criação de pastas de trabalho e linhas de base mais seguras: create_workbook se recusa a sobrescrever um .xlsx existente, enquanto create_workbook_snapshot cria uma cópia verificada sem sobrescrita para validação antes/depois
  • mutação serializada de pastas de trabalho: escritores no mesmo host bloqueiam cada pasta de trabalho antes de carregá-la e mantêm o bloqueio durante a substituição atômica e a verificação de reabertura, para que agentes concorrentes não se sobrescrevam silenciosamente
  • limites de planilha mais inteligentes com predefinições de leitura strict, default e extended limitadas, além de metadados compactos para quaisquer blocos finais intencionalmente omitidos
  • consciência de pasta de trabalho e layout via profile_workbook, describe_sheet_layout, list_tables, list_charts e analyze_range_impact
  • mutação local mais segura através de dry_run, respostas de escrita compactas, fluxos protegidos de anexar/atualizar tabelas nativas e loops de diff/auditoria/reparação de pastas de trabalho
  • desempenho e privacidade local-first com openpyxl, sem dependência de Excel desktop e sem exigência de autenticação em nuvem

Recursos do Servidor Excel MCP

  • criação de pastas de trabalho e metadados
  • criação, renomeação, cópia, exclusão e visibilidade de planilhas
  • leituras estruturadas, leituras compactas de tabelas, consultas declarativas de tabelas, agregações agrupadas e busca de células
  • mutações de linhas, colunas e intervalos
  • fórmulas e verificações de validação
  • formatação, congelamento, autofiltros, mesclagens e formatação condicional
  • tabelas Excel nativas, gráficos e resumos de tabelas dinâmicas
  • transportes stdio, streamable-http e sse obsoleto

Casos de Uso Comuns

  • agentes de IA que precisam de acesso seguro e estruturado a pastas de trabalho Excel via MCP
  • fluxos de automação de planilhas que leem e atualizam relatórios .xlsx
  • geração de dashboards Excel com formatação, tabelas, gráficos, painéis congelados e configuração de impressão
  • fluxos de QA e inspeção de pastas de trabalho que precisam de metadados, intervalos nomeados, tabelas, gráficos e estado de proteção
  • extração de dados de tabelas Excel nativas ou conjuntos de dados em formato de planilha sem scripts openpyxl escritos manualmente

Requisitos

  • Python 3.10+
  • pastas de trabalho .xlsx
  • uvx ou uma instalação local do pacote

Início Rápido

Instale e execute diretamente do PyPI com uvx, ou instale o pacote localmente no seu ambiente Python.

Stdio

Use stdio quando o cliente MCP iniciar o servidor localmente.

uvx sheetforge-mcp stdio

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

Streamable HTTP

Use streamable-http quando você quiser um processo de servidor local de longa duração.

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

Endpoint padrão:

http://127.0.0.1:8017/mcp

Exemplo de configuração do cliente:

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

A vinculação remota é uma adesão explícita porque os transportes HTTP não fornecem autenticação integrada:

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

Exponha um listener remoto somente atrás de um limite de rede autenticado e com controle de acesso.

SSE

O SSE é mantido para compatibilidade, mas novas integrações devem preferir streamable-http.

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

Endpoint padrão:

http://127.0.0.1:8017/sse

Regras de Caminhos de Arquivo

  • No modo stdio, os valores de filepath devem ser caminhos absolutos.
  • Nos modos streamable-http e sse, caminhos relativos são resolvidos sob EXCEL_FILES_PATH.
  • Nos modos streamable-http e sse, caminhos absolutos são aceitos somente quando permanecem dentro de EXCEL_FILES_PATH; travessia de diretório pai e escapes de symlink são rejeitados.
  • Nos modos streamable-http e sse, o servidor cria EXCEL_FILES_PATH automaticamente se ele não existir.

Variáveis de Ambiente

VariávelPadrãoUsada porFinalidade
FASTMCP_HOST127.0.0.1HTTP e SSEEndereço de vinculação para o processo do servidor
FASTMCP_PORT8017HTTP e SSEPorta para o processo do servidor
EXCEL_FILES_PATH./excel_filesHTTP e SSEDiretório base para caminhos relativos de pastas de trabalho
SHEETFORGE_ALLOW_REMOTEnão definidoHTTP e SSEAdesão explícita obrigatória para qualquer vinculação fora de loopback; não adiciona autenticação

Visão Geral das Ferramentas

O servidor atualmente registra 78 ferramentas MCP nos seguintes grupos:

  • visão geral da pasta de trabalho: 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
  • acesso a dados: 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
  • alterações em planilhas e intervalos: 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
  • formatação e layout: 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 e validação: 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álise e estrutura: create_table, list_charts, find_free_canvas, create_chart, create_chart_from_series, create_pivot_table

Para criação de gráficos, prefira create_chart como ponto de entrada principal:

  • use data_range para o caminho simples de dados contíguos
  • use series explícito mais categories_range opcional para gráficos não contíguos ou criados manualmente
  • use width e height de nível superior para controlar o tamanho do gráfico em centímetros; os padrões são 15 x 7.5
  • use placement quando você quiser que o SheetForge posicione o gráfico em relação ao conteúdo da planilha, a um intervalo de origem ou a uma tabela nomeada, em vez de adivinhar target_cell manualmente
  • use placement={"relative_to": "free_canvas"} quando um dashboard movimentado precisar do primeiro espaço de gráfico sem sobreposição, em vez de uma regra simples de posicionamento à direita/abaixo
  • mantenha create_chart_from_series para compatibilidade retroativa ou prompts existentes que já dependem dele

As ferramentas de leitura mais amigáveis para agentes são:

  • suggest_read_strategy: recomenda a melhor ferramenta de leitura seguinte para um alvo de pasta de trabalho, incluindo se o SheetForge deve tratá-la como uma tabela nativa do Excel, um conjunto de dados limpo de planilha, uma planilha de painel com muito layout ou uma planilha de gráfico
  • describe_dataset: amostra uma planilha ou tabela nativa do Excel e retorna cabeçalhos, sugestões de esquema, palpites de chaves candidatas, sinais estruturais, metadados protegidos de limites de planilha e um caminho de leitura recomendado como próximo passo
  • query_table: filtra, projeta, ordena e limita dados em formato de planilha ou tabelas nativas do Excel com uma consulta JSON declarativa, em vez de loops ad hoc de células
  • aggregate_table: calcula métricas agrupadas como count, sum, avg, min e max sobre dados em formato de planilha ou tabelas nativas do Excel
  • bulk_aggregate_workbooks: calcula as mesmas métricas agrupadas em muitos arquivos de pasta de trabalho em uma única chamada, com tratamento explícito de esquema via strict, intersect ou union
  • bulk_filter_workbooks: retorna linhas correspondentes em muitos arquivos de pasta de trabalho com colunas opcionais de proveniência da fonte, para que verificações recorrentes de QA e relatórios entre arquivos não exijam mais loops de uma chamada por arquivo
  • union_tables: combina linhas comparáveis de planilhas ou tabelas nativas em muitos arquivos de pasta de trabalho, com chaves opcionais de deduplicação e tratamento explícito de esquema para coleções de pastas de trabalho que mudam ao longo do tempo
  • cross_workbook_lookup: enriquece um conjunto de dados de uma pasta de trabalho com um ou mais arquivos de consulta usando correspondência estilo left join, tratamento opcional de correspondências duplicadas e proveniência compacta por linha para linhas de consulta correspondentes
  • profile_workbook: inventário em uma única chamada de planilhas, tabelas, gráficos, intervalos nomeados e estado principal de layout/proteção, incluindo occupied_range de gráfico para gráficos de planilha ancorados em grade
  • describe_sheet_layout: resumo estrutural em nível de planilha para edições seguras de painéis, incluindo painéis congelados, configurações de impressão, mesclagens, âncoras de gráfico, metadados de tabela, contagens de formatação condicional e validação, dimensionamento personalizado de linhas/colunas e uma pequena prévia de tela livre
  • audit_workbook: auditoria em nível de pasta de trabalho para problemas de alto sinal, como fórmulas #REF! quebradas, células de erro, planilhas ocultas, problemas de qualidade de cabeçalho, planilhas com muito layout e intervalos nomeados que referenciam planilhas ausentes
  • plan_workbook_repairs: converte descobertas de auditoria de pasta de trabalho em próximos passos priorizados, incluindo chamadas sugeridas de ferramentas do SheetForge para inspeção, execuções de teste seguras e fluxos de reparo
  • apply_workbook_repairs: executa em modo de teste ou aplica o subconjunto seguro de reparos desses planos, incluindo intervalos nomeados quebrados, regras de validação quebradas, formatos condicionais quebrados e revelação opcional de planilhas ocultas
  • apply_workbook_changeset: pré-visualiza uma mutação de relatório multi-ferramenta limitada em um candidato isolado, avalia pós-condições explícitas e a confirma com proteção exata contra escrita obsoleta de arquivo, além de snapshot verificado opcional e rollback
  • diff_workbooks: compara dois arquivos de pasta de trabalho e relata mudanças estruturais além de diferenças amostradas de valores de células, útil para verificação antes/depois em fluxos de agente
  • create_workbook_snapshot: cria a linha de base verificada e sem sobrescrita que torna o diff_workbooks utilizável sem um script externo de cópia
  • analyze_range_impact: verificação prévia do raio de impacto de um intervalo de planilha, incluindo sobreposições com tabelas, pegadas de gráfico, células mescladas, intervalos nomeados, validações de dados, formatos condicionais, autofiltros, áreas de impressão, células de fórmula dentro do intervalo e fórmulas ou expressões de regra em outros lugares que dependem dele direta ou transitivamente, por meio de intervalos nomeados ou referências estruturadas de tabela como Table1[Sales]
  • explain_formula_cell: resolve as referências diretas de uma célula de fórmula, mostra células da cadeia de fórmula a montante, retorna um resumo compacto de formula_chain com camadas de profundidade e caminhos amostrados, e relata dependentes a jusante para que agentes possam depurar a lógica da pasta de trabalho sem rastreamento manual
  • detect_circular_dependencies: examina os grafos de fórmula da pasta de trabalho, incluindo arestas dirigidas por intervalos nomeados, e relata autorreferências além de grupos de dependência circular multicélula antes que eles surpreendam a automação a jusante
  • create_named_range: cria intervalos nomeados em nível de pasta de trabalho ou com escopo de planilha com suporte a dry_run e replace, para que agentes possam promover regiões importantes da pasta de trabalho a referências estáveis sem recorrer a Python ad hoc
  • inspect_formula: inspeciona uma string de fórmula sem contexto de pasta de trabalho, listando funções, tipos de token de referência, funções voláteis e funções arriscadas como INDIRECT
  • inspect_named_range: inspeciona um nome definido, incluindo seu escopo, destinos e se ele aponta para planilhas ausentes ou referências quebradas
  • quick_read: leitura compacta de tabela em uma única chamada que seleciona automaticamente a primeira planilha quando necessário, com limites protegidos de strict / default / extended, paginação start_row e janelamento de colunas start_col / end_col para planilhas grandes
  • read_excel_table: lê uma tabela nativa do Excel por table_name sem adivinhar limites de planilha, agora com paginação start_row e janelamento opcional de colunas de tabela start_col / end_col
  • list_all_sheets: inventário rápido de pasta de trabalho com tamanhos de planilha, sinalizadores de vazio e sheet_type para planilhas de trabalho versus planilhas de gráfico
  • read_excel_as_table: saída compacta de headers + rows para conjuntos de dados estruturados, com predefinições de limites protegidas, compact=True para o menor payload, start_row para leituras semelhantes a páginas e start_col / end_col para fatias de colunas mais estreitas
  • read_data_from_excel: leitor de intervalo ciente de endereço de célula que suporta janelamento max_rows e max_cols para intervalos grandes não tabulares, values_only=True para payloads 2D menores e continuações baseadas em cursor para travessia 2D em várias etapas
  • read_range_formatting: leitura compacta de formatação para um intervalo de planilha, agrupada por assinaturas de estilo distintas em vez de despejos ruidosos por célula, com resumos de sobreposição de intervalos mesclados e formatos condicionais
  • search_in_sheet: busca de valor exata ou parcial em células de planilha instanciadas, para que células distantes apenas com estilo não forcem uma varredura de todo o intervalo retangular usado

Ferramentas de inventário de pasta de trabalho como list_all_sheets, profile_workbook e list_charts exibem tanto planilhas de trabalho quanto planilhas de gráfico. Ferramentas orientadas a grade como quick_read, read_excel_table, create_table, formatação, fórmulas e validação exigem uma planilha de trabalho real e retornam um erro claro de planilha de gráfico se você mirar no tipo errado de planilha.

Os auxiliares de escrita mais amigáveis para agentes com dados estruturados são:

  • upsert_excel_table_rows: atualiza linhas correspondentes em uma tabela nativa do Excel e anexa chaves ausentes em uma única chamada Nota: tabelas com linha de totais são somente atualização por enquanto; tentativas de anexação são rejeitadas em vez de deslocar linhas não relacionadas.
  • append_excel_table_rows: anexa linhas a uma tabela nativa do Excel quando você quer que o ref da tabela cresça com os novos registros
  • append_table_rows: anexa linhas cientes de cabeçalho a dados em formato de planilha quando você não tem uma tabela nativa do Excel
  • update_rows_by_key: atualiza dados em formato de planilha por uma coluna de chave nomeada sem anexar chaves ausentes

Para os leitores compactos de tabela (quick_read, read_excel_as_table, read_excel_table):

  • row_mode="arrays" mantém a menor forma headers + rows
  • row_mode="objects" retorna records organizado por nomes de campos normalizados, como first_name
  • nomes de campos normalizados são transliterações seguras para ASCII, então cabeçalhos como Näyttökerrat tornam-se nayttokerrat
  • infer_schema=True adiciona dicas leves de schema inferidas das linhas retornadas
  • start_col / end_col permitem fatiar planilhas largas ou tabelas nativas do Excel para apenas as colunas necessárias antes da paginação ou inferência de esquema
  • páginas truncadas agora incluem next_start_row, que pode ser passado de volta à mesma ferramenta para a próxima página
  • leituras de intervalos não tabulares também podem retornar tokens de cursor continuations.down e continuations.right para que agentes continuem grandes janelas 2D sem recalcular coordenadas
  • suggest_read_strategy ajuda agentes a escolher entre leituras orientadas a tabela, planilha, intervalo e pasta de trabalho antes de gastar contexto no caminho errado
  • describe_dataset fornece um resumo de conjunto de dados mais leve que uma leitura completa, incluindo linhas de amostra, qualidade do cabeçalho, candidatos a chave e a próxima ferramenta recomendada
  • describe_dataset, quick_read, read_excel_as_table e read_excel_table agora também retornam structure_token, content_token e snapshot_metadata, para que agentes possam levar a identidade do momento da leitura para gravações mais seguras com concorrência otimista
  • leitores compactos com formato de planilha e auxiliares de mutação de linhas favorecem o primeiro bloco de dados contíguo após o cabeçalho, para que notas de rodapé esparsas ou linhas discrepantes distantes não estiquem silenciosamente total_rows, alvos de anexação ou varreduras de atualização baseadas em chave
  • leituras de planilha podem optar por read_boundary_mode="strict" (0 linhas em branco), "default" (5) ou "extended" (100); os predefinidos limitados evitam deliberadamente um parâmetro de lacuna bruta ilimitado
  • describe_dataset, quick_read e read_excel_as_table expõem um objeto read_boundary com a tolerância efetiva, fim dos dados, contagem de linhas ignoradas e locais compactos do bloco final
  • visualizações de limites não padrão são diagnósticos somente leitura e retornam write_precondition_compatible=false; releia com o modo padrão antes de levar um token de estrutura para uma gravação
  • query_table é a forma mais leve de extrair apenas as linhas e colunas correspondentes necessárias de um conjunto de dados de planilha ou tabela nativa do Excel
  • query_table e bulk_filter_workbooks aceitam ne como abreviação para neq, e filtros de associação podem usar values ou a forma de lista mais curta value
  • aggregate_table permite que agentes calculem resumos agrupados diretamente no SheetForge em vez de ler todo o conjunto de dados no contexto primeiro
  • bulk_aggregate_workbooks estende esse padrão a muitos arquivos de pasta de trabalho quando um fluxo de trabalho recorrente de relatórios exigiria Python ad hoc ou chamadas repetidas de ferramenta por arquivo
  • métricas agregadas aceitam tanto a forma canônica {"op": "sum", "field": "Sales", "as": "total_sales"} quanto a forma de alias mais adivinhável {"agg": "sum", "column": "Sales", "as": "total_sales"}
  • bulk_filter_workbooks faz o mesmo para inspeção em nível de linha, mantendo a proveniência da pasta de trabalho visível por padrão
  • union_tables é a forma mais rápida de normalizar muitos conjuntos de dados comparáveis de pastas de trabalho em um único payload tabular combinado antes de QA downstream, exportação ou agregação adicional
  • cross_workbook_lookup é a forma mais rápida de enriquecer uma pasta de trabalho a partir de outra sem escrever um script de mesclagem ad hoc, especialmente para consultas de dados mestre, enriquecimento de status e fluxos de trabalho de QA entre arquivos
  • append_excel_table_rows é o caminho de anexação correto para tabelas nativas do Excel quando você não precisa de comportamento de upsert baseado em chave
  • append_table_rows agora se recusa a escrever diretamente sob uma tabela nativa do Excel adjacente e aponta para append_excel_table_rows em vez de silenciosamente deixar o intervalo da tabela obsoleto
  • gravações estruturadas cientes de token podem passar expected_structure_token para abortar em desvio estrutural; gravações do tipo anexação também exigem allow_structure_change=True, e gravações bem-sucedidas relatam tokens de estrutura/conteúdo anteriores e novos
  • rename_worksheet agora atualiza células de fórmula, bem como referências de gráfico e intervalos nomeados, e também renomeia a planilha dinâmica irmã padrão (Data_pivot -> Revenue_pivot) quando esse movimento não gera conflitos
  • copy_worksheet preserva tabelas nativas com nomes copiados únicos na pasta de trabalho, validações de dados, formatação condicional, painéis congelados, autofiltros, configurações de impressão, proteção, gráficos com sua geometria de ancoragem exata e nomes com escopo de planilha; autoreferências copiadas e referências estruturadas de tabela são reescritas para a nova planilha
  • entradas de cor de formatação aceitam RRGGBB, #RRGGBB, AARRGGBB ou #AARRGGBB, para que prompts não precisem remover prefixos de estilo CSS # primeiro
  • audit_workbook é o preflight mais rápido em toda a pasta de trabalho quando você precisa saber se uma planilha é segura e previsível o suficiente para edição autônoma
  • audit_workbook agora trata planilhas dominantes com tabelas nativas de forma mais honesta quando artefatos de layout/dashboard próximos estendem o intervalo usado, para que áreas não relacionadas de mesclagem/gráfico não criem risco falso de cabeçalho em branco em uma tabela limpa
  • plan_workbook_repairs é a forma mais rápida de transformar essas descobertas de auditoria em uma fila de ações real, em vez de decidir manualmente a próxima chamada de ferramenta para cada problema
  • apply_workbook_repairs permite que agentes visualizem ou apliquem o subconjunto seguro desses reparos sem orquestrar manualmente cada artefato quebrado da pasta de trabalho
  • diff_workbooks é a passagem de QA antes/depois mais rápida quando um agente tocou na estrutura da pasta de trabalho e quer prova do que realmente mudou

Fluxos de Trabalho Recomendados para Agentes

  1. Pasta de trabalho desconhecida -> mutação verificada em várias etapas Comece com profile_workbook (ou list_all_sheets para o inventário mais leve), inspecione guias com muito layout usando describe_sheet_layout e execute analyze_range_impact. Coloque edições suportadas de construção de relatórios e pós-condições explícitas em apply_workbook_changeset(mode="preview"); se ready_to_commit=true, repita o mesmo plano com mode="commit", expected_workbook_sha256 e changeset_token da visualização.
  2. Loop de reparo de pasta de trabalho Use audit_workbook para encontrar problemas de alto sinal, plan_workbook_repairs para transformá-los em uma fila de ações, apply_workbook_repairs(..., dry_run=True) para visualizar o subconjunto seguro e depois execute novamente audit_workbook após aplicar os reparos para confirmar que a pasta de trabalho voltou a um estado de baixo risco.
  3. Relatórios com múltiplas pastas de trabalho Use bulk_aggregate_workbooks, bulk_filter_workbooks, union_tables ou cross_workbook_lookup para construir o conjunto de dados de relatório primeiro, depois escreva as linhas resumidas em uma nova guia da pasta de trabalho e finalize a camada de apresentação com format_ranges, find_free_canvas, create_chart e autofit_columns.

Consulte TOOLS.md para a referência completa. As notas de versão estão em CHANGELOG.md.

Formato de Resposta

Toda ferramenta agora retorna um envelope JSON com uma estrutura de nível superior consistente:

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

Respostas de erro seguem o mesmo contrato:

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

Para ferramentas destrutivas que suportam modo de visualização, o envelope também pode incluir dry_run e changes. Operações de gravação confirmadas agora usam resumos compactos por padrão; passe include_changes=True quando quiser detalhes por célula, por intervalo ou por operação.

Desenvolvimento

Instale as dependências:

uv sync --extra dev

Execute os testes:

uv run --extra dev pytest -q

Execute verificações de lint:

uv run --extra dev ruff check src tests

Execute o pacote localmente:

uv run sheetforge-mcp stdio

Construa distribuições localmente:

uv build

Fluxo de Lançamento

  • Atualize pyproject.toml, manifest.json e o pacote rastreado .mcpb juntos para cada lançamento.
  • Mantenha o nome do arquivo do pacote rastreado em sincronia com a versão do pacote, por exemplo sheetforge-mcp-<version>.mcpb.
  • Todo fluxo de trabalho de construção de distribuição verifica a wheel, a distribuição de origem e o pacote MCPB rastreado contra listas de permissão de artefatos públicos compartilhadas antes do lançamento ou publicação.
  • Lançamentos do GitHub executam apenas um fluxo de trabalho de verificação de construção.
  • A publicação no PyPI é um fluxo de trabalho manual separado, para que lançamentos não criem uma implantação com falha antes que o Trusted Publisher seja configurado para o pacote.

Estrutura do Repositório

  • src/excel_mcp/server.py: servidor MCP, configuração de transporte e registro de ferramentas
  • src/excel_mcp/workbook.py: auxiliares de ciclo de vida da pasta de trabalho e metadados da pasta de trabalho
  • src/excel_mcp/changeset.py: transações verificadas de múltiplas operações com visualização/confirmação e asserções
  • src/excel_mcp/data.py: auxiliares de leitura, gravação, tabela e pesquisa
  • src/excel_mcp/sheet.py: mutações de planilha e intervalo
  • tests/: testes de regressão cobrindo dados, layout, gráficos, tabelas dinâmicas, formatação, tabelas e segurança de recursos
  • scripts/verify_release_artifacts.py: verificador compartilhado de conteúdo wheel/sdist/MCPB usado por CI e fluxos de trabalho de lançamento
  • manifest.json: metadados do pacote MCP empacotado
  • docs/index.html: página estática de destino do projeto

Por que SheetForge MCP

  • Superfície MCP focada em Excel: o conjunto de ferramentas é focado em operações reais de pasta de trabalho .xlsx, não em E/S genérica de arquivos
  • respostas amigáveis para agentes: envelopes JSON consistentes, gravações compactas e visualizações dry_run reduzem desperdício de contexto
  • introspecção de pasta de trabalho: profile_workbook, list_all_sheets, list_tables e list_charts tornam planilhas desconhecidas mais fáceis de navegar
  • edições mais seguras: analyze_range_impact dá aos agentes um preflight somente leitura antes de sobrescrever, excluir ou reestruturar um intervalo importante, incluindo cadeias de fórmulas downstream, além de referências de regras de validação e formatação condicional em outras partes da pasta de trabalho, mesmo quando fórmulas apontam para o intervalo por meio de intervalos nomeados ou referências estruturadas de tabela
  • transações verificadas: apply_workbook_changeset vincula um plano limitado de operação/asserção ao caminho canônico de destino e ao SHA-256 exato da origem, testa-o em um candidato isolado, verifica células, tabelas, painéis congelados, autofiltros e posicionamento de gráficos, e substitui a origem apenas uma vez após todas as verificações passarem
  • planejamento de layout: find_free_canvas sugere espaços vazios seguros para gráficos ou blocos de dashboard antes de você posicioná-los, usando por padrão o espaço padrão de gráfico quando você omite dimensionamento explícito
  • saída prática de Excel: formatação, configuração de impressão, proteção de planilha, upserts de tabela, criação de gráficos e auxiliares de ajuste automático cobrem fluxos de trabalho reais de relatórios
  • adequação ao ecossistema Python: construído sobre openpyxl, empacotado para uvx e fácil de executar localmente via stdio ou por meio de uma implantação HTTP deliberadamente controlada

Notas para Integradores

  • O modo stdio toma cuidado para não escrever texto não relacionado ao protocolo em stdout.
  • Todas as ferramentas retornam envelopes JSON estruturados, o que torna a análise no lado do cliente previsível.
  • As respostas das ferramentas agora usam serialização JSON compacta para reduzir o tamanho do payload do MCP, mantendo o mesmo formato de envelope.
  • read_data_from_excel(..., preview_only=True) limita a resposta às primeiras 10 linhas do intervalo selecionado e marca o payload como truncado quando aplicável.
  • read_data_from_excel(..., compact=True) omite stubs de validação padrão para células que não possuem regras de validação.
  • read_data_from_excel(..., values_only=True) retorna um array 2D simples de values para leituras de intervalo que não precisam de endereços por célula ou metadados de validação.
  • read_data_from_excel(..., max_rows=...) pagina intervalos retangulares altos e retorna next_start_row mais next_start_cell quando ainda há mais linhas.
  • read_data_from_excel(..., max_cols=...) pagina intervalos retangulares largos e retorna next_start_col mais next_column_start_cell quando ainda há mais colunas.
  • read_data_from_excel(..., cursor=...) retoma a partir de um token de continuação para que agentes possam continuar paginando sem recalcular a próxima janela manualmente; janelas 2D expõem continuações direcionais sob continuations.down e continuations.right.
  • read_excel_as_table(..., compact=True) minimiza o payload tabular para headers e rows a menos que metadados de truncamento sejam necessários, ainda retornando metadados de identidade do conjunto de dados.
  • Leitores tabulares compactos ainda incluem structure_token, content_token e snapshot_metadata, mesmo quando o payload tabular em si é minimizado.
  • quick_read(..., start_row=...) e read_excel_as_table(..., start_row=...) permitem que agentes paginem planilhas profundas sem primeiro ler a partir do topo.
  • quick_read(..., start_col=..., end_col=...) e read_excel_as_table(..., start_col=..., end_col=...) permitem que agentes solicitem apenas as colunas relevantes de planilhas largas, em vez de puxar todas as colunas para o contexto.
  • read_excel_table(..., start_col=..., end_col=...) agora suporta as mesmas fatias de colunas mais estreitas para tabelas nativas do Excel, desde que as colunas solicitadas estejam dentro do intervalo da tabela.
  • quick_read(..., include_headers=False), read_excel_as_table(..., include_headers=False) e read_excel_table(..., include_headers=False) permitem que páginas de acompanhamento omitam o payload repetido de cabeçalho quando a primeira página já estabeleceu o esquema.
  • read_excel_table(..., start_row=...) agora suporta paginação mais profunda em tabelas nativas do Excel, em vez de sempre ler a partir do topo.
  • Leituras tabulares truncadas agora retornam next_start_row para que agentes possam continuar paginando sem recalcular deslocamentos.
  • Respostas de leitura excessivamente grandes agora falham cedo com ResponseTooLargeError mais hints estruturado, para que agentes possam tentar novamente com intervalos menores ou paginação antes que o cliente trunque o payload.
  • quick_read, read_excel_as_table e read_excel_table agora podem retornar records mais dicas de schema inferidas quando você opta por row_mode="objects" e infer_schema=True.
  • Ferramentas de leitura não recalculam fórmulas do Excel; células com fórmulas aparecem como texto de fórmula, como =B2*C2, e o esquema inferido rotula colunas baseadas em fórmulas como formula para que agentes não as confundam com valores numéricos novos.
  • profile_workbook fornece um inventário da pasta de trabalho em uma única chamada, com metadados de tabela, gráfico, proteção, impressão e filtro em nível de planilha para orientação mais rápida do agente, e agora inclui occupied_range de gráficos junto com âncoras e dimensões para gráficos de planilha ancorados em grade.
  • Ferramentas de mutação principais agora usam respostas compactas por padrão em gravações confirmadas, incluindo gravações de dados, formatação, auxiliares de layout de planilha e auxiliares de mesclar/desmesclar. Use include_changes=True para diffs detalhados.
  • Gravações estruturadas com reconhecimento de token agora retornam previous_structure_token, new_structure_token, previous_content_token, new_content_token e snapshot_metadata, o que torna fluxos multiagente ou de leitura-e-gravação mais seguros sem adicionar metadados ocultos da pasta de trabalho.
  • Versões dry_run dessas gravações estruturadas agora rotulam metadados de snapshot como token_basis="dry_run_preview" e mantêm os fatos do arquivo em disco sob source_file_*, para que tokens de pré-visualização não sejam mais misturados com metadados de arquivo ao vivo.
  • Salvamentos de pasta de trabalho que passam por safe_workbook(..., save=True) usam um bloqueio de pasta de trabalho no mesmo host com reconhecimento de tempo limite, além de salvamento em arquivo temporário, fsync, substituição atômica, reversão em caso de falha de verificação e verificação de reabertura. Caminhos de symlink atualizam seu destino real sem substituir o próprio symlink. Se a reversão automática falhar, o backup de recuperação é mantido e identificado no erro. Isso protege processos cooperativos do SheetForge em uma máquina; não é um bloqueio distribuído para provedores de sincronização em nuvem.
  • format_ranges agrupa múltiplas operações de formatação em uma única passada pela pasta de trabalho e relata errors por intervalo sem descartar intervalos bem-sucedidos. Um intervalo com falha é revertido para seus estilos, valores, comentários, hiperlinks, estado de mesclagem e regras de formatação condicional pré-operação antes que o lote continue.
  • validate_formula_syntax realiza validação estrutural de tokens, verifica limites de coordenadas do Excel e rejeita funções arriscadas como INDIRECT, HYPERLINK, WEBSERVICE, DGET e RTD de forma insensível a maiúsculas/minúsculas. Ele não calcula fórmulas nem substitui o motor de cálculo do próprio Excel.
  • write_data_to_excel permanece um primitivo bruto de gravação de célula e pode armazenar strings de fórmula diretamente; use-o apenas com dados confiáveis, ou use apply_formula quando quiser as verificações de segurança de fórmula do SheetForge.
  • Os logs do servidor giram em 5 MiB com dois backups, em vez de crescer sem limite.
  • autofit_columns estima larguras práticas de colunas a partir do conteúdo atual das células, com filtros de coluna opcionais e limites mínimo/máximo.
  • list_charts agora relata width e height de gráficos em centímetros, além de âncora, tipo e metadados de série.
  • get_worksheet_protection e set_worksheet_protection adicionam um wrapper seguro em nível de planilha em torno dos sinalizadores de proteção do Excel.
  • set_print_area e set_print_titles tornam a configuração de relatórios/exportação programável sem recorrer a internals brutos do openpyxl da pasta de trabalho.
  • list_tables agora retorna metadados de esquema leves, como cabeçalhos, contagens de linhas e configurações de listras, além de nomes e intervalos de tabelas.
  • upsert_excel_table_rows expande automaticamente intervalos de tabelas nativas do Excel quando anexa chaves ausentes, recusa crescer uma tabela em células já ocupadas e rejeita tentativas de anexação quando a tabela alvo tem uma linha de totais habilitada.
  • Ferramentas de mutação principais suportam dry_run=True para que clientes possam pré-visualizar alterações antes de salvar uma pasta de trabalho.

Licença

MIT. Veja LICENSE.