MCP Datadog Server

Servidor MCP (Model Context Protocol) completo e robusto para integração com APIs do Datadog

Um servidor MCP de produção que oferece 351 tools para interagir com todas as APIs do Datadog através de LLMs, incluindo operações CRUD completas, tools curadas e ferramentas geradas automaticamente do schema.

🚀 Características Principais

📊 Tools Disponíveis (351 total)

9 Tools Curadas 🎯 - Handcrafted, otimizadas para casos específicos
25 Tools CRUD ⚡ - Operações CREATE, READ, UPDATE, DELETE para recursos principais
319 Tools Geradas 🔧 - Geradas automaticamente do schema oficial do Datadog

🔍 Recursos Avançados

✅ Autodescoberta de Schema - LLMs descobrem parâmetros automaticamente
✅ Validação Robusta - Zod schemas com validação completa
✅ Progress Tracking - Acompanhamento em tempo real para operações longas
✅ Error Handling - Tratamento inteligente de erros e retry automático
✅ CLI Rica - Interface completa para gestão e debugging

🛡️ Conformidade MCP

✅ 100% Compatível com TypeScript SDK oficial
✅ JSON Schema completo para todas as tools
✅ Metadata Annotations detalhadas
✅ Type Safety com validação Zod

📦 Instalação

Requisitos

Node.js 18+
Chaves de API do Datadog (API Key + Application Key)

Instalação via npm

npm install -g mcp-datadog-server

Instalação Local

git clone https://github.com/ClaudioLazaro/mcp-datadog-server.git
cd mcp-datadog-server
npm install

⚙️ Configuração

1. Variáveis de Ambiente

Obrigatórias

DD_API_KEY=your_api_key         # Chave da API Datadog
DD_APP_KEY=your_app_key         # Chave da aplicação Datadog

Opcionais

DD_SITE=datadoghq.com           # Site Datadog (padrão: datadoghq.com)
DD_SUBDOMAIN=api                # Subdomínio (padrão: api)
MCP_DD_FOLDERS=Dashboards,Logs  # Categorias permitidas (padrão: todas)
MCP_DD_SCHEMA_PATH=./schema.json # Caminho do schema (padrão: incluído)
MCP_DD_MAX_RETRIES=3            # Máximo de tentativas (padrão: 3)
MCP_DD_RETRY_BASE_MS=1000       # Base para retry em ms (padrão: 1000)
MCP_DD_TIMEOUT_MS=30000         # Timeout das requisições (padrão: 30000)
MCP_DD_USER_AGENT=mcp-datadog   # User agent customizado

2. Arquivo .env (Recomendado)

# .env
DD_SITE=\"us3.datadoghq.com\"
DD_API_KEY=\"xxxxxxxxxxxxxxxxxxxxxxxx\"
DD_APP_KEY=\"xxxxxxxxxxxxxxxxxxxxxxxxxxxx\"
MCP_DD_FOLDERS=\"Dashboards,Monitors,Logs\"

3. Sites Datadog Suportados

datadoghq.com (US1)
datadoghq.eu (EU)
us3.datadoghq.com (US3)
us5.datadoghq.com (US5)
ap1.datadoghq.com (AP1)
ddog-gov.com (US Gov)

🎮 Uso

Servidor MCP (Padrão)

# Iniciar servidor MCP
mcp-datadog-server serve
# ou
npm start

# Com filtros
mcp-datadog-server serve --folders=Dashboards,Monitors

Interface CLI

Listar Tools

# Lista básica
mcp-datadog-server list-tools

# Lista detalhada ordenada
mcp-datadog-server list-tools --detailed

# JSON output
mcp-datadog-server list-tools --json

Inspeção de Tools

# Ver detalhes de uma tool
mcp-datadog-server get-tool create_monitor

# Ver schema completo de uma tool
mcp-datadog-server show-schema create_monitor

# JSON output
mcp-datadog-server show-schema create_monitor --json

Validação e Análise

# Validar configuração
mcp-datadog-server validate

# Analisar schema da API
mcp-datadog-server analyze-schema

# Ajuda
mcp-datadog-server help

🔧 Tools CRUD Disponíveis

⚡ Monitors (5 operações)

create_monitor    # Criar novo monitor
get_monitor       # Obter monitor por ID
update_monitor    # Atualizar monitor existente
delete_monitor    # Deletar monitor
list_monitor      # Listar todos os monitors

📊 Dashboards (5 operações)

create_dashboard  # Criar novo dashboard
get_dashboard     # Obter dashboard por ID
update_dashboard  # Atualizar dashboard existente
delete_dashboard  # Deletar dashboard
list_dashboard    # Listar todos os dashboards

⏰ Downtimes (5 operações)

create_downtime   # Agendar downtime
get_downtime      # Obter downtime por ID
update_downtime   # Atualizar downtime
delete_downtime   # Cancelar downtime
list_downtime     # Listar todos os downtimes

👥 Users (5 operações)

create_user       # Criar usuário
get_user          # Obter usuário por ID
update_user       # Atualizar usuário
delete_user       # Deletar usuário
list_user         # Listar todos os usuários

🏗️ Teams (5 operações)

create_team       # Criar equipe
get_team          # Obter equipe por ID
update_team       # Atualizar equipe
delete_team       # Deletar equipe
list_team         # Listar todas as equipes

📋 Como o LLM Descobre os Parâmetros

🔍 Autodescoberta Automática

O LLM NÃO precisa saber os parâmetros antecipadamente. Através do protocolo MCP, ele:

Lista todas as tools disponíveis
Obtém o schema JSON Schema completo de cada tool
Entende todos os parâmetros, tipos e validações
Constrói chamadas válidas automaticamente

📄 Schema Exemplo - create_monitor

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Monitor name"
    },
    "type": {
      "type": "string",
      "enum": ["metric alert", "service check", "event alert", "query alert", "composite", "log alert"],
      "description": "Monitor type"
    },
    "query": {
      "type": "string",
      "description": "Monitor query"
    },
    "message": {
      "type": "string",
      "description": "Notification message"
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Monitor tags"
    },
    "priority": {
      "type": "number",
      "minimum": 1,
      "maximum": 5,
      "description": "Priority (1-5)"
    },
    "options": {
      "type": "object",
      "properties": {
        "thresholds": {
          "type": "object",
          "properties": {
            "critical": {"type": "number"},
            "warning": {"type": "number"},
            "ok": {"type": "number"}
          }
        },
        "notify_audit": {"type": "boolean"},
        "require_full_window": {"type": "boolean"}
      }
    }
  },
  "required": ["name", "type", "query"]
}

🎯 Exemplo de Uso pelo LLM

Input do usuário:

"Create a monitor to alert when CPU usage is above 90%"

Chamada automática do LLM:

await use_tool("create_monitor", {
  "name": "High CPU Usage Alert",
  "type": "metric alert",
  "query": "avg(last_5m):avg:system.cpu.user{*} > 0.9",
  "message": "CPU usage is high! Please investigate @ops-team",
  "tags": ["alert", "cpu", "infrastructure"],
  "priority": 3,
  "options": {
    "thresholds": {
      "critical": 0.9,
      "warning": 0.8
    },
    "notify_audit": true,
    "require_full_window": false
  }
})

O LLM automaticamente:

✅ Descobriu todos os parâmetros disponíveis
✅ Preencheu campos obrigatórios (name, type, query)
✅ Adicionou campos opcionais relevantes
✅ Estruturou objetos complexos (options.thresholds)
✅ Validou tipos e constraints

🎯 Tools Curadas Especiais

🎯 Dashboards

list_dashboards   # Lista com filtros avançados e paginação

🎯 Logs

search_logs       # Busca avançada de logs com filtros

🎯 Metrics

query_metrics     # Query de métricas timeseries

🎯 Incidents

manage_incidents  # Gerenciamento completo de incidentes

🎯 Synthetics

manage_synthetics # Testes sintéticos completos

🏗️ Integração com LLMs

Claude Desktop (Recomendado)

Adicione ao arquivo de configuração do Claude:

{
  "mcpServers": {
    "datadog": {
      "command": "mcp-datadog-server",
      "args": ["serve"],
      "env": {
        "DD_API_KEY": "your_api_key",
        "DD_APP_KEY": "your_app_key",
        "DD_SITE": "datadoghq.com"
      }
    }
  }
}

Via npx (Global)

{
  "mcpServers": {
    "datadog": {
      "command": "npx",
      "args": ["-y", "mcp-datadog-server", "serve"],
      "env": {
        "DD_API_KEY": "your_api_key",
        "DD_APP_KEY": "your_app_key"
      }
    }
  }
}

Local Development

{
  "mcpServers": {
    "datadog": {
      "command": "node",
      "args": ["/path/to/mcp-datadog-server/src/index.js", "serve"],
      "env": {
        "DD_API_KEY": "your_api_key",
        "DD_APP_KEY": "your_app_key"
      }
    }
  }
}

🛠️ Desenvolvimento

Scripts Disponíveis

npm test              # Executar testes
npm run serve         # Iniciar servidor
npm run list-tools    # Listar tools
npm run validate      # Validar configuração
npm run analyze-schema # Analisar schema da API

Makefile

make install          # Instalar dependências
make start           # Iniciar servidor
make test            # Executar testes
make list-tools      # Listar tools
make validate        # Validar configuração

Estrutura do Projeto

src/
├── index.js                    # CLI principal
├── server.js                   # Servidor MCP principal
├── core/
│   ├── config.js              # Sistema de configuração
│   ├── http-client.js         # Cliente HTTP com retry
│   ├── schema-parser.js       # Parser do schema Datadog
│   └── validation.js          # Validações robustas
└── tools/
    ├── core-tools.js          # Ferramentas base
    ├── curated-tools.js       # Tools curadas otimizadas
    └── crud-tools.js          # Tools CRUD automáticas

🔍 Debugging e Troubleshooting

Verificar Tools Carregadas

# Ver resumo
mcp-datadog-server list-tools

# Ver lista completa ordenada
mcp-datadog-server list-tools --detailed

# Ver schema de uma tool específica
mcp-datadog-server show-schema create_monitor

Validar Configuração

# Validar tudo
mcp-datadog-server validate

# Ver configuração resumida
mcp-datadog-server validate --json

Testar Conectividade

# Analisar schema carregado
mcp-datadog-server analyze-schema

# Testar servidor básico
timeout 5s mcp-datadog-server serve

Logs e Debugging

# O servidor gera logs estruturados:
[2025-01-20T10:30:00.000Z] [INFO] Starting server with config: {...}
[2025-01-20T10:30:01.000Z] [INFO] Registered 9 curated tools
[2025-01-20T10:30:02.000Z] [INFO] Registered 25 CRUD tools
[2025-01-20T10:30:03.000Z] [INFO] Registered 319 generated tools
[2025-01-20T10:30:04.000Z] [INFO] Registered 351 tools total

🚨 Solução de Problemas Comuns

1. "Tool não encontrada"

# Verificar se a tool existe
mcp-datadog-server list-tools --detailed | grep nome_da_tool

# Ver todas as categorias disponíveis
mcp-datadog-server analyze-schema

2. "API Key inválida"

# Validar credenciais
mcp-datadog-server validate

# Verificar variáveis de ambiente
echo $DD_API_KEY
echo $DD_APP_KEY

3. "Schema não carregado"

# Verificar se o schema existe
mcp-datadog-server analyze-schema

# Forçar recarregamento
rm -f datadog-api-collection-schema.json
mcp-datadog-server serve

4. "Muitas tools carregadas"

# Filtrar apenas categorias necessárias
export MCP_DD_FOLDERS="Dashboards,Monitors,Logs"
mcp-datadog-server list-tools

📈 Performance e Limites

Rate Limiting

✅ Automático - Respeita headers retry-after
✅ Configurável - Ajuste via MCP_DD_MAX_RETRIES
✅ Inteligente - Backoff exponencial

Timeouts

✅ Padrão: 30 segundos por requisição
✅ Configurável via MCP_DD_TIMEOUT_MS
✅ Progress Tracking para operações longas

Memory Usage

✅ Otimizado - Schema carregado uma vez na inicialização
✅ Streaming - Não mantém responses grandes em memória
✅ Filtros - Use MCP_DD_FOLDERS para reduzir footprint

🔐 Segurança

Credentials

✅ Environment Only - Chaves apenas via variáveis de ambiente
✅ No Logging - Credentials nunca aparecem em logs
✅ Validation - Formato das chaves validado na inicialização

Network

✅ TLS Only - Todas as chamadas via HTTPS
✅ Corporate Proxy - Suporte via NODE_EXTRA_CA_CERTS
✅ Headers Security - User-Agent e headers apropriados

Input Validation

✅ Zod Schemas - Validação rigorosa de entrada
✅ Sanitization - Limpeza automática de inputs
✅ Type Safety - TypeScript + runtime validation

📊 Monitoramento

Health Checks

# Status do servidor
mcp-datadog-server validate

# Análise das tools
mcp-datadog-server list-tools --json | jq '.total'

Metrics Disponíveis

✅ Tools Count - Total de tools carregadas
✅ API Calls - Tracking de chamadas por tool
✅ Error Rate - Rate de erros por categoria
✅ Response Time - Tempos de resposta médios

🎓 Exemplos Práticos

Criar Monitor de CPU

O LLM pode automaticamente executar:

await use_tool("create_monitor", {
  name: "High CPU Alert",
  type: "metric alert",
  query: "avg(last_5m):avg:system.cpu.user{*} > 0.9",
  message: "CPU high @ops-team"
});

Listar Dashboards Filtrados

await use_tool("list_dashboard", {
  filter_shared: false,
  count: 50
});

Criar Downtime para Manutenção

await use_tool("create_downtime", {
  scope: ["host:web-server-01"],
  start: Math.floor(Date.now() / 1000),
  end: Math.floor(Date.now() / 1000) + 3600,
  message: "Planned maintenance window"
});

📚 Documentação Adicional

🔍 SCHEMA_DISCOVERY.md - Como o LLM descobre parâmetros
📋 REFACTOR_CHECKPOINT.md - Histórico da refatoração
⚙️ TOOLS.md - Documentação completa das tools

🤝 Contribuição

Reportar Bugs

# Gerar relatório de debug
mcp-datadog-server validate --json > debug-info.json
mcp-datadog-server list-tools --json >> debug-info.json

Adicionar Tools Curadas

Edite src/tools/curated-tools.js
Adicione schema Zod completo
Implemente função execute
Teste com npm test

Melhorar Tools CRUD

Edite src/tools/crud-tools.js
Adicione novos recursos ao DATADOG_RESOURCES
Defina schemas e operações
Teste todas as operações CRUD

📝 Changelog

v0.3.0 - Current

✅ 351 tools (9 curadas + 25 CRUD + 319 geradas)
✅ CRUD completo para recursos principais
✅ Schema autodescoberta via MCP
✅ Progress tracking para operações longas
✅ CLI rica com comandos de debugging
✅ 100% conformidade com padrões MCP

v0.2.x - Previous

✅ Refatoração completa da arquitetura
✅ Validação robusta com Zod
✅ Cliente HTTP com retry automático
✅ Sistema de configuração limpo

📄 Licença

Apache License 2.0 - Veja LICENSE para detalhes.

🙏 Agradecimentos

Model Context Protocol - Framework base
Datadog - APIs e documentação
Zod - Schema validation
Undici - HTTP client

🎉 Pronto para usar com qualquer LLM compatível com MCP!

Para suporte e discussões, veja as Issues do repositório.