Tideways MCP Server

Permite a los asistentes de IA consultar datos de monitoreo de rendimiento de Tideways y proporcionar información conversacional sobre el rendimiento.

GitHub

Documentación

Servidor MCP de Tideways

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA consultar datos de monitoreo de rendimiento de Tideways y proporcionar información conversacional sobre el rendimiento de aplicaciones PHP.

Acerca de Tideways: Tideways es una plataforma de monitoreo de rendimiento de aplicaciones (APM) diseñada específicamente para aplicaciones PHP. Para detalles técnicos, consulte la documentación de la API REST.

Bifurcado de abuhamza/tideways-mcp-server por Mouhammed Diop.

Características

Información de rendimiento conversacional: Obtenga datos de rendimiento en formato de lenguaje natural optimizado para asistentes de IA
Integración con asistentes de IA: Funciona con Claude Desktop, Cursor, Claude Code y otras herramientas compatibles con MCP
Métricas de rendimiento en tiempo real: Consulte datos de rendimiento actuales con límite de velocidad configurable
Análisis de trazas: Liste y filtre trazas con desglose por capas, detección de cuellos de botella y análisis de tiempo de respuesta
Análisis de problemas: Recupere y analice errores, excepciones y problemas de rendimiento
Manejo robusto de errores: Manejo integral de errores con mensajes fáciles de usar

Repositorio: 5hahiL/tideways-mcp-server Licencia: MIT

Requisitos previos

Cuenta de Tideways con un token de API válido
Token de API con los alcances apropiados (metrics, issues, traces) - consulte la documentación de la API
Acceso a una organización y proyecto de Tideways

Configuración de integración con IA

Este es un servidor MCP (Protocolo de Contexto de Modelo) diseñado exclusivamente para asistentes de IA. No se puede utilizar como una herramienta CLI independiente.

El servidor se integra con asistentes de IA a través de la configuración de MCP utilizando el paquete npm tideways-mcp.

Variables de entorno

Variable	Requerida	Predeterminado	Descripción
`TIDEWAYS_TOKEN`	✅	-	Token de acceso a la API de Tideways (consulte la sección de Seguridad)
`TIDEWAYS_ORG`	✅	-	Nombre de la organización de Tideways
`TIDEWAYS_PROJECT`	✅	-	Nombre del proyecto de Tideways
`TIDEWAYS_BASE_URL`	❌	`https://app.tideways.io/apps/api`	URL base de la API de Tideways
`TIDEWAYS_RATE_LIMIT`	❌	`2500`	Solicitudes de API por hora — ajústelo a su plan (Team/Pro: 2500, Standard: 1000, Basic: 250)
`TIDEWAYS_MAX_RETRIES`	❌	`3`	Número máximo de reintentos de API
`TIDEWAYS_REQUEST_TIMEOUT`	❌	`30000`	Tiempo de espera de solicitudes de API (ms)
`LOG_LEVEL`	❌	`info`	Nivel de registro (debug, info, warn, error)

Integración con asistentes de IA

Este servidor solo funciona con asistentes de IA compatibles con MCP. Utiliza transporte stdio.

Claude Desktop

Agregue a su archivo de configuración MCP de Claude Desktop:

Ubicación:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

Configuración (Recomendada - usando npx):

{
  "mcpServers": {
    "tideways": {
      "command": "npx",
      "args": ["tideways-mcp"],
      "env": {
        "TIDEWAYS_TOKEN": "your_token",
        "TIDEWAYS_ORG": "your_org",
        "TIDEWAYS_PROJECT": "your_project"
      }
    }
  }
}

Alternativa (si está instalado globalmente):

{
  "mcpServers": {
    "tideways": {
      "command": "tideways-mcp",
      "env": {
        "TIDEWAYS_TOKEN": "your_token",
        "TIDEWAYS_ORG": "your_org",
        "TIDEWAYS_PROJECT": "your_project"
      }
    }
  }
}

IDE Cursor

Cursor admite MCP a través de su configuración. Agregue la configuración del servidor en la configuración de MCP de Cursor:

Abra la Configuración de Cursor
Herramientas e Integración
Agregue un nuevo servidor con:

{
  "mcpServers": {
    "tideways": {
      "command": "tideways-mcp",
      "env": {
        "TIDEWAYS_TOKEN": "your_token",
        "TIDEWAYS_ORG": "your_org",
        "TIDEWAYS_PROJECT": "your_project"
      }
    }
  }
}

VS Code con extensión MCP

Si usa VS Code con una extensión compatible con MCP:

{
  "mcp.servers": {
    "tideways": {
      "command": "npx",
      "args": ["tideways-mcp"],
      "env": {
        "TIDEWAYS_TOKEN": "your_token",
        "TIDEWAYS_ORG": "your_org",
        "TIDEWAYS_PROJECT": "your_project"
      }
    }
  }
}

Uso con asistentes de IA

Una vez configurado, puede hacer preguntas a su asistente de IA como:

Consultas básicas de rendimiento

"¿Cuál es el rendimiento actual de mi aplicación?"
"Muéstrame errores recientes en las últimas 24 horas"
"¿Cómo está funcionando mi API en comparación con ayer?"
"¿Cuáles son las transacciones más lentas en este momento?"

Análisis avanzado de trazas y optimización

"Analiza el endpoint /api/users/{id} e identifica cuellos de botella"
"Encuentra la causa raíz del rendimiento lento en mi proceso de pago"
"Detecta consultas N+1 en mi endpoint de listado de productos y sugiere correcciones"
"Analiza trazas para /dashboard y recomienda optimizaciones de código"
"Identifica cuellos de botella de consultas de base de datos en mi flujo de autenticación de usuarios"
"Encuentra fugas de memoria o rutas de código ineficientes en mis endpoints de API"
"Analiza la sobrecarga de inyección de dependencias en mi aplicación"
"Detecta llamadas redundantes a la base de datos y sugiere estrategias de caché"

Sugerencias de optimización de rendimiento

"Recomienda mejoras de rendimiento para mis endpoints más lentos"
"Analiza mis consultas SQL y sugiere estrategias de indexación"
"Identifica oportunidades para agrupación de consultas o carga diferida"
"Encuentra bucles ineficientes o llamadas recursivas en mis trazas"
"Sugiere refactorización de código basada en cuellos de botella de rendimiento"
"Analiza patrones de uso de memoria y recomienda optimizaciones"

Herramientas MCP disponibles

Todas las herramientas devuelven JSON sin procesar de la API de Tideways. El asistente de IA (Claude, Cursor, etc.) realiza el análisis e interpretación real de estos datos.

`get_performance_metrics`

Recupere métricas de rendimiento agregadas y estadísticas a nivel de sistema.

Parámetros:

ts (opcional): Marca de tiempo final en formato Y-m-d H:i (por ejemplo, "2025-08-12 18:30")
m (opcional): Número de minutos hacia atrás desde la marca de tiempo (por ejemplo, 60 para 1 hora, 1440 para 24 horas)
env (opcional): Filtrar por entorno específico
s (opcional): Filtrar por nombre de servicio específico

Ejemplos conversacionales:

"What's the current performance of my application?"
"Show me performance metrics for the last 6 hours"
"Get metrics for the API service in production"
"How is my web service performing in the staging environment?"
"Compare today's metrics with the last 24 hours"

Devuelve: Datos de rendimiento sin procesar de Tideways, incluidos tiempos de respuesta, rendimiento, tasas de error y desgloses de transacciones.

`get_performance_summary`

Recupere datos de resumen de rendimiento de series temporales en intervalos de 15 minutos para análisis de tendencias.

Parámetros:

s (opcional): Nombre del servicio para filtrar (por ejemplo, "web", "api", "worker"). Predeterminado: "web"

Ejemplos conversacionales:

"Show me performance trends over the last few hours"
"Get the performance summary for my API service"
"How has my web service been performing recently?"
"Display trends for the worker service"
"Show me response time patterns for today"

Devuelve: Datos de series temporales sin procesar con intervalos de 15 minutos que muestran tiempos de respuesta, recuentos de solicitudes y tasas de error.

`get_issues`

Recupere y analice errores recientes, excepciones y problemas de rendimiento.

Parámetros:

issue_type (opcional): "error", "slowsql", "deprecated", "all" (predeterminado: "all")
status (opcional): "open", "new", "resolved", "not_error", "ignored", "all" (predeterminado: "open")
page (opcional): Número de página para paginación (predeterminado: 1)

Ejemplos conversacionales:

"What errors are currently happening in my application?"
"Show me all open errors from the last 24 hours"
"Get slow SQL queries that need attention"
"Are there any new performance issues I should know about?"
"List all deprecated function calls in my code"
"Show me resolved errors to understand what was fixed"

Devuelve: Datos de problemas sin procesar de Tideways, incluidos tipos de error, recuentos de ocurrencias, endpoints afectados y seguimientos de pila cuando estén disponibles.

`get_traces`

Analice muestras de trazas individuales para identificación detallada de cuellos de botella y depuración de rendimiento.

Parámetros:

env (opcional): Nombre del entorno (por ejemplo, "production", "staging")
s (opcional): Nombre del servicio (por ejemplo, "web", "api", "worker")
transaction_name (opcional): Filtrar por nombre de transacción/endpoint específico
has_callgraph (opcional): Solo devolver trazas con datos detallados de callgraph
search (opcional): Búsqueda basada en palabras en transaction_name, host y URL
min_date (opcional): Fecha mínima en formato YYYY-MM-DD HH:MM (requiere max_date)
max_date (opcional): Fecha máxima en formato YYYY-MM-DD HH:MM (requiere min_date)
min_response_time_ms (opcional): Filtro de tiempo de respuesta mínimo
max_response_time_ms (opcional): Filtro de tiempo de respuesta máximo
sort_by (opcional): "response_time", "date", "memory" (predeterminado: "response_time")
sort_order (opcional): "ASC", "DESC" (predeterminado: "DESC")

Ejemplos conversacionales:

"Analyze traces for the /api/products endpoint and find bottlenecks"
"Show me the slowest requests from the last hour with details"
"Find traces with callgraph data for the checkout process"
"What's causing slow response times in my user registration flow?"
"Detect N+1 query problems in my product listing page"
"Analyze memory usage patterns in my API endpoints"
"Find database bottlenecks in the /dashboard endpoint"
"Show me traces where response time is over 2 seconds"

Devuelve: Datos de trazas sin procesar de Tideways, incluidos tiempos por solicitud, desglose por capas (SQL, Redis, HTTP, etc.), indicadores de cuellos de botella y datos de callgraph cuando has_callgraph: true está configurado. Use has_callgraph: true para el mayor detalle de depuración.

`get_historical_data`

Recupere datos históricos de rendimiento para fechas específicas con granularidad configurable.

Parámetros:

date (requerido): Fecha en formato YYYY-MM-DD
granularity (opcional): "day", "week", "month" (predeterminado: "day")

Ejemplos conversacionales:

"Get historical performance data for August 1st, 2025"
"Show me weekly performance trends for last Monday"
"Compare this month's performance with last month"
"How did my application perform on 2025-07-15?"
"Get daily performance data for the past week"
"Show me monthly trends for the last quarter"

Devuelve: Datos históricos de rendimiento sin procesar de Tideways para la fecha y granularidad especificadas.

Desarrollo

Estructura del proyecto

├── src/
│   ├── config/           # Configuration management
│   ├── lib/              # Core libraries
│   │   ├── errors.ts     # Error handling utilities
│   │   ├── logger.ts     # Structured logging
│   │   └── tideways-client.ts  # Tideways API client
│   ├── tools/            # MCP tool implementations
│   │   ├── definitions.ts # Tool schema definitions
│   │   ├── registry.ts   # Tool execution registry
│   │   └── handlers/     # Individual tool handlers
│   ├── types/            # TypeScript type definitions
│   ├── utils/            # Utility functions
│   ├── server.ts         # Main MCP server implementation
│   └── index.ts          # Application entry point
├── tests/                # Test suites
└── dist/                 # Compiled JavaScript (generated)

Ejecución de pruebas

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run type checking
npm run typecheck

Compilación

# Build TypeScript to JavaScript
npm run build

# Clean build artifacts
npm run clean

Calidad del código

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

Arquitectura

Componentes principales

Servidor MCP (src/server.ts): Servidor principal que implementa el protocolo MCP, maneja definiciones de herramientas y enrutamiento
Cliente de API de Tideways (src/lib/tideways-client.ts): Cliente HTTP con límite de velocidad, lógica de reintentos y medidas de seguridad
Registro de herramientas (src/tools/): Sistema de herramientas modular con manejadores individuales para cada herramienta MCP
Manejador de errores (src/lib/errors.ts): Manejo centralizado de errores con mensajes fáciles de usar
Registrador (src/lib/logger.ts): Registro JSON estructurado para monitoreo y depuración
Configuración (src/config/index.ts): Gestión de configuración basada en entorno

Flujo de datos

AI Assistant ←→ MCP Protocol (stdio) ←→ TidewaysMCPServer → TidewaysClient → Tideways API
                                               ↓
                                        Raw JSON Response → AI Assistant

Filosofía de formato de respuesta

Este servidor utiliza un enfoque JSON sin procesar para un rendimiento óptimo:

Canalización directa de API a LLM: Las herramientas devuelven JSON.stringify(apiData, null, 2) sin formato
Cero sobrecarga de procesamiento: Sin lógica compleja de formato, caché o interpretación
Preservación completa de datos: El LLM recibe todos los datos disponibles para un análisis flexible
Mantenimiento mínimo: Sin lógica de formato o caché que mantener o depurar

Estrategia de límite de velocidad

Limitador de velocidad configurable: Establezca TIDEWAYS_RATE_LIMIT para que coincida con su plan de Tideways (predeterminado: 2500/hora)
Llamadas directas a la API: Todas las solicitudes van directamente a la API de Tideways sin capa de caché
Lógica de reintentos: Reintentos automáticos para fallos transitorios con retroceso exponencial

🛡️ Seguridad

Los tokens de API se almacenan de forma segura en variables de entorno
Los encabezados de autorización se redactan automáticamente en los registros como Bearer [REDACTED]
Límite de velocidad para respetar las restricciones de la API de Tideways
Validación de entrada en todos los parámetros de funciones MCP
No se registran ni exponen datos sensibles en mensajes de error
Escaneo de seguridad automatizado: CodeQL, Snyk, TruffleHog, GitLeaks

📊 Monitoreo

El servidor proporciona registros JSON estructurados para monitoreo:

{
  "timestamp": "2025-08-09T10:00:00.000Z",
  "level": "info",
  "message": "Tool called",
  "context": {
    "toolName": "get_performance_metrics",
    "arguments": {"time_range": "24h"}
  }
}

🔧 Solución de problemas

Problemas comunes

Error de autenticación

Error: Authentication failed. Please check your API token.

Verifique que TIDEWAYS_TOKEN sea correcto y tenga los alcances requeridos (metrics, issues, traces)
Compruebe que el token no haya expirado
Asegúrese de que los nombres de organización y proyecto sean correctos

Límite de velocidad excedido

Error: Rate limit exceeded. Please try again later.

Establezca TIDEWAYS_RATE_LIMIT para que coincida con el límite real de su plan
Espere el restablecimiento del límite de velocidad (se muestra en el mensaje de error)
El límite de velocidad integrado respeta su límite configurado

Problemas de conexión

Error: Network error: Unable to connect to Tideways API.

Verifique la conexión a internet
Confirme que la API de Tideways sea accesible desde su red
Compruebe si el firewall corporativo bloquea el acceso a la API en app.tideways.io
Pruebe con curl: curl -H "Authorization: Bearer YOUR_TOKEN" https://app.tideways.io/apps/api/_token

Problemas de integración MCP

Error: MCP server not responding or connection failed

Reinicie su asistente de IA (Claude Desktop, Cursor, etc.)
Verifique que la sintaxis del archivo de configuración MCP sea correcta
Compruebe que la ruta del comando del servidor sea correcta
Asegúrese de que las variables de entorno estén configuradas correctamente en la configuración de MCP
Intente ejecutar el servidor manualmente primero: npx tideways-mcp

Modo de depuración

Habilite el registro de depuración para solución de problemas detallada:

# When running directly
LOG_LEVEL=debug npx tideways-mcp

# In MCP configuration, add to env:
{
  "env": {
    "LOG_LEVEL": "debug",
    "TIDEWAYS_TOKEN": "your_token",
    ...
  }
}

Obtener ayuda

Revise los registros: El modo de depuración proporciona información detallada sobre solicitudes y respuestas
Verifique la configuración: Revise todas las variables de entorno y la configuración de MCP
Pruebe el acceso a la API: Use curl para verificar que sus credenciales de la API de Tideways funcionen
Reporte problemas: Problemas de GitHub con registros de depuración y detalles de configuración

Contribuciones

¡Las contribuciones son bienvenidas!

Cree una rama de características: git checkout -b your-feature
Haga cambios y agregue pruebas: npm test
Envíe una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulte el archivo LICENSE para más detalles.