Smartsheet

Integre com o Smartsheet para gerenciamento de projetos e análise de dados, exigindo um token de acesso à API.

Documentação

Servidor MCP Smartsheet

Um servidor Model Context Protocol (MCP) que fornece integração perfeita com o Smartsheet, permitindo operações automatizadas em documentos do Smartsheet por meio de uma interface padronizada. Este servidor preenche a lacuna entre ferramentas de automação com inteligência artificial e a poderosa plataforma de colaboração do Smartsheet.

Visão Geral

O Servidor MCP Smartsheet foi projetado para facilitar interações inteligentes com o Smartsheet, fornecendo um conjunto robusto de ferramentas para gerenciamento de documentos, operações de dados e personalização de colunas. Ele serve como um componente crítico em fluxos de trabalho automatizados, permitindo que sistemas de IA interajam programaticamente com os dados do Smartsheet, mantendo a integridade dos dados e aplicando regras de negócio.

Principais Benefícios

Integração Inteligente: Conecta perfeitamente sistemas de IA à plataforma de colaboração do Smartsheet
Integridade de Dados: Aplica regras de validação e mantém a integridade referencial nas operações
Gerenciamento de Fórmulas: Preserva e atualiza referências de fórmulas automaticamente
Configuração Flexível: Suporta vários tipos de colunas e estruturas de dados complexas
Resiliência a Erros: Implementa tratamento abrangente de erros e validação em múltiplas camadas
Análise de Saúde: Capacidades especializadas de análise para dados clínicos e de pesquisa
Processamento em Lote: Tratamento eficiente de grandes conjuntos de dados de saúde
Pontuação Personalizada: Sistemas flexíveis de pontuação para iniciativas de saúde e pesquisa

Casos de Uso

Análise de Pesquisa Clínica
- Pontuação de conformidade com protocolos
- Análise de dados de pacientes
- Avaliação de impacto de pesquisa
- Processamento de dados de ensaios clínicos
- Resumo automatizado de notas de pesquisa
Operações Hospitalares
- Análise de utilização de recursos
- Pontuação de satisfação de pacientes
- Métricas de eficiência departamental
- Análise de desempenho da equipe
- Rastreamento de métricas de qualidade
Inovação em Saúde
- Pontuação de alinhamento pediátrico
- Avaliação de impacto de inovação
- Priorização de pesquisa
- Análise de viabilidade de implementação
- Avaliação de valor clínico
Gerenciamento Automatizado de Documentos
- Modificações programáticas na estrutura de planilhas
- Criação e gerenciamento dinâmico de colunas
- Validação e formatação automatizada de dados
Operações de Dados
- Atualizações em massa com verificações de integridade
- Detecção inteligente de duplicatas
- Modificações cientes de fórmulas
Integração de Sistemas
- Personalização de planilhas orientada por IA
- Fluxos de trabalho automatizados de relatórios
- Sincronização de dados entre sistemas

Pontos de Integração

O servidor integra-se com:

API do Smartsheet para operações de dados
Protocolo MCP para comunicação padronizada
Ferramentas de desenvolvimento local via interface stdio
Sistemas de monitoramento por meio de registro estruturado

Recursos

Ferramentas (34 Disponíveis)

get_column_map (Leitura)
- Recupera o mapeamento de colunas e dados de amostra de um Smartsheet
- Fornece metadados detalhados de colunas, incluindo:
  - Tipos de colunas (colunas de sistema, fórmulas, listas de seleção)
  - Regras de validação
  - Especificações de formato
  - Configurações de numeração automática
- Retorna dados de amostra para contexto
- Inclui exemplos de uso para escrever dados
get_sheet_info (Leitura - Alias)
- Alias para get_column_map fornecendo funcionalidade idêntica
- Mantém compatibilidade retroativa com integrações existentes
smartsheet_write (Criação)
- Escreve novas linhas no Smartsheet com tratamento inteligente de:
  - Colunas gerenciadas pelo sistema
  - Valores de listas de seleção múltipla
  - Colunas baseadas em fórmulas
- Implementa detecção automática de duplicatas
- Adiciona novas linhas na parte inferior da planilha (após as entradas existentes)
- Retorna resultados detalhados da operação, incluindo IDs de linhas
smartsheet_update (Atualização)
- Atualiza linhas existentes em um Smartsheet
- Suporta atualizações parciais (modificar campos específicos)
- Mantém a integridade dos dados com validação
- Trata campos de seleção múltipla de forma consistente
- Retorna detalhes de sucesso/falha por linha
smartsheet_delete (Exclusão)
- Exclui linhas de um Smartsheet
- Suporta exclusão em lote de múltiplas linhas
- Valida a existência de linhas e permissões
- Retorna resultados detalhados da operação
smartsheet_search (Pesquisa)
- Realiza pesquisa avançada em planilhas
- Suporta múltiplos modos de pesquisa:
  - Pesquisa de texto com suporte a regex
  - Correspondência exata de valores para colunas PICKLIST
  - Opções de diferenciação de maiúsculas/minúsculas e palavra inteira
- Capacidades de pesquisa específicas por coluna
- Retorna:
  - IDs de linhas correspondentes (resultado principal)
  - Informações detalhadas de correspondência
  - Metadados e estatísticas de pesquisa
smartsheet_add_column (Gerenciamento de Colunas)
- Adiciona novas colunas a um Smartsheet
- Suporta todos os tipos de colunas:
  - TEXT_NUMBER
  - DATE
  - CHECKBOX
  - PICKLIST
  - CONTACT_LIST
- Opções configuráveis:
  - Índice de posição
  - Regras de validação
  - Definições de fórmulas
  - Opções de lista de seleção
- Aplica o limite de colunas (400) com validação
- Retorna informações detalhadas da coluna
smartsheet_delete_column (Gerenciamento de Colunas)
- Exclui colunas com segurança, verificando dependências
- Valida referências de fórmulas antes da exclusão
- Impede a exclusão de colunas usadas em fórmulas
- Retorna informações detalhadas de dependências
- Suporta opção de exclusão forçada
smartsheet_rename_column (Gerenciamento de Colunas)
- Renomeia colunas preservando relacionamentos
- Atualiza referências de fórmulas automaticamente
- Mantém a integridade dos dados
- Valida a exclusividade do nome
- Retorna informações detalhadas da atualização
smartsheet_bulk_update (Atualizações Condicionais)
- Realiza atualizações condicionais em massa com base em regras
- Suporta avaliação de condições complexas:
  - Múltiplos operadores (igual, contém, maior que, etc.)
  - Comparações específicas por tipo (texto, datas, números)
  - Verificações de vazio/não vazio
- Processamento em lote com tamanho configurável
- Tratamento abrangente de erros e reversão
- Rastreamento detalhado de resultados da operação
get_all_row_ids (Utilitário)
- Recupera todos os IDs de linhas de um Smartsheet
- Útil para operações em lote e análise de dados
- Retorna lista completa de identificadores de linhas
- Suporta planilhas grandes com eficiência
start_batch_analysis (Análise de Saúde)
- Processa planilhas inteiras ou linhas selecionadas com análise de IA
- Suporta múltiplos tipos de análise:
  - Resumo de notas clínicas
  - Análise de sentimento de feedback de pacientes
  - Pontuação personalizada para iniciativas de saúde
  - Avaliação de impacto de pesquisa
- Recursos:
  - Processamento automático em lote (3 linhas por lote para desempenho ideal)
  - Rastreamento de progresso e monitoramento de status
  - Tratamento de erros com relatórios detalhados
  - Metas de análise personalizáveis via Azure OpenAI
  - Suporte a múltiplas colunas de origem
  - Divisão de conteúdo ciente de tokens para textos longos
get_job_status (Monitoramento de Análise)
- Rastreia o progresso da análise em lote
- Fornece estatísticas detalhadas do trabalho:
  - Total de linhas a processar
  - Contagem de linhas processadas
  - Contagem de linhas com falha
  - Carimbos de data/hora do processamento
- Atualizações de status em tempo real
- Relatórios abrangentes de erros
cancel_batch_analysis (Controle de Trabalho)
- Cancela trabalhos de análise em lote em execução
- Encerramento gracioso do processo
- Mantém a consistência dos dados
- Retorna o status final do trabalho
list_workspaces (Gerenciamento de Workspace)
- Lista todos os workspaces acessíveis
- Retorna IDs, nomes e permalinks dos workspaces
- Inclui informações de nível de acesso
- Suporta descoberta de workspaces em toda a organização
get_workspace (Gerenciamento de Workspace)
- Recupera informações detalhadas do workspace
- Retorna planilhas, pastas, relatórios e painéis contidos
- Fornece detalhes de nível de acesso e permissões
- Suporta exploração de conteúdo do workspace
create_workspace (Gerenciamento de Workspace)
- Cria um novo workspace com nome especificado
- Retorna o ID do novo workspace e confirmação
- Permite organização programática de workspaces
- Suporta migração de endpoints de pastas obsoletos
create_sheet_in_workspace (Gerenciamento de Workspace)
- Cria uma nova planilha diretamente em um workspace
- Suporta todos os tipos e configurações de colunas
- Retorna o ID da nova planilha e detalhes
- Permite criação e organização programática de planilhas
list_workspace_sheets (Gerenciamento de Workspace)
- Lista todas as planilhas em um workspace específico
- Retorna IDs, nomes e permalinks das planilhas
- Inclui carimbos de data/hora de criação e modificação
- Suporta descoberta de conteúdo do workspace
smartsheet_upload_attachment (Gerenciamento de Anexos)
- Envia arquivos para planilhas, linhas ou comentários
- Suporta múltiplos tipos de anexos e validação de tamanho de arquivo
- Retorna metadados do anexo e status do envio
smartsheet_get_attachments (Gerenciamento de Anexos)
- Lista todos os anexos de planilha ou linha
- Retorna metadados abrangentes de anexos
- Inclui URLs de arquivos, tamanhos e informações do criador
smartsheet_download_attachment (Gerenciamento de Anexos)
- Baixa anexos específicos para o sistema de arquivos local
- Cria diretórios conforme necessário e verifica downloads
- Retorna status do download e informações do arquivo
smartsheet_delete_attachment (Gerenciamento de Anexos)
- Remove anexos de planilhas
- Valida permissões e retorna status da exclusão
smartsheet_create_discussion (Gerenciamento de Discussões)
- Cria novos tópicos de discussão em planilhas ou linhas
- Suporta comentários iniciais e títulos opcionais
- Retorna metadados da discussão e status da criação
smartsheet_add_comment (Gerenciamento de Discussões)
- Adiciona comentários a discussões existentes
- Mantém a estrutura de conversa em tópicos
- Retorna detalhes do comentário e carimbos de data/hora
smartsheet_get_discussions (Gerenciamento de Discussões)
- Lista todas as discussões de planilhas ou linhas
- Inclusão opcional de todos os comentários na resposta
- Retorna metadados da discussão e informações dos participantes
smartsheet_get_comments (Gerenciamento de Discussões)
- Obtém todos os comentários em um tópico de discussão específico
- Inclui informações de anexos, se presentes
- Retorna histórico cronológico de comentários
smartsheet_delete_comment (Gerenciamento de Discussões)
- Exclui comentários específicos de discussões
- Valida permissões antes da exclusão
- Retorna confirmação da exclusão
smartsheet_get_cell_history (Histórico de Células e Auditoria)
- Obtém histórico de modificações para células individuais
- Inclui atribuição de usuário e carimbos de data/hora
- Rastreia alterações de valores, fórmulas e formatação
smartsheet_get_row_history (Histórico de Células e Auditoria)
- Obtém histórico de alterações para linhas inteiras
- Fornece linha do tempo cronológica de todas as alterações de células
- Suporta filtragem por coluna específica e trilhas de auditoria completas
smartsheet_get_sheet_cross_references (Referências Entre Planilhas)
- Analisa todas as referências entre planilhas dentro de uma planilha
- Identifica fórmulas que referenciam outras planilhas
- Análise detalhada de padrões de fórmulas e dependências
smartsheet_find_sheet_references (Referências Entre Planilhas)
- Encontra todas as planilhas que referenciam uma planilha de destino específica
- Pesquisa em todo o workspace ou em todas as planilhas acessíveis
- Mapeamento abrangente de referências e análise de impacto
smartsheet_validate_cross_references (Referências Entre Planilhas)
- Valida todas as referências entre planilhas para links quebrados
- Identifica planilhas referenciadas inacessíveis ou excluídas
- Sugere planilhas alternativas para referências quebradas
smartsheet_create_cross_reference (Referências Entre Planilhas)
- Cria fórmulas INDEX_MATCH, VLOOKUP, SUMIF, COUNTIF
- Constrói fórmulas de referência entre planilhas programaticamente
- Suporte para modelos de fórmulas personalizados e múltiplos tipos de fórmulas

Recursos (4 Estáticos + 5 Modelos Dinâmicos)

O servidor fornece tanto recursos estáticos quanto modelos de recursos dinâmicos para acesso aprimorado a dados e informações contextuais.

Recursos Estáticos

smartsheet://templates/project-plan - Modelo de Plano de Projeto
- Modelo de plano de projeto pré-construído com melhores práticas
- Inclui estrutura de colunas ideal para gerenciamento de tarefas
- Fornece orientação sobre dependências e alocação de recursos
smartsheet://templates/task-tracker - Modelo de Rastreador de Tarefas
- Modelo simples de rastreamento de tarefas para colaboração em equipe
- Focado no monitoramento de progresso sem dependências complexas
- Ideal para equipes ágeis e fluxos de trabalho simples
smartsheet://schemas/column-types - Referência de Tipos de Coluna
- Referência completa de todos os tipos de coluna suportados pelo Smartsheet
- Inclui nível de suporte da API para cada tipo (completo, limitado, somente leitura)
- Essencial para entender as capacidades e limitações das colunas
smartsheet://best-practices/formulas - Melhores Práticas de Fórmulas
- Padrões comuns de fórmulas e exemplos de cálculo
- Melhores práticas para desempenho e manutenibilidade
- Orientação para referências entre planilhas

Modelos de Recursos Dinâmicos

smartsheet://{sheet_id}/summary - Resumo da Planilha
- Resumo gerado automaticamente com métricas-chave e status de saúde
- Indicadores de progresso e estatísticas de conclusão
- Análise em tempo real dos dados da planilha
smartsheet://{sheet_id}/gantt-data - Dados do Gráfico de Gantt
- Formato padronizado de dados do gráfico de Gantt para visualização
- Dados de cronograma otimizados para ferramentas de gerenciamento de projetos
- Relações de dependência e informações do caminho crítico
smartsheet://{workspace_id}/overview - Visão Geral do Workspace
- Visão geral abrangente do conteúdo do workspace
- Todas as planilhas, relatórios e painéis em formato estruturado
- Níveis de acesso e hierarquia organizacional
smartsheet://{sheet_id}/dependencies - Mapa de Dependências
- Mapeamento visual de dependências para planilhas de projeto
- Relações de tarefas e análise do caminho crítico
- Identificação de gargalos e sugestões de otimização
smartsheet://{sheet_id}/health-report - Relatório de Saúde da Planilha
- Análise de saúde que identifica problemas de qualidade de dados
- Detecção de dados ausentes e identificação de fórmulas quebradas
- Oportunidades de otimização e recomendações

Prompts (6 Disponíveis)

Modelos de prompt inteligentes que fornecem assistência guiada para operações e análises comuns do Smartsheet.

create_project_plan - Guia de Criação de Plano de Projeto
- Criação guiada de plano de projeto com melhores práticas
- Sugestões de modelos com base no tipo e duração do projeto
- Recomendações de estrutura de detalhamento do trabalho
analyze_project_status - Análise de Saúde do Projeto
- Análise abrangente da saúde do projeto com recomendações
- Insights sobre aderência ao cronograma e utilização de recursos
- Identificação de riscos e estratégias de mitigação
optimize_workflow - Otimização de Fluxo de Trabalho
- Sugestões para melhorar a estrutura da planilha e os fluxos de trabalho
- Oportunidades de automação e melhorias de eficiência
- Recomendações para aprimorar a experiência do usuário
generate_insights - Extração de Insights de Dados
- Extraia insights e padrões-chave dos dados da planilha
- Análise de tendências e detecção de anomalias
- Inteligência acionável e suporte à decisão
create_dashboard_summary - Criação de Painel Executivo
- Gere resumos executivos a partir de múltiplas planilhas
- Acompanhamento de KPIs de alto nível e insights estratégicos
- Relatórios e recomendações focados na liderança
setup_conditional_formatting - Guia de Formatação Condicional
- Configuração passo a passo de formatação condicional
- Melhores práticas para representação visual de dados
- Configuração de indicadores de status e acompanhamento de progresso

Principais Recursos

Gerenciamento de Tipos de Coluna
- Lida com tipos de coluna do sistema (AUTO_NUMBER, CREATED_DATE, etc.)
- Suporta análise de fórmulas e rastreamento de dependências
- Gerencia opções de lista de seleção e valores de múltipla seleção
- Operações abrangentes de coluna (adicionar, excluir, renomear)
- Preservação e atualização de referências de fórmulas
Validação de Dados
- Detecção automática de duplicatas
- Validação de tipos de coluna
- Verificação de formato de dados
- Análise de dependências de coluna
- Validação de exclusividade de nomes
Funcionalidade de Pesquisa
- Recursos avançados de pesquisa
- Pesquisa ciente do tipo:
  - Correspondência exata para valores PICKLIST
  - Correspondência de padrões para campos de texto
  - Comparações numéricas
- Opções de pesquisa configuráveis:
  - Sensibilidade a maiúsculas/minúsculas
  - Correspondência de palavra inteira
  - Filtragem por coluna
- Resultados abrangentes:
  - IDs de linhas para linhas correspondentes
  - Contexto detalhado da correspondência
  - Estatísticas de pesquisa
Manipulação de Metadados
- Extrai e processa metadados de colunas
- Lida com regras de validação
- Gerencia especificações de formato
- Rastreia dependências de fórmulas
- Mantém relacionamentos entre colunas
Análise de Saúde
- Resumo de notas clínicas usando Azure OpenAI
- Análise de sentimento de feedback de pacientes
- Pontuação de conformidade com protocolos
- Avaliação de impacto de pesquisa
- Análise de utilização de recursos
- Análise personalizada com geração otimizada de prompts
Processamento em Lote
- Agrupamento automático de linhas (3 linhas por lote para desempenho ideal)
- Acompanhamento e monitoramento de progresso
- Tratamento de erros e recuperação
- Metas de processamento personalizáveis
- Suporte a análise de múltiplas colunas
- Fragmentação de conteúdo ciente de tokens para textos grandes
- Processamento de jobs em segundo plano com ThreadPoolExecutor
Gerenciamento de Jobs
- Monitoramento de status em tempo real
- Acompanhamento detalhado de progresso
- Relatórios de erros e registro
- Suporte a cancelamento de jobs
- Controles de operações em lote
Referências Entre Planilhas
- Análise de fórmulas e mapeamento de dependências
- Detecção e validação de referências entre planilhas
- Identificação de links quebrados e sugestões de reparo
- Geração automatizada de fórmulas (INDEX_MATCH, VLOOKUP, SUMIF, COUNTIF)
- Análise de impacto de referências entre workspaces
- Suporte a modelos de fórmulas personalizados

Configuração

Pré-requisitos

Node.js e npm
Conda (para gerenciamento de ambiente)
Token de acesso à API do Smartsheet
Acesso à API Azure OpenAI (para recursos de análise em lote)

Configuração do Ambiente

Crie um ambiente conda dedicado:

conda create -n cline_mcp_env python=3.12 nodejs -y
conda activate cline_mcp_env

Instale as dependências do Node.js:

npm install

Instale as dependências do Python:

cd smartsheet_ops
pip install -e .
cd ..

Nota: O pacote Python inclui dependências para:

smartsheet-python-sdk - Cliente da API Smartsheet
python-dotenv - Gerenciamento de variáveis de ambiente
openai - Integração com Azure OpenAI
tiktoken - Contagem de tokens para análise de IA

Compile o servidor TypeScript:

npm run build

Configuração

O servidor suporta dois modos de transporte:

Transporte STDIO (padrão): Para desenvolvimento local e uso via CLI
Transporte HTTP: Para clientes baseados na web e acesso à rede

1. Obtenha sua Chave de API do Smartsheet

Faça login no Smartsheet
Vá para Conta → Configurações Pessoais → Acesso à API
Gere um novo token de acesso

2. Configure para Transporte STDIO (Cline/Local)

O caminho de configuração depende do seu sistema operacional:

macOS:

~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Windows:

%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Linux:

~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "smartsheet": {
      "command": "/Users/[username]/anaconda3/envs/cline_mcp_env/bin/node",
      "args": [
        "/path/to/smartsheet-server/build/index.js",
        "--transport",
        "stdio"
      ],
      "env": {
        "PYTHON_PATH": "/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3",
        "SMARTSHEET_API_KEY": "your-api-key",
        "AZURE_OPENAI_API_KEY": "your-azure-openai-key",
        "AZURE_OPENAI_API_BASE": "your-azure-openai-endpoint",
        "AZURE_OPENAI_API_VERSION": "your-api-version",
        "AZURE_OPENAI_DEPLOYMENT": "your-deployment-name"
      },
      "disabled": false,
      "autoApprove": [
        "get_column_map",
        "smartsheet_write",
        "smartsheet_update",
        "smartsheet_delete",
        "smartsheet_search",
        "smartsheet_add_column",
        "smartsheet_delete_column",
        "smartsheet_rename_column",
        "smartsheet_bulk_update",
        "start_batch_analysis",
        "get_job_status",
        "cancel_batch_analysis",
        "get_all_row_ids",
        "list_workspaces",
        "get_workspace",
        "create_workspace",
        "create_sheet_in_workspace",
        "list_workspace_sheets"
      ]
    }
  }
}

3. Configure para Transporte HTTP

Para clientes MCP baseados na web ou acesso à rede, use o modo de transporte HTTP:

Inicie o servidor:

# Start with default port (3000)
SMARTSHEET_API_KEY=your-api-key PYTHON_PATH=/path/to/python smartsheet-server --transport http

# Start with custom port
SMARTSHEET_API_KEY=your-api-key PYTHON_PATH=/path/to/python smartsheet-server --transport http --port 8080

Configuração do Cliente:

{
  "mcpServers": {
    "smartsheet-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-optional-auth-token"
      }
    }
  }
}

Verificação de Saúde:

O servidor HTTP fornece um endpoint de verificação de saúde:

curl http://localhost:3000/health
# Response: {"status":"ok","server":"smartsheet-mcp"}

Iniciando o Servidor

Transporte STDIO (Padrão)

O servidor iniciará automaticamente quando o Cline ou o Claude Desktop precisar dele. No entanto, você também pode iniciá-lo manualmente para testes.

macOS/Linux:

# Activate the environment
conda activate cline_mcp_env

# Start with STDIO transport (default)
PYTHON_PATH=/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3 SMARTSHEET_API_KEY=your-api-key node build/index.js

# Or explicitly specify STDIO transport
PYTHON_PATH=/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3 SMARTSHEET_API_KEY=your-api-key node build/index.js --transport stdio

Windows:

:: Activate the environment
conda activate cline_mcp_env

:: Start with STDIO transport
set PYTHON_PATH=C:\Users\[username]\anaconda3\envs\cline_mcp_env\python.exe
set SMARTSHEET_API_KEY=your-api-key
node build\index.js --transport stdio

Transporte HTTP

Para clientes baseados na web ou acesso à rede:

macOS/Linux:

# Activate the environment
conda activate cline_mcp_env

# Start HTTP server on default port (3000)
PYTHON_PATH=/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3 SMARTSHEET_API_KEY=your-api-key node build/index.js --transport http

# Start HTTP server on custom port
PYTHON_PATH=/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3 SMARTSHEET_API_KEY=your-api-key node build/index.js --transport http --port 8080

Windows:

:: Activate the environment
conda activate cline_mcp_env

:: Start HTTP server
set PYTHON_PATH=C:\Users\[username]\anaconda3\envs\cline_mcp_env\python.exe
set SMARTSHEET_API_KEY=your-api-key
node build\index.js --transport http --port 3000

Opções de Linha de Comando

# View help
node build/index.js --help

# Available options:
--transport <type>    # "stdio" (default) or "http"
--port <number>       # HTTP port (default: 3000, only used with --transport http)
--help, -h            # Show help message

Verificando a Instalação

Transporte STDIO

O servidor deve exibir "Smartsheet MCP server running on stdio" quando iniciado
Teste a conexão usando qualquer ferramenta MCP (por exemplo, get_column_map)

Transporte HTTP

O servidor deve exibir "Smartsheet MCP server running on HTTP port 3000" quando iniciado
Teste o endpoint de saúde: curl http://localhost:3000/health
Resposta esperada: {"status":"ok","server":"smartsheet-mcp"}

Ambiente Python

Verifique se o ambiente Python possui os pacotes necessários instalados:

conda activate cline_mcp_env
pip show smartsheet-python-sdk openai tiktoken python-dotenv

O pacote Python deve incluir estas dependências principais:

smartsheet-python-sdk>=2.105.1 - Cliente da API Smartsheet
openai>=1.0.0 - Integração com Azure OpenAI
tiktoken>=0.5.0 - Contagem de tokens para análise de IA
python-dotenv>=1.0.0 - Gerenciamento de variáveis de ambiente

Exemplos de Uso

Obtendo Informações de Coluna (Leitura)

// Get column mapping and sample data
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_column_map",
  arguments: {
    sheet_id: "your-sheet-id",
  },
});

Escrevendo Dados (Criação)

// Write new rows to Smartsheet
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "smartsheet_write",
  arguments: {
    sheet_id: "your-sheet-id",
    column_map: {
      "Column 1": "1234567890",
      "Column 2": "0987654321",
    },
    row_data: [
      {
        "Column 1": "Value 1",
        "Column 2": "Value 2",
      },
    ],
  },
});

Pesquisando Dados

// Basic text search
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "smartsheet_search",
  arguments: {
    sheet_id: "your-sheet-id",
    pattern: "search text",
    options: {
      case_sensitive: false,
      whole_word: false,
      columns: ["Column1", "Column2"], // Optional: limit search to specific columns
    },
  },
});

// Search PICKLIST column with exact matching
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "smartsheet_search",
  arguments: {
    sheet_id: "your-sheet-id",
    pattern: "In Progress",
    options: {
      columns: ["Status"], // PICKLIST column
      case_sensitive: true,
      whole_word: true,
    },
  },
});

Atualizando Dados (Atualização)

// Update existing rows
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "smartsheet_update",
  arguments: {
    sheet_id: "your-sheet-id",
    column_map: {
      Status: "850892021780356",
      Notes: "6861293012340612",
    },
    updates: [
      {
        row_id: "7670198317295492",
        data: {
          Status: "In Progress",
          Notes: "Updated via MCP server",
        },
      },
    ],
  },
});

Excluindo Dados (Exclusão)

// Delete rows from Smartsheet
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "smartsheet_delete",
  arguments: {
    sheet_id: "your-sheet-id",
    row_ids: ["7670198317295492", "7670198317295493"],
  },
});

Exemplos de Análise de Saúde

// Example 1: Pediatric Innovation Scoring
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "start_batch_analysis",
  arguments: {
    sheet_id: "your-sheet-id",
    type: "custom",
    sourceColumns: ["Ideas", "Implementation_Details"],
    targetColumn: "Pediatric_Score",
    rowIds: ["row1", "row2", "row3"], // Optional: specify rows, or omit for all rows
    customGoal:
      "Score each innovation 1-100 based on pediatric healthcare impact. Consider: 1) Direct benefit to child patients, 2) Integration with pediatric workflows, 3) Implementation feasibility in children's hospital, 4) Safety considerations for pediatric use. Return only a number.",
  },
});

// Example 2: Clinical Note Summarization
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "start_batch_analysis",
  arguments: {
    sheet_id: "your-sheet-id",
    type: "summarize",
    sourceColumns: ["Clinical_Notes"],
    targetColumn: "Note_Summary",
    rowIds: ["row1", "row2"], // Optional: specify rows, or omit for all rows
  },
});

// Example 3: Patient Satisfaction Analysis
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "start_batch_analysis",
  arguments: {
    sheet_id: "your-sheet-id",
    type: "sentiment",
    sourceColumns: ["Patient_Feedback"],
    targetColumn: "Satisfaction_Score",
    rowIds: ["row1", "row2"], // Optional: specify rows, or omit for all rows
  },
});

// Example 4: Get All Row IDs for Batch Processing
const allRows = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_all_row_ids",
  arguments: {
    sheet_id: "your-sheet-id",
  },
});

// Example 5: Monitor Analysis Job Progress
const jobStatus = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_job_status",
  arguments: {
    sheet_id: "your-sheet-id",
    jobId: "job-uuid-from-start-analysis",
  },
});

Exemplos de Gerenciamento de Workspace

// List all accessible workspaces
const workspaces = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "list_workspaces",
  arguments: {},
});

// Get details of a specific workspace
const workspace = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_workspace",
  arguments: {
    workspace_id: "6621332407379844",
  },
});

// Create a new workspace
const newWorkspace = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "create_workspace",
  arguments: {
    name: "Project Management",
  },
});

// Create a sheet in a workspace
const newSheet = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "create_sheet_in_workspace",
  arguments: {
    workspace_id: "6621332407379844",
    name: "Task Tracker",
    columns: [
      { title: "Task Name", type: "TEXT_NUMBER" },
      { title: "Due Date", type: "DATE" },
      {
        title: "Status",
        type: "PICKLIST",
        options: ["Not Started", "In Progress", "Completed"],
      },
    ],
  },
});

// List all sheets in a workspace
const sheets = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "list_workspace_sheets",
  arguments: {
    workspace_id: "6621332407379844",
  },
});

Exemplos de Uso de Recursos

// Access static resources
const projectTemplate = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://templates/project-plan",
});

const columnTypes = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://schemas/column-types",
});

const formulaGuide = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://best-practices/formulas",
});

// Access dynamic resources
const sheetSummary = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://8596778555232132/summary",
});

const ganttData = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://8596778555232132/gantt-data",
});

const workspaceOverview = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://6621332407379844/overview",
});

const dependencyMap = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://8596778555232132/dependencies",
});

const healthReport = await access_mcp_resource({
  server_name: "smartsheet",
  uri: "smartsheet://8596778555232132/health-report",
});

Exemplos de Uso de Prompts

// Project plan creation guidance
const projectPlanPrompt = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_prompt",
  arguments: {
    name: "create_project_plan",
    arguments: {
      project_name: "Website Redesign",
      project_type: "software",
      duration_estimate: "3 months",
    },
  },
});

// Project health analysis
const analysisPrompt = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_prompt",
  arguments: {
    name: "analyze_project_status",
    arguments: {
      sheet_id: "8596778555232132",
      focus_area: "timeline",
    },
  },
});

// Workflow optimization suggestions
const optimizationPrompt = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_prompt",
  arguments: {
    name: "optimize_workflow",
    arguments: {
      sheet_id: "8596778555232132",
      workflow_type: "approval",
    },
  },
});

// Data insights extraction
const insightsPrompt = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_prompt",
  arguments: {
    name: "generate_insights",
    arguments: {
      sheet_id: "8596778555232132",
      insight_type: "bottlenecks",
    },
  },
});

// Executive dashboard creation
const dashboardPrompt = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_prompt",
  arguments: {
    name: "create_dashboard_summary",
    arguments: {
      workspace_id: "6621332407379844",
      summary_focus: "risks",
    },
  },
});

// Conditional formatting setup
const formattingPrompt = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_prompt",
  arguments: {
    name: "setup_conditional_formatting",
    arguments: {
      sheet_id: "8596778555232132",
      formatting_goal: "status indicators",
    },
  },
});

Desenvolvimento

Para desenvolvimento com reconstrução automática:

npm run watch

Pipeline CI/CD

Este projeto implementa um pipeline CI/CD abrangente de 8 estágios com GitHub Actions, garantindo qualidade de código, segurança e confiabilidade em todos os componentes.

Arquitetura do Pipeline

O pipeline CI/CD consiste em 8 jobs coordenados que são executados em paralelo e em sequência para eficiência ideal:

Verificações de Qualidade TypeScript - ESLint, verificação de tipos, validação de formatação
Verificações de Qualidade Python - Black, Flake8, verificação de tipos MyPy
Testes TypeScript - Testes em matriz no Node.js 16, 18, 20 com cobertura
Testes Python - Testes em matriz no Python 3.8, 3.9, 3.10, 3.11 com cobertura
Cobertura Combinada - Relatório de cobertura unificado e integração com Codecov
Testes de Integração - Validação de ponta a ponta e verificação de inicialização do servidor MCP
Varredura de Segurança - npm audit, safety do Python, análise de segurança Bandit
Build e Empacotamento - Criação de artefatos e verificação de implantação

Principais Recursos do Pipeline

Garantia de Qualidade:

Suporte a Múltiplas Linguagens: Cobertura completa do pipeline para TypeScript e Python
Testes em Matriz: Verificação de compatibilidade entre plataformas
Portões de Qualidade de Código: ESLint, Black, Flake8, MyPy, modo estrito do TypeScript
Aplicação de Cobertura: Validação automatizada de limites de cobertura
Varredura de Segurança: Avaliação regular de vulnerabilidades com safety e Bandit

Otimização de Desempenho:

Execução Paralela: Jobs independentes executados simultaneamente para feedback mais rápido
Cache Inteligente: Módulos Node e dependências Python armazenados em cache entre execuções
Execução Condicional: Testes de desempenho apenas em PRs, cobertura completa no main
Gerenciamento de Artefatos: Artefatos de build preservados por 7-30 dias

Integração e Implantação:

Validação do Protocolo MCP: Teste de inicialização do servidor e conformidade com o protocolo
Suporte a Docker: Builds de contêineres multi-plataforma (linux/amd64, linux/arm64)
Lançamentos Automatizados: Lançamentos com tags de versão e geração de changelog
Gerenciamento de Dependências: Auditorias de segurança semanais e automação de atualizações

Gatilhos de Workflow

# Comprehensive testing on main branches
- push: [main, develop]
- pull_request: [main, develop]

# Additional workflows
- release: version tags (v*.*.*)
- security: weekly dependency scans
- performance: PR-specific testing

Monitoramento de Status

O pipeline fornece notificações abrangentes e gerenciamento de artefatos, garantindo que todas as partes interessadas tenham visibilidade do status do build, resultados de testes e prontidão para implantação.

Testes e Garantia de Qualidade

Este projeto mantém cobertura de testes abrangente e garantia de qualidade em componentes TypeScript e Python com pipelines CI/CD automatizados.

Infraestrutura de Testes

Status dos Testes: 54/54 testes TypeScript passando, 5/5 testes Python passando

Nossa estratégia abrangente de testes inclui:

Testes Unitários: Jest para TypeScript (54 testes), pytest para Python (5 testes principais)
Testes de Integração: Testes entre componentes e validação do protocolo MCP
Qualidade de Código: ESLint, verificação TypeScript, Black, Flake8, MyPy
Varredura de Segurança: npm audit, verificações de segurança do Python, análise Bandit
Análise de Cobertura: Relatórios de cobertura combinados com integração Codecov
Testes de Performance: Medição do tempo de inicialização e rastreamento de benchmarks

Visão Geral da Cobertura de Testes

Métricas atuais de cobertura:

Cobertura TypeScript: Cobertura abrangente da implementação do servidor MCP
Cobertura Python: Operações principais e funcionalidade da CLI
Relatórios Combinados: Análise unificada de cobertura em ambas as linguagens
Rastreamento Automatizado: Monitoramento de cobertura em tempo real via Codecov

Comandos Rápidos de Teste

# Essential testing commands for daily development
npm run ci:check          # Pre-commit validation (recommended before push)
npm run test:all          # Run all tests with coverage
npm run coverage          # Full coverage analysis with combined reporting
npm run coverage:open     # View coverage reports in browser

# Individual test suites
npm test                  # TypeScript tests only
npm run test:python       # Python tests only
npm run test:coverage     # TypeScript with coverage
npm run test:python:coverage  # Python with coverage

# Development testing
npm run test:watch        # Watch mode for continuous testing
npm run coverage:clean    # Coverage without external uploads

Comandos Abrangentes de Teste

# Quality assurance
npm run lint              # ESLint for TypeScript
npm run lint:fix          # Auto-fix linting issues
npm run format            # Prettier code formatting
npm run typecheck         # TypeScript type validation

# Coverage and reporting  
npm run badges:update     # Generate coverage badges
npm run coverage:ci       # CI-optimized coverage reporting
npm run coverage:view     # Open all coverage reports
npm run coverage:combined # View combined coverage report

# Build and validation
npm run build             # Build TypeScript
npm run watch             # Development build with watch
npm run inspector         # MCP inspector for tool testing

Relatórios e Artefatos de Teste

Após executar os testes, relatórios detalhados estão disponíveis:

Cobertura TypeScript: ./coverage/index.html
Cobertura Python: ./smartsheet_ops/coverage/index.html
Cobertura Combinada: ./coverage-combined/index.html
Artefatos de Teste: Disponíveis nas execuções do pipeline de CI/CD

Limiares de Qualidade

O projeto impõe padrões rigorosos de qualidade:

Cobertura TypeScript: mínimo de 60% (configurável por componente)
Cobertura Python: 80% geral com relatórios linha por linha
Qualidade de Código: regras ESLint, modo estrito TypeScript, Python Black/Flake8
Segurança: Auditorias regulares de dependências e varredura de vulnerabilidades
Desempenho: Monitoramento do tempo de inicialização e detecção de regressões

Suporte a Docker

Compile e execute a versão containerizada:

# Build Docker image
docker build -t smartsheet-server .

# Run with environment variables
docker run -e SMARTSHEET_API_KEY=your_key -e PYTHON_PATH=/usr/local/bin/python smartsheet-server

Depuração

Como os servidores MCP se comunicam via stdio, a depuração pode ser desafiadora. O servidor implementa registro abrangente de erros e fornece mensagens de erro detalhadas através do protocolo MCP.

Principais recursos de depuração:

Registro de erros no stderr
Mensagens de erro detalhadas nas respostas MCP
Validação de tipos em múltiplos níveis
Relatórios abrangentes de resultados de operações
Análise de dependências para operações de coluna
Rastreamento de referências de fórmulas

Tratamento de Erros

O servidor implementa uma abordagem de tratamento de erros em múltiplas camadas:

Camada MCP
- Valida parâmetros de ferramentas
- Trata erros de nível de protocolo
- Fornece respostas de erro formatadas
- Gerencia timeouts e tentativas
Camada CLI
- Valida argumentos de comando
- Trata erros de execução
- Formata mensagens de erro como JSON
- Valida operações de coluna
Camada de Operações
- Trata erros da API Smartsheet
- Valida tipos e formatos de dados
- Fornece contexto detalhado de erro
- Gerencia dependências de coluna
- Valida referências de fórmulas
- Garante a integridade dos dados

Contribuindo

Contribuições são bem-vindas! Por favor, garanta:

O código TypeScript/Python segue o estilo existente
Novos recursos incluem tratamento de erros adequado
As alterações mantêm compatibilidade retroativa
As atualizações incluem documentação adequada
As operações de coluna mantêm a integridade dos dados
As referências de fórmulas são tratadas adequadamente