07 - Server di Produttivita: Code Review e Scaffolding

Introduzione: Server MCP per la Produttività dello Sviluppatore

Nella categoria Produttività del progetto Tech-MCP, troviamo tre server MCP progettati per automatizzare attivita ripetitive che ogni sviluppatore affronta quotidianamente: la revisione del codice, la gestione delle dipendenze e la creazione di nuovi progetti. Questi server operano come funzioni pure, senza stato interno ne database, rendendoli leggeri, prevedibili e facili da integrare in qualsiasi workflow.

Il problema che risolvono e concreto: le code review manuali sono lente e soggettive, le vulnerabilità nelle dipendenze spesso passano inosservate, e la configurazione iniziale di un nuovo progetto richiede tempo e attenzione per evitare errori. Automatizzando i controlli meccanici, questi server permettono agli sviluppatori di concentrarsi sulla logica di business e sulle scelte architetturali.

Server 1: code-review

Il server code-review fornisce strumenti di analisi statica orientati al processo di revisione del codice. Automatizza i controlli meccanici che un revisore umano tenderebbe a tralasciare: statement di debug dimenticati, credenziali hardcoded, funzioni troppo complesse e pattern problematici. Ogni problema rilevato viene classificato con un livello di severita (error, warning o info), permettendo di prioritizzare le correzioni.

Architettura Stateless

Il server non possiede uno store ne servizi interni. Ogni tool opera come una funzione pura che riceve un input e produce un risultato JSON. Non c'e database, non c'è cache, non c'è stato condiviso tra le chiamate. Questa scelta architetturale garantisce idempotenza: la stessa richiesta produce sempre lo stesso risultato.

            Richiesta MCP
                 |
                 v
      +---------------------+
      |   Tool Dispatcher   |
      +---------------------+
       /        |         \
      v         v          v
analyze-   check-     suggest-
diff       complexity  improvements
  |            |           |
  v            v           v
parseDiff  calculate   checkMagicNumbers
detectIss  Complexity  checkLongFunctions
ues                    checkDeepNesting
                       checkDuplicatePatterns
                       checkUnusedVariables
    

Tabella dei Tool

Tool: analyze-diff

Il tool analyze-diff riceve una stringa nel formato git diff e la analizza riga per riga alla ricerca di pattern problematici. Il flusso interno segue questi passaggi:

1. La stringa diff viene divisa in righe
2. Si estraggono i nomi dei file modificati dagli header +++
3. Si parsano gli hunk headers per tracciare i numeri di riga
4. Ogni riga aggiunta (+) viene testata contro pattern di problemi
5. Si controllano blocchi consecutivi di oltre 50 righe aggiunte

Esempio di richiesta e risposta per analizzare un diff contenente problemi:

// Richiesta
{
  "tool": "analyze-diff",
  "arguments": {
    "diff": "--- a/src/app.ts\n+++ b/src/app.ts\n@@ -10,3 +10,5 @@\n+console.log('debug');\n+const password = 'secret123';\n+debugger;"
  }
}

// Risposta
{
  "stats": { "filesChanged": 1, "linesAdded": 3, "linesRemoved": 0 },
  "totalIssues": 3,
  "issuesBySeverity": { "error": 2, "warning": 1, "info": 0 },
  "issues": [
    { "type": "console-statement", "severity": "warning", "line": 10 },
    { "type": "hardcoded-credential", "severity": "error", "line": 11 },
    { "type": "debugger-statement", "severity": "error", "line": 12 }
  ]
}
    

Tool: check-complexity

Il tool check-complexity calcola la complessità ciclomatica di uno snippet di codice contando i punti di decisione. La complessità parte da 1 (il percorso principale) e incrementa per ogni costrutto di branching trovato.

Il codice viene prima ripulito da commenti e stringhe per evitare falsi positivi, poi si contano i pattern di decisione standard: if, else if, for, while, case, catch, &&, ||, ?:.

La complessità calcolata viene classificata automaticamente in quattro livelli:

• <= 5: Bassa - codice semplice e leggibile
• <= 10: Moderata - complessità gestibile
• <= 20: Alta - candidato al refactoring
• > 20: Molto alta - richiede scomposizione urgente

// Richiesta
{
  "tool": "check-complexity",
  "arguments": {
    "code": "function process(data) {\n  if (data.valid) {\n    for (const item of data.items) {\n      if (item.active && item.count > 0) {\n        switch(item.type) {\n          case 'A': break;\n          case 'B': break;\n        }\n      }\n    }\n  }\n}",
    "language": "javascript"
  }
}

// Risposta
{
  "totalComplexity": 7,
  "rating": "moderate - manageable complexity",
  "breakdown": [
    { "pattern": "if", "count": 2, "description": "If statements" },
    { "pattern": "for", "count": 1, "description": "For loops" },
    { "pattern": "case", "count": 2, "description": "Switch case branches" },
    { "pattern": "&&", "count": 1, "description": "Logical AND operators" }
  ],
  "lineCount": 12,
  "language": "javascript"
}
    

Tool: suggest-improvements

Il tool suggest-improvements esegue cinque controlli indipendenti sul codice sorgente, cercando pattern che indicano potenziali problemi di qualità e manutenibilità:

1. Magic numbers: numeri con 2+ cifre non dichiarati come costanti (esclusi valori comuni come 0, 1, 2, 10, 100, 1000, 24, 60, 1024)
2. Funzioni lunghe: funzioni con più di 30 righe, rilevate tramite conteggio di parentesi graffe
3. Nesting profondo: più di 4 livelli di annidamento di parentesi graffe (deduplicato ogni 5 righe)
4. Codice duplicato: righe identiche (con più di 10 caratteri) che appaiono 3 o più volte
5. Variabili inutilizzate: variabili dichiarate ma referenziate una sola volta nel codice

I suggerimenti sono ordinati per severita: high > medium > low.

// Richiesta
{
  "tool": "suggest-improvements",
  "arguments": {
    "code": "function calc(x) {\n  const result = x * 3.14159;\n  const temp = 42;\n  return result * 86400;\n}",
    "language": "typescript"
  }
}

// Risposta
{
  "totalSuggestions": 2,
  "suggestionsBySeverity": { "high": 0, "medium": 2, "low": 0 },
  "suggestions": [
    { "type": "magic-number", "severity": "medium", "message": "Magic number 3.14159 found" },
    { "type": "magic-number", "severity": "medium", "message": "Magic number 86400 found" }
  ]
}
    

Registrazione dei Tool nel Server

I tool del server code-review vengono registrati seguendo il pattern standard di Tech-MCP. Ogni tool dichiara il proprio schema di input con Zod e implementa un handler che restituisce il risultato come contenuto testuale JSON:

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'analyze-diff',
      description: 'Analyze a git diff string for common issues in added code',
      inputSchema: {
        type: 'object',
        properties: {
          diff: { type: 'string', description: 'The git diff string to analyze' }
        },
        required: ['diff']
      }
    },
    {
      name: 'check-complexity',
      description: 'Calculate cyclomatic complexity of a code snippet',
      inputSchema: {
        type: 'object',
        properties: {
          code: { type: 'string', description: 'The code snippet' },
          language: { type: 'string', description: 'Programming language' }
        },
        required: ['code', 'language']
      }
    },
    {
      name: 'suggest-improvements',
      description: 'Suggest improvements for magic numbers, long functions, deep nesting',
      inputSchema: {
        type: 'object',
        properties: {
          code: { type: 'string', description: 'The code snippet' },
          language: { type: 'string', description: 'Programming language' }
        },
        required: ['code', 'language']
      }
    }
  ]
}));
    

Eventi Pubblicati da code-review

Il server pubblica due eventi sull'EventBus, consumabili da altri server della suite Tech-MCP:

Il server non sottoscrive alcun evento: e puramente reattivo alle chiamate tool. I server standup-notes e agile-metrics possono consumare questi eventi per aggregare metriche di qualità del codice e generare report automatici.

Server 2: dependency-manager

Il server dependency-manager e dedicato alla gestione e all'analisi delle dipendenze di un progetto Node.js. Affronta tre problemi critici nello sviluppo software moderno: vulnerabilità di sicurezza nelle dipendenze, pacchetti dichiarati ma mai importati, e incompatibilita di licenze copyleft che possono imporre restrizioni sulla distribuzione del software.

Architettura e Dipendenze di Sistema

A differenza di code-review che opera interamente tramite regex, il server dependency-manager interagisce con il filesystem e con processi child. Rimane comunque stateless: nessun dato e mantenuto tra le chiamate.

  projectPath
      |
      +-- package.json  <--- letto da tutti e 3 i tool
      |
      +-- node_modules/ <--- letto da license-audit
      |     +-- pkg-a/
      |     |     +-- package.json (campo "license")
      |     +-- pkg-b/
      |           +-- package.json
      |
      +-- src/           <--- scansionato da find-unused
            +-- index.ts
            +-- app.ts
            +-- utils/
    

Tabella dei Tool

Tool: check-vulnerabilities

Il tool check-vulnerabilities e un wrapper strutturato attorno a npm audit --json. Il flusso operativo prevede:

1. Verifica dell'esistenza di package.json nel percorso indicato
2. Esecuzione di npm audit --json con timeout di 60 secondi
3. Gestione del codice di uscita non-zero (npm audit esce con errore se trova vulnerabilità)
4. Parsing dell'output JSON nel formato npm v7+
5. Raggruppamento per severita: critical, high, moderate, low, info
6. Pubblicazione evento code:dependency-alert per ogni vulnerabilità critica o alta

// Richiesta
{
  "tool": "check-vulnerabilities",
  "arguments": {
    "projectPath": "/home/user/my-project"
  }
}

// Risposta
{
  "project": "my-project",
  "totalVulnerabilities": 5,
  "severityCounts": {
    "high": 2,
    "moderate": 2,
    "low": 1
  },
  "vulnerabilities": {
    "high": [
      {
        "name": "lodash",
        "severity": "high",
        "title": "Prototype Pollution",
        "url": "https://github.com/advisories/GHSA-xxxx",
        "range": "<4.17.21",
        "fixAvailable": { "name": "lodash", "version": "4.17.21" }
      }
    ]
  },
  "metadata": {
    "totalDependencies": 142,
    "devDependencies": 38,
    "prodDependencies": 104
  }
}
    

Tool: find-unused

Il tool find-unused esegue una scansione ricorsiva dei file sorgente per identificare le dipendenze dichiarate in package.json ma mai effettivamente importate nel codice. L'analisi copre:

• Import ES modules: import ... from 'package'
• CommonJS: require('package')
• Import dinamici: import('package')
• Pacchetti scoped: gestione corretta di @scope/package

Le directory node_modules, dist, build, .git e coverage vengono automaticamente escluse dalla scansione. I file analizzati includono le estensioni .ts, .js, .tsx e .jsx.

// Richiesta
{
  "tool": "find-unused",
  "arguments": {
    "projectPath": "/home/user/my-project"
  }
}

// Risposta
{
  "project": "my-project",
  "sourceFilesScanned": 47,
  "summary": {
    "totalDependencies": 12,
    "totalDevDependencies": 8,
    "unusedDependencies": 2,
    "unusedDevDependencies": 1
  },
  "unusedDependencies": ["moment", "lodash"],
  "unusedDevDependencies": ["@types/lodash"],
  "note": "Dependencies may be used in config files, scripts, or other non-source files."
}
    

Tool: license-audit

Il tool license-audit esamina le licenze di ogni dipendenza leggendo direttamente i file package.json all'interno di node_modules. Il controllo e particolarmente rilevante per progetti commerciali, dove l'uso di licenze copyleft potrebbe imporre restrizioni indesiderate.

// Richiesta
{
  "tool": "license-audit",
  "arguments": {
    "projectPath": "/home/user/my-project"
  }
}

// Risposta
{
  "project": "my-project",
  "summary": {
    "totalDependenciesChecked": 20,
    "uniqueLicenses": 4,
    "copyleftCount": 1,
    "notFoundInNodeModules": 0
  },
  "copyleftWarnings": [
    { "name": "some-gpl-lib", "version": "2.1.0", "license": "GPL-3.0" }
  ],
  "byLicense": {
    "MIT": [{ "name": "express", "version": "4.21.0" }],
    "ISC": [{ "name": "glob", "version": "10.3.0" }],
    "GPL-3.0": [{ "name": "some-gpl-lib", "version": "2.1.0" }]
  }
}
    

Eventi Pubblicati da dependency-manager

Come code-review, anche questo server non sottoscrive eventi. I server standup-notes e agile-metrics possono ricevere gli alert per tracciare il trend delle vulnerabilità nel tempo.

Server 3: project-scaffolding

Il server project-scaffolding automatizza la creazione di nuovi progetti e componenti a partire da template predefiniti. Ogni nuovo progetto richiede normalmente la creazione manuale di package.json, tsconfig.json, struttura delle cartelle e file boilerplate: un processo ripetitivo e soggetto a errori che questo server elimina completamente.

Template Disponibili

Il server offre quattro template built-in che coprono i casi d'uso più comuni nello sviluppo TypeScript moderno:

Tabella dei Tool

Tool: scaffold-project

Il tool scaffold-project genera un intero progetto a partire da un template selezionato. Il cuore del meccanismo e la sostituzione dei placeholder: ogni file del template contiene segnaposto come {{projectName}}, {{author}}, {{description}} e {{license}} che vengono sostituiti con i valori forniti.

  1. Validazione template
         |
         v
  2. Preparazione valori placeholder
     { projectName, author, description, license }
         |
         v
  3. Per ogni file nel template:
     a. Calcolo percorso: outputDir/projectName/relativePath
     b. Creazione directory (mkdir recursive)
     c. Sostituzione placeholder nel contenuto
     d. Scrittura file su disco
         |
         v
  4. Restituzione lista file creati
    

// Richiesta
{
  "tool": "scaffold-project",
  "arguments": {
    "template": "express-api",
    "projectName": "user-service",
    "outputDir": "/home/user/projects",
    "options": {
      "author": "Mario Rossi",
      "description": "Microservizio gestione utenti",
      "license": "MIT"
    }
  }
}

// Risposta
{
  "template": "express-api",
  "projectName": "user-service",
  "outputDir": "/home/user/projects/user-service",
  "filesCreated": [
    "package.json", "tsconfig.json", "src/index.ts", "src/app.ts",
    "src/routes/health.ts", "src/middleware/error-handler.ts",
    ".gitignore", "README.md"
  ],
  "totalFiles": 8
}
    

Tool: scaffold-component

Il tool scaffold-component genera singoli file per componenti, servizi, controller o modelli. Supporta sia TypeScript che JavaScript e produce codice con struttura standard pronta per l'uso:

// Richiesta
{
  "tool": "scaffold-component",
  "arguments": {
    "type": "service",
    "name": "User",
    "outputDir": "/home/user/projects/user-service/src/services",
    "language": "typescript"
  }
}

// Risposta
{
  "message": "Generated service file: /home/user/projects/user-service/src/services/User.service.ts",
  "filePath": "/home/user/projects/user-service/src/services/User.service.ts"
}
    

Integrazione Event Bus

Il server project-scaffolding non pubblica ne sottoscrive eventi. E un server puramente generativo che opera su richiesta esplicita dell'utente. Tuttavia, i progetti generati possono essere immediatamente analizzati dagli altri server di produttività:

• dependency-manager: per verificare vulnerabilità e licenze delle dipendenze del progetto appena generato
• code-review: per analizzare la qualità del codice generato dai template
• codebase-knowledge: per mappare la struttura del nuovo progetto con architecture-map

Interazioni tra i Server di Produttività

I tre server di produttività collaborano in modo complementare. Pur essendo indipendenti, il loro output può alimentare gli input degli altri server, creando un flusso di lavoro automatizzato:

+----------------------+                          +---------------------+
| project-scaffolding  |  genera progetto    ---> | dependency-manager  |
|                      |  analizzabile            |  (check-vulnerab.)  |
+----------------------+                          +---------------------+
         |
         |  genera codice      --->  +---------------------+
         +-------------------------> | code-review         |
                                     | (analyze/suggest)   |
                                     +---------------------+

+------------------+     code:commit-analyzed       +-------------------+
|   code-review    | -----------------------------> |   standup-notes   |
|                  |     code:review-completed       |   agile-metrics   |
+------------------+ -----------------------------> +-------------------+

+---------------------+    code:dependency-alert    +-------------------+
| dependency-manager  | --------------------------> | standup-notes     |
|                     |                             | agile-metrics     |
+---------------------+                             +-------------------+
    

Pattern Comune: Server Stateless e Analisi Pura

Tutti e tre i server di produttività condividono un pattern architetturale fondamentale: sono completamente stateless. Non utilizzano database, non mantengono cache, non hanno servizi interni con stato persistente. Ogni chiamata tool e indipendente e auto-contenuta.

Questo approccio offre diversi vantaggi:

• Idempotenza: la stessa richiesta produce sempre lo stesso risultato, facilitando testing e debugging
• Scalabilità: nessun collo di bottiglia da stato condiviso, i server possono essere istanziati in parallelo
• Semplicita: nessuna migrazione di database, nessuna gestione di sessioni, nessun cleanup necessario
• Affidabilità: un crash non comporta perdita di dati perchè non c'è stato da preservare

Il server code-review opera interamente tramite regex e conteggio di pattern. Il server dependency-manager legge dal filesystem e invoca npm audit come processo esterno. Il server project-scaffolding scrive file su disco partendo da template in-memory. Nessuno dei tre richiede configurazione di infrastruttura aggiuntiva.

Conclusioni

I tre server di produttività di Tech-MCP dimostrano come MCP possa automatizzare compiti ripetitivi nello sviluppo software senza richiedere infrastruttura complessa. Il server code-review rileva automaticamente problemi comuni nelle code review, dependency-manager mantiene sotto controllo vulnerabilità e licenze, e project-scaffolding elimina il boilerplate nella creazione di nuovi progetti.

Il pattern stateless adottato da tutti e tre i server li rende particolarmente adatti a essere integrati in pipeline CI/CD e workflow automatizzati, dove la prevedibilità e l'assenza di effetti collaterali sono requisiti fondamentali.

Nel prossimo articolo esploreremo i server DevOps della suite Tech-MCP: docker-compose per la gestione dei container, log-analyzer per l'analisi dei log applicativi, e cicd-monitor per il monitoraggio delle pipeline di build e deploy. Vedremo come questi server si integrano con i server di produttività attraverso l'EventBus per creare un workflow di sviluppo completamente automatizzato.

Il codice sorgente completo dei tre server e disponibile nel repository Tech-MCP su GitHub.