Tideways MCP Server

Permite que assistentes de IA consultem dados de monitoramento de desempenho do Tideways e forneçam insights de desempenho conversacionais.

GitHub
3

Documentação

Tideways MCP Server

CI/CD Pipeline Release Security Pipeline npm version npm downloads

Um servidor Model Context Protocol (MCP) que permite que assistentes de IA consultem dados de monitoramento de desempenho do Tideways e forneçam insights conversacionais de desempenho para aplicações PHP.

Sobre o Tideways: Tideways é uma plataforma poderosa de monitoramento de desempenho de aplicações (APM) projetada especificamente para aplicações PHP. Para detalhes técnicos, consulte a documentação da API REST.

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

Recursos

  • Insights Conversacionais de Desempenho: Obtenha dados de desempenho em formato de linguagem natural otimizado para assistentes de IA
  • Integração com Assistentes de IA: Funciona com Claude Desktop, Cursor, Claude Code e outras ferramentas compatíveis com MCP
  • Métricas de Desempenho em Tempo Real: Consulte dados de desempenho atuais com limite de taxa configurável
  • Análise de Traces: Liste e filtre traces com detalhamento por camada, detecção de gargalos e análise de tempo de resposta
  • Análise de Problemas: Recupere e analise erros, exceções e problemas de desempenho
  • Tratamento Robusto de Erros: Tratamento abrangente de erros com mensagens amigáveis ao usuário

Repositório: 5hahiL/tideways-mcp-server Licença: MIT

Pré-requisitos

  • Conta Tideways com um token de API válido
  • Token de API com escopos apropriados (metrics, issues, traces) - consulte a documentação da API
  • Acesso a uma organização e projeto Tideways

Configuração de Integração com IA

Este é um servidor MCP (Model Context Protocol) projetado exclusivamente para assistentes de IA. Não pode ser usado como uma ferramenta CLI independente.

O servidor integra-se com assistentes de IA através da configuração MCP usando o pacote npm tideways-mcp.

Variáveis de Ambiente

VariávelObrigatóriaPadrãoDescrição
TIDEWAYS_TOKEN✅-Token de acesso à API Tideways (consulte a seção Segurança)
TIDEWAYS_ORG✅-Nome da organização Tideways
TIDEWAYS_PROJECT✅-Nome do projeto Tideways
TIDEWAYS_BASE_URL❌https://app.tideways.io/apps/apiURL base da API Tideways
TIDEWAYS_RATE_LIMIT❌2500Requisições de API por hora — ajuste ao seu plano (Team/Pro: 2500, Standard: 1000, Basic: 250)
TIDEWAYS_MAX_RETRIES❌3Número máximo de tentativas de nova chamada à API
TIDEWAYS_REQUEST_TIMEOUT❌30000Tempo limite de requisição à API (ms)
LOG_LEVEL❌infoNível de log (debug, info, warn, error)

Integração com Assistentes de IA

Este servidor funciona apenas com assistentes de IA compatíveis com MCP. Ele usa transporte stdio.

Claude Desktop

Adicione ao seu arquivo de configuração MCP do Claude Desktop:

Localização:

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

Configuração (Recomendada - usando npx):

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

Alternativa (se instalado globalmente):

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

Cursor IDE

O Cursor suporta MCP através de suas configurações. Adicione a configuração do servidor nas configurações MCP do Cursor:

  1. Abra as Configurações do Cursor
  2. Ferramentas e Integração
  3. Adicione um novo servidor com:
{
  "mcpServers": {
    "tideways": {
      "command": "tideways-mcp",
      "env": {
        "TIDEWAYS_TOKEN": "your_token",
        "TIDEWAYS_ORG": "your_org",
        "TIDEWAYS_PROJECT": "your_project"
      }
    }
  }
}

VS Code com Extensão MCP

Se estiver usando VS Code com uma extensão compatível com MCP:

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

Usando com Assistentes de IA

Uma vez configurado, você pode fazer perguntas ao seu assistente de IA como:

Consultas Básicas de Desempenho

  • "Qual é o desempenho atual da minha aplicação?"
  • "Mostre-me erros recentes nas últimas 24 horas"
  • "Como está minha API em comparação com ontem?"
  • "Quais são as transações mais lentas agora?"

Análise Avançada de Traces e Otimização

  • "Analise o endpoint /api/users/{id} e identifique gargalos"
  • "Encontre a causa raiz do desempenho lento no meu processo de checkout"
  • "Detecte consultas N+1 no meu endpoint de listagem de produtos e sugira correções"
  • "Analise traces para /dashboard e recomende otimizações de código"
  • "Identifique gargalos de consultas de banco de dados no meu fluxo de autenticação de usuário"
  • "Encontre vazamentos de memória ou caminhos de código ineficientes nos meus endpoints de API"
  • "Analise a sobrecarga de injeção de dependência na minha aplicação"
  • "Detecte chamadas redundantes ao banco de dados e sugira estratégias de cache"

Sugestões de Otimização de Desempenho

  • "Recomende melhorias de desempenho para meus endpoints mais lentos"
  • "Analise minhas consultas SQL e sugira estratégias de indexação"
  • "Identifique oportunidades para agrupamento de consultas ou carregamento preguiçoso"
  • "Encontre loops ineficientes ou chamadas recursivas nos meus traces"
  • "Sugira refatoração de código com base em gargalos de desempenho"
  • "Analise padrões de uso de memória e recomende otimizações"

Ferramentas MCP Disponíveis

Todas as ferramentas retornam JSON bruto da API Tideways. O assistente de IA (Claude, Cursor, etc.) realiza a análise e interpretação real desses dados.

get_performance_metrics

Recupere métricas agregadas de desempenho e estatísticas gerais do sistema.

Parâmetros:

  • ts (opcional): Timestamp final no formato Y-m-d H:i (ex.: "2025-08-12 18:30")
  • m (opcional): Número de minutos retroativos a partir do timestamp (ex.: 60 para 1 hora, 1440 para 24 horas)
  • env (opcional): Filtrar por ambiente específico
  • s (opcional): Filtrar por nome de serviço específico

Exemplos Conversacionais:

"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"

Retorna: Dados brutos de desempenho do Tideways, incluindo tempos de resposta, throughput, taxas de erro e detalhamentos de transações.

get_performance_summary

Recupere dados resumidos de desempenho em séries temporais em intervalos de 15 minutos para análise de tendências.

Parâmetros:

  • s (opcional): Nome do serviço para filtrar (ex.: "web", "api", "worker"). Padrão: "web"

Exemplos Conversacionais:

"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"

Retorna: Dados brutos de séries temporais com intervalos de 15 minutos mostrando tempos de resposta, contagens de requisições e taxas de erro.

get_issues

Recupere e analise erros recentes, exceções e problemas de desempenho.

Parâmetros:

  • issue_type (opcional): "error", "slowsql", "deprecated", "all" (padrão: "all")
  • status (opcional): "open", "new", "resolved", "not_error", "ignored", "all" (padrão: "open")
  • page (opcional): Número da página para paginação (padrão: 1)

Exemplos Conversacionais:

"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"

Retorna: Dados brutos de problemas do Tideways, incluindo tipos de erro, contagens de ocorrência, endpoints afetados e stack traces quando disponíveis.

get_traces

Analise amostras individuais de traces para identificação detalhada de gargalos e depuração de desempenho.

Parâmetros:

  • env (opcional): Nome do ambiente (ex.: "production", "staging")
  • s (opcional): Nome do serviço (ex.: "web", "api", "worker")
  • transaction_name (opcional): Filtrar por nome de transação/endpoint específico
  • has_callgraph (opcional): Retornar apenas traces com dados detalhados de callgraph
  • search (opcional): Busca baseada em palavras em transaction_name, host e URL
  • min_date (opcional): Data mínima no formato YYYY-MM-DD HH:MM (requer max_date)
  • max_date (opcional): Data máxima no formato YYYY-MM-DD HH:MM (requer min_date)
  • min_response_time_ms (opcional): Filtro de tempo de resposta mínimo
  • max_response_time_ms (opcional): Filtro de tempo de resposta máximo
  • sort_by (opcional): "response_time", "date", "memory" (padrão: "response_time")
  • sort_order (opcional): "ASC", "DESC" (padrão: "DESC")

Exemplos Conversacionais:

"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"

Retorna: Dados brutos de traces do Tideways, incluindo tempo por requisição, detalhamento por camada (SQL, Redis, HTTP, etc.), flags de gargalo e dados de callgraph quando has_callgraph: true está definido. Use has_callgraph: true para o nível mais profundo de detalhes de depuração.

get_historical_data

Recupere dados históricos de desempenho para datas específicas com granularidade configurável.

Parâmetros:

  • date (obrigatório): Data no formato YYYY-MM-DD
  • granularity (opcional): "day", "week", "month" (padrão: "day")

Exemplos Conversacionais:

"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"

Retorna: Dados brutos históricos de desempenho do Tideways para a data e granularidade especificadas.

Desenvolvimento

Estrutura do Projeto

├── 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)

Executando Testes

# 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

Compilação

# Build TypeScript to JavaScript
npm run build

# Clean build artifacts
npm run clean

Qualidade de Código

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

Arquitetura

Componentes Principais

  1. Servidor MCP (src/server.ts): Servidor principal que implementa o protocolo MCP, gerencia definições de ferramentas e roteamento
  2. Cliente da API Tideways (src/lib/tideways-client.ts): Cliente HTTP com limite de taxa, lógica de nova tentativa e medidas de segurança
  3. Registro de Ferramentas (src/tools/): Sistema modular de ferramentas com manipuladores individuais para cada ferramenta MCP
  4. Manipulador de Erros (src/lib/errors.ts): Tratamento centralizado de erros com mensagens amigáveis ao usuário
  5. Logger (src/lib/logger.ts): Logging JSON estruturado para monitoramento e depuração
  6. Configuração (src/config/index.ts): Gerenciamento de configuração baseado em ambiente

Fluxo de Dados

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

Filosofia de Formato de Resposta

Este servidor usa uma abordagem JSON bruta para desempenho ideal:

  • Pipeline Direto API-para-LLM: As ferramentas retornam JSON.stringify(apiData, null, 2) sem formatação
  • Zero Sobrecarga de Processamento: Sem lógica complexa de formatação, cache ou interpretação
  • Preservação Completa de Dados: O LLM recebe todos os dados disponíveis para análise flexível
  • Manutenção Mínima: Sem lógica de formatação ou cache para manter ou depurar

Estratégia de Limite de Taxa

  • Limitador de Taxa Configurável: Defina TIDEWAYS_RATE_LIMIT para corresponder ao seu plano Tideways (padrão: 2500/hora)
  • Chamadas Diretas à API: Todas as requisições vão diretamente para a API Tideways sem camada de cache
  • Lógica de Nova Tentativa: Novas tentativas automáticas para falhas transitórias com backoff exponencial

🛡️ Segurança

  • Tokens de API armazenados com segurança em variáveis de ambiente
  • Cabeçalhos de autorização automaticamente mascarados nos logs como Bearer [REDACTED]
  • Limite de taxa para respeitar as restrições da API Tideways
  • Validação de entrada em todos os parâmetros de funções MCP
  • Nenhum dado sensível é registrado ou exposto em mensagens de erro
  • Varredura automatizada de segurança: CodeQL, Snyk, TruffleHog, GitLeaks

📊 Monitoramento

O servidor fornece logs JSON estruturados para monitoramento:

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

🔧 Solução de Problemas

Problemas Comuns

Erro de Autenticação

Error: Authentication failed. Please check your API token.
  • Verifique se TIDEWAYS_TOKEN está correto e possui os escopos necessários (metrics, issues, traces)
  • Verifique se o token não expirou
  • Garanta que os nomes da organização e do projeto estejam corretos

Limite de Taxa Excedido

Error: Rate limit exceeded. Please try again later.
  • Defina TIDEWAYS_RATE_LIMIT para corresponder ao limite real do seu plano
  • Aguarde a redefinição do limite de taxa (mostrada na mensagem de erro)
  • O limite de taxa integrado respeita o limite configurado

Problemas de Conexão

Error: Network error: Unable to connect to Tideways API.
  • Verifique a conexão com a internet
  • Verifique se a API Tideways está acessível a partir da sua rede
  • Verifique se o firewall corporativo bloqueia o acesso à API em app.tideways.io
  • Teste com curl: curl -H "Authorization: Bearer YOUR_TOKEN" https://app.tideways.io/apps/api/_token

Problemas de Integração MCP

Error: MCP server not responding or connection failed
  • Reinicie seu assistente de IA (Claude Desktop, Cursor, etc.)
  • Verifique se a sintaxe do arquivo de configuração MCP está correta
  • Verifique se o caminho do comando do servidor está correto
  • Garanta que as variáveis de ambiente estejam configuradas corretamente na configuração MCP
  • Tente executar o servidor manualmente primeiro: npx tideways-mcp

Modo de Depuração

Ative o logging de depuração para solução de problemas detalhada:

# When running directly
LOG_LEVEL=debug npx tideways-mcp

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

Obtendo Ajuda

  1. Verifique os logs: O modo de depuração fornece informações detalhadas sobre requisições e respostas
  2. Verifique a configuração: Revise todas as variáveis de ambiente e configurações MCP
  3. Teste o acesso à API: Use curl para verificar se suas credenciais da API Tideways funcionam
  4. Reporte problemas: Issues no GitHub com logs de depuração e detalhes de configuração

Contribuindo

Contribuições são bem-vindas!

  1. Crie um branch de recurso: git checkout -b your-feature
  2. Faça alterações e adicione testes: npm test
  3. Envie um pull request

Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.