08 - Server DevOps: Docker, Log e CI/CD

Introduzione: MCP per il DevOps

Il DevOps moderno richiede l'orchestrazione di container, l'analisi continua dei log applicativi e il monitoraggio delle pipeline CI/CD. Queste attivita, svolte manualmente, consumano tempo prezioso e sono soggette a errori. Con il Model Context Protocol, possiamo automatizzare queste operazioni direttamente dall'IDE, senza cambiare contesto tra terminale, dashboard di GitHub Actions e interfacce web di monitoraggio.

In questo articolo analizziamo i tre server MCP della categoria DevOps del progetto Tech-MCP: docker-compose per la gestione degli stack Docker, log-analyzer per l'analisi automatizzata dei file di log e cicd-monitor per il monitoraggio delle pipeline GitHub Actions.

1. Server docker-compose: Gestione Stack Docker

Il server docker-compose fornisce strumenti per il parsing, l'analisi, il monitoraggio e la generazione di configurazioni Docker Compose. Il problema che risolve e la complessità crescente dei file docker-compose.yml e dei Dockerfile, dove errori di configurazione, bad practice e mancanza di standardizzazione possono causare problemi in produzione.

Architettura del Server

Il server opera su due canali principali: il filesystem per la lettura di file YAML e Dockerfile, e il processo child_process per l'esecuzione di comandi Docker. Non pubblica ne sottoscrive eventi sull'Event Bus: tutte le operazioni sono stateless e on-demand.

+------------------------------------------------------------+
|               docker-compose server                        |
|                                                            |
|  +-------------------------------------------------------+ |
|  |                  Tool Layer                           | |
|  |                                                       | |
|  |  parse-compose     analyze-dockerfile                 | |
|  |  list-services     generate-compose                   | |
|  +-------------------------------------------------------+ |
|        |                                    |              |
|        v                                    v              |
|  +------------+                    +------------------+    |
|  | fs         |                    | child_process    |    |
|  | readFile   |                    | execSync         |    |
|  | (YAML/     |                    | (docker compose  |    |
|  |  Docker)   |                    |  ps --format     |    |
|  +------------+                    |  json)           |    |
|                                    +------------------+    |
+------------------------------------------------------------+
    

Tabella dei Tool

Schema Zod: parse-compose

Il tool parse-compose accetta un singolo parametro filePath che indica il percorso al file docker-compose.yml da analizzare. Il parser interno e line-based e non dipende da librerie YAML esterne.

// Schema Zod per parse-compose
const ParseComposeSchema = z.object({
  filePath: z.string().describe("Percorso al file docker-compose.yml")
});
    

Parser YAML Line-Based

Il parser analizza il file riga per riga, identificando le sezioni top-level (services, networks, volumes) e per ogni servizio estrae le proprietà: image, build, ports, environment e volumes. Il parser esegue anche validazioni automatiche:

• Immagine senza tag specifico (es. nginx senza :1.25-alpine)
• Uso di privileged: true (rischio di sicurezza)
• Uso di network_mode: host (espone tutte le porte)
• Servizio senza image ne build definiti
• Presenza del campo version deprecato

Esempio di richiesta e risposta:

// Richiesta
{
  "tool": "parse-compose",
  "arguments": {
    "filePath": "/home/user/project/docker-compose.yml"
  }
}

// Risposta
{
  "filePath": "/home/user/project/docker-compose.yml",
  "services": ["web", "db", "redis"],
  "serviceCount": 3,
  "networks": ["backend"],
  "volumes": ["db_data"],
  "validationIssues": [
    "Service \"web\" uses image \"nginx\" without a specific tag."
  ],
  "hasIssues": true
}
    

Schema Zod: analyze-dockerfile

Il tool analyze-dockerfile esamina un Dockerfile applicando un set di regole di best practice con tre livelli di severita: error, warning e info.

// Schema Zod per analyze-dockerfile
const AnalyzeDockerfileSchema = z.object({
  filePath: z.string().describe("Percorso al Dockerfile da analizzare")
});
    

Esempio di risposta dall'analisi di un Dockerfile:

{
  "filePath": "/home/user/project/Dockerfile",
  "baseImage": "node:latest",
  "stages": 1,
  "totalInstructions": 12,
  "issues": [
    {
      "line": 1,
      "severity": "warning",
      "rule": "no-latest-tag",
      "message": "Base image \"node:latest\" uses the :latest tag.",
      "suggestion": "Pin to a specific version tag (e.g., node:20-alpine)."
    },
    {
      "line": 0,
      "severity": "warning",
      "rule": "running-as-root",
      "message": "No USER instruction found.",
      "suggestion": "Add a USER instruction to run as non-root."
    }
  ],
  "summary": { "errors": 0, "warnings": 2, "info": 1 }
}
    

Schema Zod: generate-compose

Il tool generate-compose riceve un array di definizioni di servizi e produce un file docker-compose.yml valido. Aggiunge automaticamente restart: unless-stopped a ogni servizio e dichiara i named volume nella sezione volumes:.

// Schema Zod per generate-compose
const GenerateComposeSchema = z.object({
  services: z.array(z.object({
    name: z.string().describe("Nome del servizio"),
    image: z.string().describe("Immagine Docker da utilizzare"),
    ports: z.array(z.string()).optional()
      .describe("Array di mapping porte (es. '3000:3000')"),
    environment: z.record(z.string()).optional()
      .describe("Variabili d'ambiente come coppie chiave-valore"),
    volumes: z.array(z.string()).optional()
      .describe("Array di mount (bind mount o named volume)")
  })).describe("Array di definizioni servizio")
});
    

Esempio di generazione:

// Richiesta
{
  "tool": "generate-compose",
  "arguments": {
    "services": [
      {
        "name": "api",
        "image": "node:20-alpine",
        "ports": ["3000:3000"],
        "environment": { "NODE_ENV": "production" },
        "volumes": ["./src:/app/src"]
      },
      {
        "name": "postgres",
        "image": "postgres:16-alpine",
        "ports": ["5432:5432"],
        "environment": { "POSTGRES_PASSWORD": "secret" },
        "volumes": ["pg_data:/var/lib/postgresql/data"]
      }
    ]
  }
}
    

# Output generato
services:
  api:
    image: node:20-alpine
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: "production"
    volumes:
      - ./src:/app/src
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: "secret"
    volumes:
      - pg_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  pg_data:
    

Schema Zod: list-services

Il tool list-services elenca i servizi Docker in esecuzione. Internamente esegue docker compose ps --format json e, in caso di fallimento, tenta con il comando legacy docker-compose ps --format json.

// Schema Zod per list-services
const ListServicesSchema = z.object({
  composePath: z.string().optional()
    .describe("Percorso opzionale al docker-compose.yml per filtrare")
});

// Formato risposta
interface ServiceInfo {
  name: string;
  status: string;
  image: string;
  ports: string;
}
    

2. Server log-analyzer: Analisi Automatizzata dei Log

Il server log-analyzer affronta un problema universale: i file di log crescono rapidamente, contengono migliaia di righe e individuare pattern di errore, anomalie o trend richiede tempo e competenze specifiche. Questo server automatizza l'analisi, supportando sia log in formato testo puro che log strutturati in formato JSON (NDJSON).

Architettura del Server

Come docker-compose, anche log-analyzer e un server stateless che non pubblica ne sottoscrive eventi. Opera direttamente sul filesystem tramite fs/promises.

+------------------------------------------------------------+
|               log-analyzer server                          |
|                                                            |
|  +-------------------------------------------------------+ |
|  |                  Tool Layer                           | |
|  |                                                       | |
|  |  analyze-log-file   find-error-patterns               | |
|  |  tail-log           generate-summary                  | |
|  +-------------------------------------------------------+ |
|                         |                                  |
|                         v                                  |
|  +-------------------------------------------------------+ |
|  |           fs/promises (readFile)                      | |
|  |                                                       | |
|  |  Formati supportati:                                  | |
|  |  - Plain text (syslog, Apache, custom)                | |
|  |  - JSON lines (NDJSON, structured logging)            | |
|  |  - Auto-detection basata su campionamento             | |
|  +-------------------------------------------------------+ |
+------------------------------------------------------------+
    

Tabella dei Tool

Auto-Detection del Formato

Il server campiona le prime 10 righe del file per determinare automaticamente se il log e in formato JSON o plain text. Se ogni riga inizia con { e viene parsata correttamente come JSON, il formato viene impostato a json. In caso contrario, il server utilizza regex per estrarre livelli di log e timestamp.

I livelli di log riconosciuti sono: ERROR, WARN (WARNING), INFO, DEBUG, TRACE, FATAL, CRITICAL e NOTICE.

Schema Zod: analyze-log-file

// Schema Zod per analyze-log-file
const AnalyzeLogFileSchema = z.object({
  filePath: z.string().describe("Percorso al file di log"),
  format: z.enum(["auto", "json", "plain"]).optional()
    .default("auto")
    .describe("Formato del log: auto-detect, JSON lines o plain text")
});
    

Esempio di risposta:

{
  "totalLines": 5420,
  "levels": {
    "INFO": 5100,
    "WARN": 250,
    "ERROR": 65,
    "DEBUG": 5
  },
  "topErrors": [
    { "message": "Connection refused to redis:6379", "count": 30 },
    { "message": "Request timeout after 30000ms", "count": 20 }
  ],
  "timeRange": {
    "earliest": "2024-06-15T08:00:01.234Z",
    "latest": "2024-06-15T18:45:30.567Z"
  }
}
    

Schema Zod: find-error-patterns

Il tool find-error-patterns normalizza i messaggi di errore per raggruppare occorrenze dello stesso problema con dati diversi. UUID, indirizzi IP, numeri, URL e path vengono sostituiti con placeholder generici.

// Schema Zod per find-error-patterns
const FindErrorPatternsSchema = z.object({
  filePath: z.string().describe("Percorso al file di log"),
  minCount: z.number().optional().default(2)
    .describe("Numero minimo di occorrenze per considerare un pattern")
});
    

Esempio di risposta con pattern normalizzati:

{
  "totalPatternsFound": 4,
  "minCount": 3,
  "patterns": [
    {
      "pattern": "Connection refused to <IP>",
      "count": 30,
      "examples": [
        "Connection refused to 10.0.0.5:6379",
        "Connection refused to 10.0.0.5:6380"
      ]
    },
    {
      "pattern": "Request timeout after <NUM>ms for <URL>",
      "count": 20,
      "examples": [
        "Request timeout after 30000ms for https://api.external.com/v1/users"
      ]
    }
  ]
}
    

Schema Zod: tail-log

// Schema Zod per tail-log
const TailLogSchema = z.object({
  filePath: z.string().describe("Percorso al file di log"),
  lines: z.number().optional().default(50)
    .describe("Numero di righe da restituire dalla fine del file"),
  filter: z.string().optional()
    .describe("Stringa di filtro per selezionare solo le righe corrispondenti")
});
    

Esempio con filtro per errori:

// Richiesta
{
  "tool": "tail-log",
  "arguments": {
    "filePath": "/var/log/app/application.log",
    "lines": 20,
    "filter": "ERROR"
  }
}

// Risposta
"2024-06-15T18:30:00Z ERROR Connection refused to redis:6379\n
2024-06-15T18:35:12Z ERROR Request timeout after 30000ms\n
..."
    

Schema Zod: generate-summary

Il tool generate-summary produce un report testuale completo che include conteggi per livello, range temporale, indicatori di salute (error rate, warning rate) e i top 5 errori per frequenza.

// Schema Zod per generate-summary
const GenerateSummarySchema = z.object({
  filePath: z.string().describe("Percorso al file di log da riassumere")
});
    

Esempio di output formattato:

Log File Summary: /path/to/file.log
==================================================

Total lines: 15234

Log Level Breakdown:
  ERROR: 42 (0.3%)
  WARN: 156 (1.0%)
  INFO: 14836 (97.4%)
  DEBUG: 200 (1.3%)

Time Range:
  Earliest: 2024-01-15T00:00:01Z
  Latest:   2024-01-15T23:59:58Z

Health Indicators:
  Error rate: 0.3%
  Warning rate: 1.0%

Top Error Messages:
  1. [15x] Connection timeout to database
  2. [12x] Failed to parse request body
  3. [8x]  Authentication token expired
    

3. Server cicd-monitor: Monitoraggio Pipeline CI/CD

Il server cicd-monitor e il ponte tra la suite MCP e le pipeline di Continuous Integration e Continuous Deployment. Si integra nativamente con GitHub Actions tramite la CLI gh, permettendo di monitorare workflow run, visualizzare log di build e identificare test instabili (flaky) senza lasciare l'ambiente di sviluppo.

Architettura del Server

A differenza dei due server precedenti, cicd-monitor pubblica eventi sull'Event Bus. Quando il tool get-pipeline-status rileva un workflow completato o fallito, emette gli eventi corrispondenti che possono essere consumati da altri server come standup-notes e agile-metrics.

+------------------------------------------------------------+
|               cicd-monitor server                          |
|                                                            |
|  +-------------------------------------------------------+ |
|  |                  Tool Layer                           | |
|  |                                                       | |
|  |  list-pipelines       get-pipeline-status             | |
|  |  get-build-logs       get-flaky-tests                 | |
|  +-------------------------------------------------------+ |
|                           |                                |
|                           v                                |
|  +-------------------------------------------------------+ |
|  |          child_process.execSync                       | |
|  |          Comandi: gh run list / gh run view           | |
|  +-------------------------------------------------------+ |
|                           |                                |
|                           v                                |
|  +-------------------------------------------------------+ |
|  |   Event Bus                                           | |
|  |   cicd:pipeline-completed                             | |
|  |   cicd:build-failed                                   | |
|  +-------------------------------------------------------+ |
+------------------------------------------------------------+
    

Tabella dei Tool

Schema Zod: list-pipelines

// Schema Zod per list-pipelines
const ListPipelinesSchema = z.object({
  repo: z.string().optional()
    .describe("Repository nel formato owner/repo"),
  limit: z.number().optional().default(10)
    .describe("Numero massimo di run da restituire")
});
    

Internamente il tool esegue il comando gh run list --json databaseId,displayTitle,headBranch,event,status,conclusion,createdAt,updatedAt,url,workflowName e mappa il risultato in un formato semplificato.

// Risposta
{
  "total": 5,
  "runs": [
    {
      "id": 12345678,
      "title": "feat: add user authentication",
      "branch": "feature/auth",
      "event": "push",
      "status": "completed",
      "conclusion": "success",
      "workflow": "CI",
      "createdAt": "2024-06-15T10:00:00Z",
      "url": "https://github.com/my-org/my-project/actions/runs/12345678"
    }
  ]
}
    

Schema Zod: get-pipeline-status

Il tool get-pipeline-status e il più importante del server, perchè non solo fornisce il dettaglio di un workflow run, ma e anche il trigger per la pubblicazione degli eventi sull'Event Bus.

// Schema Zod per get-pipeline-status
const GetPipelineStatusSchema = z.object({
  runId: z.string().describe("ID del workflow run di GitHub Actions"),
  repo: z.string().optional()
    .describe("Repository nel formato owner/repo")
});
    

Il tool esegue due comandi gh in sequenza: uno per i dettagli del run e uno per i job e step. In base al risultato pubblica gli eventi appropriati:

• Se conclusion == 'success': pubblica cicd:pipeline-completed con status success
• Se conclusion == 'failure': pubblica sia cicd:pipeline-completed con status failed sia cicd:build-failed con il nome del job fallito

// Risposta con dettaglio job e step
{
  "id": 12345678,
  "title": "feat: add user authentication",
  "branch": "feature/auth",
  "sha": "abc123def456",
  "conclusion": "failure",
  "jobs": [
    {
      "name": "build",
      "conclusion": "success",
      "steps": [
        { "name": "Checkout", "conclusion": "success", "number": 1 },
        { "name": "Install", "conclusion": "success", "number": 2 },
        { "name": "Build", "conclusion": "success", "number": 3 }
      ]
    },
    {
      "name": "test",
      "conclusion": "failure",
      "steps": [
        { "name": "Run tests", "conclusion": "failure", "number": 1 }
      ]
    }
  ]
}
    

Schema Zod: get-build-logs

// Schema Zod per get-build-logs
const GetBuildLogsSchema = z.object({
  runId: z.string().describe("ID del workflow run"),
  repo: z.string().optional()
    .describe("Repository nel formato owner/repo"),
  lines: z.number().optional().default(100)
    .describe("Numero di righe di log da restituire")
});
    

Il tool esegue gh run view <id> --log con un timeout di 60 secondi (più alto degli altri comandi, dato che i log possono raggiungere i 10MB) e restituisce le ultime N righe.

Schema Zod: get-flaky-tests

Il rilevamento dei test flaky e l'operazione più complessa del server. L'algoritmo analizza gli ultimi N run, raggruppa per branch e workflow, e identifica gli step che hanno sia passaggi che fallimenti.

// Schema Zod per get-flaky-tests
const GetFlakyTestsSchema = z.object({
  repo: z.string().optional()
    .describe("Repository nel formato owner/repo"),
  branch: z.string().optional()
    .describe("Branch specifico da analizzare"),
  runs: z.number().optional().default(20)
    .describe("Numero di run recenti da analizzare")
});
    

// Risposta get-flaky-tests
{
  "analyzedRuns": 20,
  "branchesAnalyzed": 1,
  "flakyStepsFound": 2,
  "flaky": [
    {
      "branch": "main",
      "workflow": "CI",
      "job": "test",
      "step": "Run integration tests",
      "passCount": 3,
      "failCount": 2,
      "totalRuns": 5,
      "flakinessRate": 40.0
    }
  ]
}
    

Eventi sull'Event Bus

Tra i tre server DevOps, solo cicd-monitor pubblica eventi sull'Event Bus. I server docker-compose e log-analyzer sono completamente stateless e non interagiscono con il sistema di eventi.

La durata della pipeline viene calcolata come differenza in millisecondi tra updatedAt e createdAt. Gli eventi vengono consumati principalmente da:

• standup-notes: riceve notifica di build completate e fallite per generare report giornalieri automatici
• agile-metrics: aggrega metriche di velocità pipeline e tasso di fallimento per la dashboard di progetto

Interazioni tra i Server DevOps

I tre server DevOps sono progettati per lavorare in modo complementare. Sebbene ciascuno possa operare indipendentemente, la combinazione dei tre copre l'intero ciclo DevOps:

Configurazione Claude Desktop

Per utilizzare i tre server DevOps con Claude Desktop, aggiungi le seguenti voci al file di configurazione:

{
  "mcpServers": {
    "docker-compose": {
      "command": "node",
      "args": ["path/to/Tech-MCP/servers/docker-compose/dist/index.js"],
      "env": {}
    },
    "log-analyzer": {
      "command": "node",
      "args": ["path/to/Tech-MCP/servers/log-analyzer/dist/index.js"],
      "env": {}
    },
    "cicd-monitor": {
      "command": "node",
      "args": ["path/to/Tech-MCP/servers/cicd-monitor/dist/index.js"],
      "env": {}
    }
  }
}
    

Sviluppi Futuri

La roadmap per i server DevOps include miglioramenti significativi:

• docker-compose: supporto Docker Swarm, validazione network, analisi multi-stage Dockerfile, template per stack comuni (LAMP, MEAN), integrazione Event Bus per eventi container start/stop/crash
• log-analyzer: streaming in tempo reale con fs.watch, correlazione multi-file, anomaly detection, supporto per file compressi .gz e .bz2, output con istogrammi ASCII
• cicd-monitor: supporto multi-piattaforma (GitLab CI, Bitbucket Pipelines, Jenkins), caching intelligente, analisi trend storici, DORA metrics (lead time, cycle time, deployment frequency)

Conclusioni

I tre server DevOps di Tech-MCP coprono le esigenze fondamentali dell'automazione DevOps: docker-compose garantisce la qualità delle configurazioni Docker con parsing YAML e analisi Dockerfile, log-analyzer automatizza l'analisi dei log applicativi con auto-detection del formato e normalizzazione dei pattern di errore, e cicd-monitor porta il monitoraggio delle pipeline GitHub Actions direttamente nell'IDE con rilevamento automatico dei test flaky.

L'aspetto più interessante e la complementarieta: i log di build scaricati da cicd-monitor possono essere analizzati con log-analyzer, mentre le configurazioni Docker validate da docker-compose alimentano le pipeline monitorate da cicd-monitor. Gli eventi pubblicati sull'Event Bus collegano il ciclo DevOps al project management, chiudendo il cerchio.

Nel prossimo articolo analizzeremo i server per Database e Testing: db-schema-explorer per l'esplorazione degli schemi, data-mock-generator per la generazione di dati di test, test-generator per la creazione automatica di test e performance-profiler per il profiling delle prestazioni.

Il codice completo di tutti i server e disponibile nel repository Tech-MCP su GitHub.