Mcp Datadog Server

MCP Datadog Server

用于与 Datadog API 集成的完整、稳健的 MCP（Model Context Protocol）服务

一款可用于生产环境的 MCP 服务，提供 351 个工具，可通过大模型与所有 Datadog API 交互，包括完整的 CRUD 操作、精选工具和根据 schema 自动生成的工具。

🚀 主要特点

📊 可用工具（共 351 个）

• 9 个精选工具 🎯 — 手工打造，针对特定场景进行了优化
• 25 个 CRUD 工具 ⚡ — 对主要资源执行 CREATE、READ、UPDATE、DELETE 操作
• 319 个自动生成的工具 🔧 — 根据 Datadog 官方 schema 自动生成

🔍 高级功能

• ✅ Schema 自动发现 — 大模型可自动发现参数
• ✅ 稳健的验证 — 使用 Zod schemas 进行完整验证
• ✅ 进度跟踪 — 实时跟踪长时间运行的操作
• ✅ 错误处理 — 智能错误处理和自动重试
• ✅ 丰富的 CLI — 提供完整的管理和调试界面

🛡️ MCP 合规性

• ✅ 100% 兼容官方 TypeScript SDK
• ✅ 所有工具均提供完整的 JSON Schema
• ✅ 详细的元数据注解
• ✅ 使用 Zod 验证确保类型安全

📦 安装

要求

• Node.js 18+
• Datadog API 密钥（API Key + Application Key）

通过 npm 安装

npm install -g mcp-datadog-server

本地安装

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

⚙️ 配置

1. 环境变量

必需

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

可选

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. .env 文件（推荐）

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

3. 支持的 Datadog 站点

• datadoghq.com（US1）
• datadoghq.eu（EU）
• us3.datadoghq.com（US3）
• us5.datadoghq.com（US5）
• ap1.datadoghq.com（AP1）
• ddog-gov.com（US Gov）

🎮 使用

MCP 服务（默认）

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

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

CLI 界面

列出工具

# 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

检查工具

# 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

验证与分析

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

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

# Ajuda
mcp-datadog-server help

🔧 可用的 CRUD 工具

⚡ 监控器（5 个操作）

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

📊 仪表板（5 个操作）

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

⏰ 停机时间（5 个操作）

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

👥 用户（5 个操作）

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

🏗️ 团队（5 个操作）

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

📋 大模型如何发现参数

🔍 自动发现

大模型无需提前了解参数。通过 MCP 协议，它可以：

1. 列出所有可用工具
2. 获取每个工具完整的 JSON Schema schema
3. 了解所有参数、类型和验证规则
4. 自动构建有效调用

📄 Schema 示例 — 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"]
}

🎯 大模型使用示例

用户输入：

“创建一个监控器，在 CPU 使用率超过 90% 时发出警报”

大模型自动生成的调用：

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
  }
})

大模型会自动：

• ✅ 发现所有可用参数
• ✅ 填写必填字段（name、type、query）
• ✅ 添加相关的可选字段
• ✅ 构建复杂对象（options.thresholds）
• ✅ 验证类型和约束

🎯 特别精选的工具

🎯 仪表板

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

🎯 日志

search_logs       # Busca avançada de logs com filtros

🎯 指标

query_metrics     # Query de métricas timeseries

🎯 事件

manage_incidents  # Gerenciamento completo de incidentes

🎯 Synthetics

manage_synthetics # Testes sintéticos completos

🏗️ 与大模型集成

Claude Desktop（推荐）

将以下内容添加到 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"
      }
    }
  }
}

通过 npx（全局）

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

本地开发

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

🛠️ 开发

可用脚本

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

项目结构

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

🔍 调试与故障排除

检查已加载的工具

# 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 tudo
mcp-datadog-server validate

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

测试连接

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

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

日志和调试

# 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

🚨 常见问题排查

1. “未找到工具”

# 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 无效”

# Validar credenciais
mcp-datadog-server validate

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

3. “Schema 未加载”

# 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. “加载的工具过多”

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

📈 性能和限制

速率限制

• ✅ 自动 - 遵循 retry-after headers
• ✅ 可配置 - 通过 MCP_DD_MAX_RETRIES 调整
• ✅ 智能 - 指数退避

超时

• ✅ 默认：每个请求 30 秒
• ✅ 通过 MCP_DD_TIMEOUT_MS 配置
• ✅ 对长时间运行的操作进行进度跟踪

内存使用

• ✅ 已优化 - Schema 在初始化时加载一次
• ✅ 流式处理 - 不会将大型 responses 保留在内存中
• ✅ 过滤器 - 使用 MCP_DD_FOLDERS 减少内存占用

🔐 安全

凭据

• ✅ 仅限环境变量 - 密钥仅通过环境变量提供
• ✅ 不记录日志 - 凭据不会出现在日志中
• ✅ 验证 - 在初始化时验证密钥格式

网络

• ✅ 仅限 TLS - 所有调用均通过 HTTPS 进行
• ✅ 企业代理 - 通过 NODE_EXTRA_CA_CERTS 支持
• ✅ 安全 Headers - 使用适当的 User-Agent 和 headers

输入验证

• ✅ Zod Schemas - 严格验证输入
• ✅ 清理 - 自动清理输入
• ✅ 类型安全 - TypeScript + 运行时验证

📊 监控

健康检查

# Status do servidor
mcp-datadog-server validate

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

可用指标

• ✅ 工具数量 - 已加载工具的总数
• ✅ API 调用 - 按工具跟踪调用
• ✅ 错误率 - 按类别统计错误率
• ✅ 响应时间 - 平均响应时间

🎓 实际示例

创建 CPU 监控器

大模型可以自动执行：

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

列出筛选后的仪表板

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

创建维护停机时间

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

📚 补充文档

• 🔍 SCHEMA_DISCOVERY.md - 大模型如何发现参数
• 📋 REFACTOR_CHECKPOINT.md - 重构历史
• ⚙️ TOOLS.md - 工具完整文档

🤝 贡献

报告 Bug

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

添加精选工具

1. 编辑 src/tools/curated-tools.js
2. 添加完整的 Zod schema
3. 实现 execute 函数
4. 使用 npm test 测试

改进 CRUD 工具

1. 编辑 src/tools/crud-tools.js
2. 向 DATADOG_RESOURCES 添加新资源
3. 定义 schemas 和操作
4. 测试所有 CRUD 操作

📝 变更日志

v0.3.0 - 当前版本

• ✅ 351 个工具（9 个精选工具 + 25 个 CRUD 工具 + 319 个生成工具）
• ✅ 主要资源的完整 CRUD 支持
• ✅ 通过 MCP 自动发现 Schema
• ✅ 对长时间运行的操作进行进度跟踪
• ✅ 提供丰富调试命令的 CLI
• ✅ 100% 符合 MCP 标准

v0.2.x - 先前版本

• ✅ 完成架构重构
• ✅ 使用 Zod 进行稳健验证
• ✅ 带自动重试的 HTTP 客户端
• ✅ 简洁的配置系统

📄 许可证

Apache License 2.0 - 详情请参阅 LICENSE。

🙏 致谢

• Model Context Protocol - 基础框架
• Datadog - API 和文档
• Zod - Schema 验证
• Undici - HTTP 客户端

---

🎉 可与任何兼容 MCP 的大模型搭配使用！

如需支持和讨论，请查看仓库中的 Issues。