Mcp Datadog Server

MCP Datadog Server

Datadog API と統合するための、完全かつ堅牢な Model Context Protocol（MCP）サーバー

LLM を通じて Datadog のすべての API を操作できる、本番環境対応の MCP サーバーです。完全な CRUD 操作、厳選されたツール、スキーマから自動生成されたツールを含む351 個のツールを提供します。

🚀 主な特徴

📊 利用可能なツール（合計351個）

• 厳選されたツール9個 🎯 - 特定のユースケース向けに手作業で作成し、最適化
• CRUD ツール25個 ⚡ - 主要なリソースに対する CREATE、READ、UPDATE、DELETE 操作
• 自動生成されたツール319個 🔧 - Datadog の公式スキーマから自動生成

🔍 高度な機能

• ✅ スキーマの自動検出 - LLM がパラメーターを自動的に検出
• ✅ 堅牢な検証 - 完全な検証機能を備えた Zod スキーマ
• ✅ 進行状況の追跡 - 長時間の操作の進行状況をリアルタイムで追跡
• ✅ エラー処理 - インテリジェントなエラー処理と自動リトライ
• ✅ 豊富な CLI - 管理とデバッグのための完全なインターフェース

🛡️ MCP 準拠

• ✅ 公式 TypeScript SDK と 100% 互換
• ✅ すべてのツールに対応する完全な 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

📋 LLM によるパラメーターの検出方法

🔍 自動検出

LLM は、事前にパラメーターを知っている必要はありません。MCP プロトコルを通じて、次のことを行います。

1. 利用可能なすべてのツールを一覧表示
2. 各ツールの完全な JSON Schema スキーマを取得
3. すべてのパラメーター、型、検証ルールを理解
4. 有効な呼び出しを自動的に構築

📄 スキーマの例 - 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"]
}

🎯 LLM による使用例

ユーザー入力：

「CPU 使用率が 90% を超えたときにアラートを出すモニターを作成して」

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

LLM は自動的に次のことを行います。

• ✅ 利用可能なすべてのパラメーターを検出
• ✅ 必須フィールド（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

🏗️ LLM との統合

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. 「スキーマが読み込まれていません」

# 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 ヘッダーに従います
• ✅ 設定可能 - MCP_DD_MAX_RETRIES で調整できます
• ✅ インテリジェント - 指数バックオフ

タイムアウト

• ✅ デフォルト：リクエストごとに30秒
• ✅ MCP_DD_TIMEOUT_MS で設定可能
• ✅ 長時間の操作向けプログレス追跡

メモリ使用量

• ✅ 最適化済み - スキーマは初期化時に一度だけ読み込まれます
• ✅ ストリーミング - 大きなレスポンスをメモリに保持しません
• ✅ フィルター - MCP_DD_FOLDERS を使用してメモリ使用量を削減します

🔐 セキュリティ

認証情報

• ✅ 環境変数のみ - キーは環境変数経由でのみ指定します
• ✅ ログに記録しない - 認証情報がログに出力されることはありません
• ✅ 検証 - キーの形式は初期化時に検証されます

ネットワーク

• ✅ TLS のみ - すべての呼び出しは HTTPS 経由です
• ✅ 企業プロキシ - NODE_EXTRA_CA_CERTS 経由でサポートします
• ✅ セキュリティヘッダー - 適切な User-Agent とヘッダーを使用します

入力検証

• ✅ Zod スキーマ - 入力を厳密に検証します
• ✅ サニタイズ - 入力を自動的にクリーンアップします
• ✅ 型安全性 - TypeScript と実行時検証

📊 モニタリング

ヘルスチェック

# Status do servidor
mcp-datadog-server validate

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

利用可能なメトリクス

• ✅ ツール数 - 読み込まれたツールの合計数
• ✅ API 呼び出し - ツールごとの呼び出しを追跡します
• ✅ エラー率 - カテゴリーごとのエラー率
• ✅ レスポンス時間 - 平均レスポンス時間

🎓 実践例

CPU モニターを作成する

LLM は次の操作を自動的に実行できます：

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 - LLM がパラメーターを検出する方法
• 📋 REFACTOR_CHECKPOINT.md - リファクタリングの履歴
• ⚙️ TOOLS.md - ツールの完全なドキュメント

🤝 コントリビューション

バグを報告する

# 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 スキーマを追加します
3. execute 関数を実装します
4. npm test でテストします

CRUD ツールを改善する

1. src/tools/crud-tools.js を編集します
2. DATADOG_RESOURCES に新しいリソースを追加します
3. スキーマと操作を定義します
4. すべての CRUD 操作をテストします

📝 変更履歴

v0.3.0 - 現在

• ✅ 351 個のツール（厳選 9 個 + CRUD 25 個 + 生成 319 個）
• ✅ 主要リソースの完全な CRUD
• ✅ MCP 経由のスキーマ自動検出
• ✅ 長時間の操作向けプログレス追跡
• ✅ デバッグコマンドを備えた充実した CLI
• ✅ MCP 標準に完全準拠

v0.2.x - 以前

• ✅ アーキテクチャを全面的にリファクタリング
• ✅ Zod による堅牢な検証
• ✅ 自動リトライ機能を備えた HTTP クライアント
• ✅ シンプルな設定システム

📄 ライセンス

Apache License 2.0 - 詳細は LICENSE を参照してください。

🙏 謝辞

• Model Context Protocol - 基盤となるフレームワーク
• Datadog - API とドキュメント
• Zod - スキーマ検証
• Undici - HTTP クライアント

---

🎉 MCP 互換のあらゆる LLM ですぐに使用できます！

サポートやディスカッションについては、リポジトリの Issues をご覧ください。