Sheet-Cello

Servidor MCP do Google Sheets 🚀

Um servidor poderoso e abrangente do Model Context Protocol (MCP) que permite que agentes de IA interajam diretamente com o Google Sheets. Execute desde atualizações simples de células até análises de dados complexas e visualizações usando linguagem natural.

---

📂 Estrutura do Projeto

O projeto está organizado em camadas de serviço modulares para facilitar a manutenção e a extensibilidade:

• constants/: Configuração centralizada e descrições de ferramentas otimizadas para LLM.
  • constants.py: Definições para nomes de ferramentas, descrições e chaves do GSheet.
• services/: Lógica central para interagir com APIs e serviços externos.
• tools/: Implementação de vários recursos de planilhas:
  • data_analysis/: Classificação, filtragem, tabelas dinâmicas e extração de valores únicos.
    • data_operations/: Leitura de intervalos, atualizações em lote e entrada de dados em linhas/colunas.
    • formattings/: Estilo de texto, cores, alinhamento, bordas e formatos de número.
    • formulas/: Inserção e avaliação de fórmulas.
    • rows_and_coloumns_operations/: Alterações estruturais (inserir/excluir/ocultar/mostrar).
    • sheet_operations/: Gerenciamento de planilhas (criar, excluir, renomear, listar).
    • visualizations/: Criação e atualização dinâmica de gráficos.
• utils/: Utilitários auxiliares para normalização de cores e recuperação de planilhas.
• main.py e server.py: Pontos de entrada e inicialização do servidor MCP.

---

⚙️ Primeiros Passos

1. Pré-requisitos

• Projeto do Google Cloud com as APIs do Google Sheets e Drive ativadas.
• Arquivo JSON de credenciais da conta de serviço colocado em assets/.
• Python 3.10+ instalado.

Etapa 2: Criar Projeto no Google Cloud

• Acesse o Console do Google Cloud
• Crie um novo projeto

Etapa 3: Ativar APIs

Ative:

• API do Google Sheets
• API do Google Drive

Etapa 4: Criar Conta de Serviço

• Acesse APIs e Serviços → Credenciais
• Crie uma Conta de Serviço

Etapa 5: Criar Chave da Conta de Serviço

• Abra a Conta de Serviço
• Crie uma chave JSON
• Baixe o arquivo (ex.: credentials.json)
• Abra o Google Sheet
• Compartilhe com o e-mail da conta de serviço
• Dê acesso de Editor

Etapa 7: Autorizar em Python

mount your credential to assets/ if you running through docker
set SERVICE_FILE_PATH=path to your credential if running locally

2. Verificar Conexão

1. Verifique se o Servidor está em Execução:

   python main.py
   

2. Configuração do Cursor:
   • Abra Configurações do Cursor → Desenvolvedor → Editar Configuração.
     • Certifique-se de que o servidor esteja listado (nome padrão: sheets-cello).
3. Credenciais:
   • Certifique-se de que o SERVICE_FILE_PATH em constants/constants.py ou como variável de ambiente aponte para o seu JSON da conta de serviço.

---

🛠️ Referência Exaustiva de Ferramentas

O agente fornece 46 ferramentas especializadas organizadas nas seguintes categorias. Cada ferramenta é otimizada para uso com LLM, com descrições detalhadas e exemplos de uso.

🔌 Conexão e Escopo (1 ferramenta)

• select_sheet: Seleciona ou ativa uma pasta de trabalho diferente do Google Sheets pelo nome.

📊 Operações de Dados (8 ferramentas)

• read_range: Recupera valores de um intervalo retangular específico (ex.: A1:C10).
• read_batch_ranges: Recupera valores de vários intervalos não contíguos em uma única chamada.
• read_sheet: Busca todas as linhas e colunas preenchidas da planilha.
• get_cell_value: Recupera o valor de uma única célula específica.
• set_cell_value: Atualiza o valor de uma única célula específica.
• update_row_by_index: Atualiza uma linha inteira com novos dados com base no número da linha.
• update_or_insert_column: Atualiza ou insere valores em uma coluna específica.
• append_data_batch_in_rows: Acrescenta várias linhas de dados, encontrando automaticamente o final, se necessário.
• clear_range: Exclui todo o conteúdo dentro de um intervalo especificado de células.

📑 Gerenciamento de Planilhas (4 ferramentas)

• list_sheets: Recupera uma lista de todos os títulos de planilhas na pasta de trabalho atual.
• create_sheet: Cria uma nova planilha com tamanho opcional de linhas/colunas.
• delete_sheet: Exclui uma planilha existente pelo nome.
• rename_sheet: Atualiza o título de uma planilha existente.

🎨 Formatação e Estilo (12 ferramentas)

• set_text_style: Define negrito, itálico e tamanho da fonte para um intervalo.
• set_text_color: Define a cor do primeiro plano das células usando valores RGB.
• set_background_color: Define a cor de fundo (preenchimento) das células usando valores RGB.
• set_alignment: Define o alinhamento horizontal e/ou vertical do texto.
• set_wrap: Controla como o texto é quebrado (WRAP, CLIP, OVERFLOW).
• set_borders: Aplica bordas (superior, inferior, esquerda, direita) ao redor de um intervalo.
• set_rotation: Rotaciona o texto dentro das células por um determinado ângulo.
• set_number_format: Define padrões de formato de número, data, moeda ou porcentagem.
• merge_cells: Mescla todas as células em um intervalo em uma única célula.
• set_column_width: Define a largura de uma coluna específica em pixels.
• set_row_height: Define a altura de uma linha específica em pixels.
• auto_fit_columns: Ajusta automaticamente as larguras das colunas com base no conteúdo.

📐 Operações de Linhas e Colunas (8 ferramentas)

• insert_rows: Insere novas linhas vazias em um índice específico.
• delete_rows: Exclui um número especificado de linhas a partir de um índice.
• insert_columns: Insere novas colunas vazias em um índice específico.
• delete_columns: Exclui um número especificado de colunas a partir de um índice.
• hide_rows: Oculta linhas específicas da visualização.
• show_rows: Mostra linhas anteriormente ocultas.
• hide_columns: Oculta colunas específicas da visualização.
• show_columns: Mostra colunas anteriormente ocultas.

🔢 Fórmulas (3 ferramentas)

• set_formula_in_cell: Insere uma fórmula do Google Sheets (ex.: =SUM(A1:A10)).
• get_formula_from_cell: Recupera a string de fórmula bruta de uma célula.
• evaluate_formula: Retorna o resultado numérico ou de texto calculado de uma fórmula.

📈 Análise de Dados (6 ferramentas)

• sort_range: Classifica um intervalo por uma coluna em ordem crescente ou decrescente.
• filter_data: Aplica critérios de filtragem complexos a um intervalo.
• remove_duplicates: Remove linhas duplicadas com base em colunas específicas.
• find_value: Pesquisa um valor específico em um intervalo ou em toda a planilha.
• get_unique_values: Retorna todos os valores únicos de uma coluna específica.
• create_gsheet_pivot: Cria um resumo de tabela dinâmica em uma planilha de destino.

📊 Visualizações (3 ferramentas)

• create_chart: Cria gráficos de linha, barra, pizza ou coluna.
• update_chart: Atualiza o título, tipo ou posição de um gráfico existente.
• delete_chart: Remove um gráfico da planilha pelo título.

---

🔧 Solução de Problemas

• Ferramentas MCP Não Aparecem?
  1. Certifique-se de que o python main.py está em execução. 2. Reinicie o Cursor completamente para atualizar a descoberta de ferramentas.
• Permissão Negada?
  • Certifique-se de ter compartilhado seu Google Sheet com o E-mail da Conta de Serviço encontrado no seu arquivo JSON de credenciais.

---

#VARIÁVEIS DE AMBIENTE

SERVICE_FILE_PATH= path to your credentials.json
transport= (sse,stdio,http)
mcp_host= ip to host mcp
mcp_port= port to run mcp server