Smartsheet

Integra con Smartsheet para la gestión de proyectos y análisis de datos, requiriendo un token de acceso API.

GitHub
12
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Smartsheet

Tests MIT License Version 0.3.0

Node.js Versions Python Versions

Un servidor de Model Context Protocol (MCP) que proporciona una integración perfecta con Smartsheet, permitiendo operaciones automatizadas en documentos de Smartsheet a través de una interfaz estandarizada. Este servidor cierra la brecha entre las herramientas de automatización impulsadas por IA y la potente plataforma de colaboración de Smartsheet.

Descripción general

El Servidor MCP de Smartsheet está diseñado para facilitar interacciones inteligentes con Smartsheet, proporcionando un sólido conjunto de herramientas para la gestión de documentos, operaciones de datos y personalización de columnas. Sirve como un componente crítico en flujos de trabajo automatizados, permitiendo que los sistemas de IA interactúen programáticamente con los datos de Smartsheet mientras mantienen la integridad de los datos y aplican reglas de negocio.

Beneficios clave

  • Integración inteligente: Conecta sin problemas los sistemas de IA con la plataforma de colaboración de Smartsheet
  • Integridad de datos: Aplica reglas de validación y mantiene la integridad referencial en todas las operaciones
  • Gestión de fórmulas: Preserva y actualiza automáticamente las referencias de fórmulas
  • Configuración flexible: Admite varios tipos de columnas y estructuras de datos complejas
  • Resiliencia ante errores: Implementa un manejo integral de errores y validación en múltiples capas
  • Analítica sanitaria: Capacidades de análisis especializadas para datos clínicos y de investigación
  • Procesamiento por lotes: Manejo eficiente de grandes conjuntos de datos sanitarios
  • Puntuación personalizada: Sistemas de puntuación flexibles para iniciativas sanitarias e investigación

Casos de uso

  1. Analítica de investigación clínica

    • Puntuación de cumplimiento de protocolos
    • Análisis de datos de pacientes
    • Evaluación del impacto de la investigación
    • Procesamiento de datos de ensayos clínicos
    • Resumen automatizado de notas de investigación

  2. Operaciones hospitalarias

    • Análisis de utilización de recursos
    • Puntuación de satisfacción del paciente
    • Métricas de eficiencia departamental
    • Analítica de rendimiento del personal
    • Seguimiento de métricas de calidad

  3. Innovación sanitaria

    • Puntuación de alineación pediátrica
    • Evaluación del impacto de la innovación
    • Priorización de la investigación
    • Análisis de viabilidad de implementación
    • Evaluación del valor clínico

  4. Gestión automatizada de documentos

    • Modificaciones programáticas de la estructura de hojas
    • Creación y gestión dinámica de columnas
    • Validación y formato automatizado de datos

  5. Operaciones de datos

    • Actualizaciones masivas de datos con comprobaciones de integridad
    • Detección inteligente de duplicados
    • Modificaciones conscientes de fórmulas

  6. Integración de sistemas

    • Personalización de hojas impulsada por IA
    • Flujos de trabajo de informes automatizados
    • Sincronización de datos entre sistemas

Puntos de integración

El servidor se integra con:

  • API de Smartsheet para operaciones de datos
  • Protocolo MCP para comunicación estandarizada
  • Herramientas de desarrollo local a través de la interfaz stdio
  • Sistemas de monitoreo mediante registro estructurado

Características

Herramientas (34 disponibles)

  1. get_column_map (Lectura)

    • Recupera el mapeo de columnas y datos de muestra de una hoja de Smartsheet
    • Proporciona metadatos detallados de columnas, incluyendo:
      • Tipos de columnas (columnas de sistema, fórmulas, listas de selección)
      • Reglas de validación
      • Especificaciones de formato
      • Configuraciones de numeración automática
    • Devuelve datos de muestra para contexto
    • Incluye ejemplos de uso para escribir datos

  2. get_sheet_info (Lectura - Alias)

    • Alias de get_column_map que proporciona funcionalidad idéntica
    • Mantiene compatibilidad hacia atrás con integraciones existentes

  3. smartsheet_write (Creación)

    • Escribe nuevas filas en Smartsheet con manejo inteligente de:
      • Columnas gestionadas por el sistema
      • Valores de listas de selección múltiple
      • Columnas basadas en fórmulas
    • Implementa detección automática de duplicados
    • Agrega nuevas filas al final de la hoja (después de las entradas existentes)
    • Devuelve resultados detallados de la operación, incluidos los IDs de fila

  4. smartsheet_update (Actualización)

    • Actualiza filas existentes en una hoja de Smartsheet
    • Admite actualizaciones parciales (modificar campos específicos)
    • Mantiene la integridad de los datos con validación
    • Maneja campos de selección múltiple de manera consistente
    • Devuelve detalles de éxito/fallo por fila

  5. smartsheet_delete (Eliminación)

    • Elimina filas de una hoja de Smartsheet
    • Admite eliminación por lotes de múltiples filas
    • Valida la existencia de filas y los permisos
    • Devuelve resultados detallados de la operación

  6. smartsheet_search (Búsqueda)

    • Realiza búsquedas avanzadas en hojas
    • Admite múltiples modos de búsqueda:
      • Búsqueda de texto con soporte de expresiones regulares
      • Coincidencia de valores exactos para columnas PICKLIST
      • Opciones de distinción entre mayúsculas y minúsculas y palabra completa
    • Capacidades de búsqueda específicas por columna
    • Devuelve:
      • IDs de filas coincidentes (resultado principal)
      • Información detallada de coincidencias
      • Metadatos y estadísticas de búsqueda

  7. smartsheet_add_column (Gestión de columnas)

    • Agrega nuevas columnas a una hoja de Smartsheet
    • Admite todos los tipos de columnas:
      • TEXT_NUMBER
      • DATE
      • CHECKBOX
      • PICKLIST
      • CONTACT_LIST
    • Opciones configurables:
      • Índice de posición
      • Reglas de validación
      • Definiciones de fórmulas
      • Opciones de listas de selección
    • Aplica el límite de columnas (400) con validación
    • Devuelve información detallada de la columna

  8. smartsheet_delete_column (Gestión de columnas)

    • Elimina columnas de manera segura con verificación de dependencias
    • Valida referencias de fórmulas antes de la eliminación
    • Evita la eliminación de columnas utilizadas en fórmulas
    • Devuelve información detallada de dependencias
    • Admite opción de eliminación forzada

  9. smartsheet_rename_column (Gestión de columnas)

    • Renombra columnas preservando las relaciones
    • Actualiza automáticamente las referencias de fórmulas
    • Mantiene la integridad de los datos
    • Valida la unicidad de nombres
    • Devuelve información detallada de la actualización

  10. smartsheet_bulk_update (Actualizaciones condicionales)

    • Realiza actualizaciones masivas condicionales basadas en reglas
    • Admite evaluación de condiciones complejas:
      • Múltiples operadores (igual, contiene, mayor que, etc.)
      • Comparaciones específicas por tipo (texto, fechas, números)
      • Comprobaciones de vacío/no vacío
    • Procesamiento por lotes con tamaño configurable
    • Manejo integral de errores y reversión
    • Seguimiento detallado de resultados de operaciones

  11. get_all_row_ids (Utilidad)

    • Recupera todos los IDs de fila de una hoja de Smartsheet
    • Útil para operaciones por lotes y análisis de datos
    • Devuelve la lista completa de identificadores de fila
    • Admite hojas grandes de manera eficiente

  12. start_batch_analysis (Analítica sanitaria)

    • Procesa hojas completas o filas seleccionadas con análisis de IA
    • Admite múltiples tipos de análisis:
      • Resumen de notas clínicas
      • Análisis de sentimiento de comentarios de pacientes
      • Puntuación personalizada para iniciativas sanitarias
      • Evaluación del impacto de la investigación
    • Características:
      • Procesamiento automático por lotes (3 filas por lote para rendimiento óptimo)
      • Seguimiento de progreso y monitoreo de estado
      • Manejo de errores con informes detallados
      • Objetivos de análisis personalizables mediante Azure OpenAI
      • Soporte para múltiples columnas de origen
      • Fragmentación de contenido consciente de tokens para textos largos

  13. get_job_status (Monitoreo de análisis)

    • Realiza seguimiento del progreso del análisis por lotes
    • Proporciona estadísticas detalladas del trabajo:
      • Total de filas a procesar
      • Conteo de filas procesadas
      • Conteo de filas fallidas
      • Marcas de tiempo de procesamiento
    • Actualizaciones de estado en tiempo real
    • Informes de errores integrales

  14. cancel_batch_analysis (Control de trabajos)

    • Cancela trabajos de análisis por lotes en ejecución
    • Terminación elegante del proceso
    • Mantiene la consistencia de los datos
    • Devuelve el estado final del trabajo

  15. list_workspaces (Gestión de espacios de trabajo)

    • Lista todos los espacios de trabajo accesibles
    • Devuelve IDs, nombres y enlaces permanentes de espacios de trabajo
    • Incluye información del nivel de acceso
    • Admite el descubrimiento de espacios de trabajo en toda la organización

  16. get_workspace (Gestión de espacios de trabajo)

    • Recupera información detallada del espacio de trabajo
    • Devuelve hojas, carpetas, informes y paneles contenidos
    • Proporciona detalles de nivel de acceso y permisos
    • Admite la exploración de contenido del espacio de trabajo

  17. create_workspace (Gestión de espacios de trabajo)

    • Crea un nuevo espacio de trabajo con el nombre especificado
    • Devuelve el nuevo ID del espacio de trabajo y confirmación
    • Permite la organización programática de espacios de trabajo
    • Admite la migración desde endpoints de carpetas obsoletos

  18. create_sheet_in_workspace (Gestión de espacios de trabajo)

    • Crea una nueva hoja directamente en un espacio de trabajo
    • Admite todos los tipos y configuraciones de columnas
    • Devuelve el nuevo ID de la hoja y detalles
    • Permite la creación y organización programática de hojas

  19. list_workspace_sheets (Gestión de espacios de trabajo)

    • Lista todas las hojas en un espacio de trabajo específico
    • Devuelve IDs, nombres y enlaces permanentes de hojas
    • Incluye marcas de tiempo de creación y modificación
    • Admite el descubrimiento de contenido del espacio de trabajo

  20. smartsheet_upload_attachment (Gestión de adjuntos)

    • Sube archivos a hojas, filas o comentarios
    • Admite múltiples tipos de adjuntos y validación de tamaño de archivo
    • Devuelve metadatos del adjunto y estado de subida

  21. smartsheet_get_attachments (Gestión de adjuntos)

    • Lista todos los adjuntos de una hoja o fila
    • Devuelve metadatos integrales de adjuntos
    • Incluye URLs de archivos, tamaños e información del creador

  22. smartsheet_download_attachment (Gestión de adjuntos)

    • Descarga adjuntos específicos al sistema de archivos local
    • Crea directorios según sea necesario y verifica las descargas
    • Devuelve estado de descarga e información del archivo

  23. smartsheet_delete_attachment (Gestión de adjuntos)

    • Elimina adjuntos de hojas
    • Valida permisos y devuelve estado de eliminación

  24. smartsheet_create_discussion (Gestión de discusiones)

    • Crea nuevos hilos de discusión en hojas o filas
    • Admite comentarios iniciales y títulos opcionales
    • Devuelve metadatos de la discusión y estado de creación

  25. smartsheet_add_comment (Gestión de discusiones)

    • Agrega comentarios a discusiones existentes
    • Mantiene la estructura de conversación en hilos
    • Devuelve detalles del comentario y marcas de tiempo

  26. smartsheet_get_discussions (Gestión de discusiones)

    • Lista todas las discusiones de hojas o filas
    • Inclusión opcional de todos los comentarios en la respuesta
    • Devuelve metadatos de la discusión e información de participantes

  27. smartsheet_get_comments (Gestión de discusiones)

    • Obtiene todos los comentarios en un hilo de discusión específico
    • Incluye información de adjuntos si está presente
    • Devuelve el historial cronológico de comentarios

  28. smartsheet_delete_comment (Gestión de discusiones)

    • Elimina comentarios específicos de discusiones
    • Valida permisos antes de la eliminación
    • Devuelve confirmación de eliminación

  29. smartsheet_get_cell_history (Historial de celdas y auditoría)

    • Obtiene el historial de modificaciones de celdas individuales
    • Incluye atribución de usuario y marcas de tiempo
    • Realiza seguimiento de cambios de valores, fórmulas y formato

  30. smartsheet_get_row_history (Historial de celdas y auditoría)

    • Obtiene el historial de cambios de filas completas
    • Proporciona una línea de tiempo cronológica de todos los cambios de celdas
    • Admite filtrado por columnas específicas y pistas de auditoría completas

  31. smartsheet_get_sheet_cross_references (Referencias entre hojas)

    • Analiza todas las referencias entre hojas dentro de una hoja
    • Identifica fórmulas que referencian otras hojas
    • Análisis detallado de patrones de fórmulas y dependencias

  32. smartsheet_find_sheet_references (Referencias entre hojas)

    • Encuentra todas las hojas que referencian una hoja objetivo específica
    • Busca en el espacio de trabajo o en todas las hojas accesibles
    • Mapeo integral de referencias y análisis de impacto

  33. smartsheet_validate_cross_references (Referencias entre hojas)

    • Valida todas las referencias entre hojas para detectar enlaces rotos
    • Identifica hojas referenciadas inaccesibles o eliminadas
    • Sugiere hojas alternativas para referencias rotas

  34. smartsheet_create_cross_reference (Referencias entre hojas)

    • Crea fórmulas INDEX_MATCH, VLOOKUP, SUMIF, COUNTIF
    • Construye fórmulas de referencia entre hojas programáticamente
    • Soporte para plantillas de fórmulas personalizadas y múltiples tipos de fórmulas

Recursos (4 estáticos + 5 plantillas dinámicas)

El servidor proporciona tanto recursos estáticos como plantillas de recursos dinámicos para un acceso mejorado a los datos e información contextual.

Recursos estáticos

  1. smartsheet://templates/project-plan - Plantilla de Plan de Proyecto

    • Plantilla de plan de proyecto preconstruida con mejores prácticas
    • Incluye estructura de columnas óptima para la gestión de tareas
    • Proporciona orientación sobre dependencias y asignación de recursos

  2. smartsheet://templates/task-tracker - Plantilla de Seguimiento de Tareas

    • Plantilla simple de seguimiento de tareas para colaboración en equipo
    • Enfocada en el monitoreo de progreso sin dependencias complejas
    • Ideal para equipos ágiles y flujos de trabajo simples

  3. smartsheet://schemas/column-types - Referencia de Tipos de Columna

    • Referencia completa de todos los tipos de columna compatibles con Smartsheet
    • Incluye nivel de soporte de API para cada tipo (completo, limitado, solo lectura)
    • Esencial para comprender las capacidades y limitaciones de las columnas

  4. smartsheet://best-practices/formulas - Mejores Prácticas de Fórmulas

    • Patrones comunes de fórmulas y ejemplos de cálculo
    • Mejores prácticas para rendimiento y mantenibilidad
    • Orientación sobre referencias entre hojas

Plantillas de Recursos Dinámicos

  1. smartsheet://{sheet_id}/summary - Resumen de Hoja

    • Resumen generado automáticamente con métricas clave y estado de salud
    • Indicadores de progreso y estadísticas de finalización
    • Análisis en tiempo real de los datos de la hoja

  2. smartsheet://{sheet_id}/gantt-data - Datos de Diagrama de Gantt

    • Formato estandarizado de datos de diagrama de Gantt para visualización
    • Datos de cronograma optimizados para herramientas de gestión de proyectos
    • Relaciones de dependencia e información de ruta crítica

  3. smartsheet://{workspace_id}/overview - Resumen del Espacio de Trabajo

    • Resumen integral del contenido del espacio de trabajo
    • Todas las hojas, informes y paneles en formato estructurado
    • Niveles de acceso y jerarquía organizacional

  4. smartsheet://{sheet_id}/dependencies - Mapa de Dependencias

    • Mapeo visual de dependencias para hojas de proyecto
    • Relaciones de tareas y análisis de ruta crítica
    • Identificación de cuellos de botella y sugerencias de optimización

  5. smartsheet://{sheet_id}/health-report - Informe de Salud de la Hoja

    • Análisis de salud que identifica problemas de calidad de datos
    • Detección de datos faltantes e identificación de fórmulas rotas
    • Oportunidades de optimización y recomendaciones

Prompts (6 Disponibles)

Plantillas de prompts inteligentes que brindan asistencia guiada para operaciones y análisis comunes de Smartsheet.

  1. create_project_plan - Guía de Creación de Plan de Proyecto

    • Creación guiada de plan de proyecto con mejores prácticas
    • Sugerencias de plantillas según el tipo y duración del proyecto
    • Recomendaciones de estructura de desglose de trabajo

  2. analyze_project_status - Análisis de Salud del Proyecto

    • Análisis integral de salud del proyecto con recomendaciones
    • Cumplimiento de cronograma e información sobre utilización de recursos
    • Identificación de riesgos y estrategias de mitigación

  3. optimize_workflow - Optimización de Flujos de Trabajo

    • Sugerencias para mejorar la estructura de hojas y flujos de trabajo
    • Oportunidades de automatización y mejoras de eficiencia
    • Recomendaciones para mejorar la experiencia del usuario

  4. generate_insights - Extracción de Información de Datos

    • Extraer información clave y patrones de los datos de la hoja
    • Análisis de tendencias y detección de anomalías
    • Inteligencia accionable y soporte para decisiones

  5. create_dashboard_summary - Creación de Panel Ejecutivo

    • Generar resúmenes ejecutivos desde múltiples hojas
    • Seguimiento de KPI de alto nivel e información estratégica
    • Informes y recomendaciones enfocados en liderazgo

  6. setup_conditional_formatting - Guía de Formato Condicional

    • Configuración paso a paso de formato condicional
    • Mejores prácticas de representación visual de datos
    • Configuración de indicadores de estado y seguimiento de progreso

Capacidades Clave

  • Gestión de Tipos de Columna

    • Maneja tipos de columna del sistema (AUTO_NUMBER, CREATED_DATE, etc.)
    • Soporta análisis de fórmulas y seguimiento de dependencias
    • Gestiona opciones de listas de selección y valores de selección múltiple
    • Operaciones integrales de columnas (agregar, eliminar, renombrar)
    • Preservación y actualización de referencias de fórmulas

  • Validación de Datos

    • Detección automática de duplicados
    • Validación de tipos de columna
    • Verificación de formato de datos
    • Análisis de dependencias de columnas
    • Validación de unicidad de nombres

  • Funcionalidad de Búsqueda

    • Capacidades de búsqueda avanzada
    • Búsqueda consciente del tipo:
      • Coincidencia exacta para valores PICKLIST
      • Coincidencia de patrones para campos de texto
      • Comparaciones numéricas
    • Opciones de búsqueda configurables:
      • Sensibilidad a mayúsculas
      • Coincidencia de palabras completas
      • Filtrado por columnas
    • Resultados integrales:
      • IDs de filas para filas coincidentes
      • Contexto detallado de coincidencias
      • Estadísticas de búsqueda

  • Manejo de Metadatos

    • Extrae y procesa metadatos de columnas
    • Maneja reglas de validación
    • Gestiona especificaciones de formato
    • Rastrea dependencias de fórmulas
    • Mantiene relaciones entre columnas

  • Analítica de Salud

    • Resumen de notas clínicas usando Azure OpenAI
    • Análisis de sentimiento de comentarios de pacientes
    • Puntuación de cumplimiento de protocolos
    • Evaluación de impacto de investigación
    • Análisis de utilización de recursos
    • Análisis personalizado con generación optimizada de prompts

  • Procesamiento por Lotes

    • Agrupación automática de filas (3 filas por lote para rendimiento óptimo)
    • Seguimiento y monitoreo de progreso
    • Manejo de errores y recuperación
    • Objetivos de procesamiento personalizables
    • Soporte de análisis de múltiples columnas
    • Fragmentación de contenido consciente de tokens para texto grande
    • Procesamiento de trabajos en segundo plano con ThreadPoolExecutor

  • Gestión de Trabajos

    • Monitoreo de estado en tiempo real
    • Seguimiento detallado de progreso
    • Informes de errores y registro
    • Soporte de cancelación de trabajos
    • Controles de operaciones por lotes

  • Referencias Entre Hojas

    • Análisis de fórmulas y mapeo de dependencias
    • Detección y validación de referencias entre hojas
    • Identificación de enlaces rotos y sugerencias de reparación
    • Generación automatizada de fórmulas (INDEX_MATCH, VLOOKUP, SUMIF, COUNTIF)
    • Análisis de impacto de referencias entre espacios de trabajo
    • Soporte de plantillas de fórmulas personalizadas

Configuración

Requisitos Previos

  • Node.js y npm
  • Conda (para gestión de entornos)
  • Token de acceso a la API de Smartsheet
  • Acceso a la API de Azure OpenAI (para funciones de análisis por lotes)

Configuración del Entorno

  1. Crear un entorno conda dedicado:
conda create -n cline_mcp_env python=3.12 nodejs -y
conda activate cline_mcp_env
  1. Instalar dependencias de Node.js:
npm install
  1. Instalar dependencias de Python:
cd smartsheet_ops
pip install -e .
cd ..

Nota: El paquete de Python incluye dependencias para:

  • smartsheet-python-sdk - Cliente de API de Smartsheet
  • python-dotenv - Gestión de variables de entorno
  • openai - Integración con Azure OpenAI
  • tiktoken - Conteo de tokens para análisis de IA
  1. Compilar el servidor TypeScript:
npm run build

Configuración

El servidor soporta dos modos de transporte:

  • Transporte STDIO (predeterminado): Para desarrollo local y uso de CLI
  • Transporte HTTP: Para clientes basados en web y acceso de red

1. Obtener su Clave de API de Smartsheet

  1. Inicie sesión en Smartsheet
  2. Vaya a Cuenta → Configuración Personal → Acceso a API
  3. Genere un nuevo token de acceso

2. Configurar para Transporte STDIO (Cline/Local)

La ruta de configuración depende de su sistema operativo:

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. Configurar para Transporte HTTP

Para clientes MCP basados en web o acceso de red, use el modo de transporte HTTP:

Iniciar el 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

Configuración del Cliente:

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

Verificación de Salud:

El servidor HTTP proporciona un endpoint de verificación de salud:

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

Iniciar el Servidor

Transporte STDIO (Predeterminado)

El servidor se iniciará automáticamente cuando Cline o Claude Desktop lo necesite. Sin embargo, también puede iniciarlo manualmente para pruebas.

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 basados en web o acceso de red:

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

Opciones de Línea de Comandos

# 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

Verificación de la Instalación

Transporte STDIO

  1. El servidor debería mostrar "Smartsheet MCP server running on stdio" al iniciarse
  2. Pruebe la conexión usando cualquier herramienta MCP (por ejemplo, get_column_map)

Transporte HTTP

  1. El servidor debería mostrar "Smartsheet MCP server running on HTTP port 3000" al iniciarse
  2. Pruebe el endpoint de salud: curl http://localhost:3000/health
  3. Respuesta esperada: {"status":"ok","server":"smartsheet-mcp"}

Entorno de Python

Verifique que el entorno de Python tenga los paquetes requeridos instalados:

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

El paquete de Python debería incluir estas dependencias clave:

  • smartsheet-python-sdk>=2.105.1 - Cliente de API de Smartsheet
  • openai>=1.0.0 - Integración con Azure OpenAI
  • tiktoken>=0.5.0 - Conteo de tokens para análisis de IA
  • python-dotenv>=1.0.0 - Gestión de variables de entorno

Ejemplos de Uso

Obtener Información de Columnas (Lectura)

// 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",
  },
});

Escribir Datos (Crear)

// 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",
      },
    ],
  },
});

Buscar Datos

// 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,
    },
  },
});

Actualizar Datos (Actualizar)

// 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",
        },
      },
    ],
  },
});

Eliminar Datos (Eliminar)

// 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"],
  },
});

Ejemplos de Analítica de Salud

// 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",
  },
});

Ejemplos de Gestión de Espacios de Trabajo

// 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",
  },
});

Ejemplos 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",
});

Ejemplos 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",
    },
  },
});

Desarrollo

Para desarrollo con reconstrucción automática:

npm run watch

Pipeline de CI/CD

Este proyecto implementa un pipeline integral de CI/CD de 8 etapas con GitHub Actions, garantizando calidad de código, seguridad y confiabilidad en todos los componentes.

Arquitectura del Pipeline

El pipeline de CI/CD consta de 8 trabajos coordinados que se ejecutan en paralelo y en secuencia para una eficiencia óptima:

  1. Verificaciones de Calidad de TypeScript - ESLint, verificación de tipos, validación de formato
  2. Verificaciones de Calidad de Python - Black, Flake8, verificación de tipos MyPy
  3. Pruebas de TypeScript - Pruebas matriciales en Node.js 16, 18, 20 con cobertura
  4. Pruebas de Python - Pruebas matriciales en Python 3.8, 3.9, 3.10, 3.11 con cobertura
  5. Cobertura Combinada - Informes de cobertura unificados e integración con Codecov
  6. Pruebas de Integración - Validación de extremo a extremo y verificación de inicio del servidor MCP
  7. Escaneo de Seguridad - npm audit, safety de Python, análisis de seguridad Bandit
  8. Compilación y Empaquetado - Creación de artefactos y verificación de despliegue

Características Clave del Pipeline

Aseguramiento de Calidad:

  • Soporte Multilenguaje: Cobertura completa del pipeline para TypeScript y Python
  • Pruebas Matriciales: Verificación de compatibilidad multiplataforma
  • Puertas de Calidad de Código: ESLint, Black, Flake8, MyPy, modo estricto de TypeScript
  • Aplicación de Cobertura: Validación automatizada de umbrales de cobertura
  • Escaneo de Seguridad: Evaluación regular de vulnerabilidades con safety y Bandit

Optimización de Rendimiento:

  • Ejecución en Paralelo: Los trabajos independientes se ejecutan simultáneamente para retroalimentación más rápida
  • Caché Inteligente: Módulos de Node y dependencias de Python almacenados en caché entre ejecuciones
  • Ejecución Condicional: Pruebas de rendimiento solo en PRs, cobertura completa en main
  • Gestión de Artefactos: Artefactos de compilación preservados durante 7-30 días

Integración y Despliegue:

  • Validación del Protocolo MCP: Pruebas de inicio del servidor y cumplimiento del protocolo
  • Soporte Docker: Compilaciones de contenedores multiplataforma (linux/amd64, linux/arm64)
  • Lanzamientos Automatizados: Lanzamientos etiquetados por versión con generación de registro de cambios
  • Gestión de Dependencias: Auditorías de seguridad semanales y automatización de actualizaciones

Disparadores del Flujo de Trabajo

# 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

Monitoreo de Estado

CI Pipeline Security Scan Codecov Coverage

El pipeline proporciona notificaciones integrales y gestión de artefactos, garantizando que todas las partes interesadas tengan visibilidad del estado de compilación, resultados de pruebas y preparación para el despliegue.

Pruebas y Aseguramiento de Calidad

Este proyecto mantiene cobertura de pruebas integral y aseguramiento de calidad en componentes de TypeScript y Python con pipelines automatizados de CI/CD.

Infraestructura de Pruebas

Estado de Pruebas: 54/54 pruebas de TypeScript aprobadas, 5/5 pruebas de Python aprobadas

Nuestra estrategia integral de pruebas incluye:

  • Pruebas unitarias: Jest para TypeScript (54 pruebas), pytest para Python (5 pruebas principales)
  • Pruebas de integración: Pruebas entre componentes y validación del protocolo MCP
  • Calidad del código: ESLint, verificación de TypeScript, Black, Flake8, MyPy
  • Escaneo de seguridad: npm audit, comprobaciones de seguridad de Python, análisis de Bandit
  • Análisis de cobertura: Informes de cobertura combinados con integración de Codecov
  • Pruebas de rendimiento: Medición del tiempo de inicio y seguimiento de benchmarks

Resumen de cobertura de pruebas

Métricas de cobertura actuales:

  • Cobertura de TypeScript: Cobertura integral de la implementación del servidor MCP
  • Cobertura de Python: Operaciones principales y funcionalidad de CLI
  • Informes combinados: Análisis de cobertura unificado en ambos lenguajes
  • Seguimiento automatizado: Monitoreo de cobertura en tiempo real mediante Codecov

Comandos rápidos de prueba

# 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 completos de prueba

# 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

Informes y artefactos de prueba

Después de ejecutar las pruebas, hay informes detallados disponibles:

  • Cobertura de TypeScript: ./coverage/index.html
  • Cobertura de Python: ./smartsheet_ops/coverage/index.html
  • Cobertura combinada: ./coverage-combined/index.html
  • Artefactos de prueba: Disponibles en las ejecuciones del pipeline de CI/CD

Umbrales de calidad

El proyecto aplica estándares de calidad estrictos:

  • Cobertura de TypeScript: Mínimo del 60% (configurable por componente)
  • Cobertura de Python: 80% en general con informes línea por línea
  • Calidad del código: Reglas de ESLint, modo estricto de TypeScript, Black/Flake8 de Python
  • Seguridad: Auditorías periódicas de dependencias y escaneo de vulnerabilidades
  • Rendimiento: Monitoreo del tiempo de inicio y detección de regresiones

Soporte de Docker

Compila y ejecuta la versión contenerizada:

# 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

Depuración

Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser un desafío. El servidor implementa un registro de errores integral y proporciona mensajes de error detallados a través del protocolo MCP.

Características clave de depuración:

  • Registro de errores en stderr
  • Mensajes de error detallados en las respuestas de MCP
  • Validación de tipos en múltiples niveles
  • Informes completos de resultados de operaciones
  • Análisis de dependencias para operaciones de columnas
  • Seguimiento de referencias de fórmulas

Manejo de errores

El servidor implementa un enfoque de manejo de errores en múltiples capas:

  1. Capa MCP

    • Valida los parámetros de las herramientas
    • Maneja errores a nivel de protocolo
    • Proporciona respuestas de error formateadas
    • Gestiona tiempos de espera y reintentos

  2. Capa CLI

    • Valida los argumentos de los comandos
    • Maneja errores de ejecución
    • Formatea mensajes de error como JSON
    • Valida operaciones de columnas

  3. Capa de operaciones

    • Maneja errores de la API de Smartsheet
    • Valida tipos de datos y formatos
    • Proporciona contexto de error detallado
    • Gestiona dependencias de columnas
    • Valida referencias de fórmulas
    • Garantiza la integridad de los datos

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, asegúrate de:

  1. Que el código de TypeScript/Python siga el estilo existente
  2. Que las nuevas funciones incluyan un manejo de errores adecuado
  3. Que los cambios mantengan la compatibilidad con versiones anteriores
  4. Que las actualizaciones incluyan documentación adecuada
  5. Que las operaciones de columnas mantengan la integridad de los datos
  6. Que las referencias de fórmulas se manejen correctamente