# Flussi di lavoro di integrazione (/it/docs/verdent-for-vscode/advanced-features/integrations)

> Pattern pratici per integrare Verdent con strumenti e servizi esterni



### Cosa imparerai [#cosa-imparerai]

Flussi di lavoro pratici di integrazione che combinano sottoagenti personalizzati, regole e server MCP per scenari di sviluppo reali.

***

## Metodi di integrazione [#metodi-di-integrazione]

| Metodo                         | Ideale per                               | Configurazione                    |
| ------------------------------ | ---------------------------------------- | --------------------------------- |
| **Sottoagenti personalizzati** | Attività specializzate basate su AI      | `~/.verdent/subagents/*.md`       |
| **Regole (AGENTS.md)**         | Standard e comportamento del team        | Radice del progetto `AGENTS.md`   |
| **Server MCP**                 | Strumenti esterni conformi al protocollo | `.mcp.json` (radice del progetto) |

**Filosofia:** combina i metodi per creare flussi di lavoro completi su misura per le tue esigenze.

***

## Pattern di integrazione comuni [#pattern-di-integrazione-comuni]

### Flusso di lavoro per lo sviluppo di database [#flusso-di-lavoro-per-lo-sviluppo-di-database]

**Stack:** sottoagente Migration Reviewer + standard AGENTS.md + server PostgreSQL MCP

**Sottoagente:**

```markdown
---
name: migration-reviewer
description: Reviews database migrations for safety
---
Checks: Destructive operations, reversibility, indexing, blocking operations
```

**AGENTS.md:**

```markdown
## Database Standards
- All migrations reviewed by @migration-reviewer
- Test on staging before production
- Include rollback procedures
```

**MCP:** server PostgreSQL per l'esecuzione di query, l'ispezione dello schema e la validazione delle migrazioni

**Flusso di lavoro:** scrivi la migrazione → @migration-reviewer valida → MCP esegue i test in staging → documentazione della PR

***

### Sviluppo API con sicurezza [#sviluppo-api-con-sicurezza]

**Stack:** Security Auditor + regole AGENTS.md + strumento di test API personalizzato

**Componenti:**

* **Sottoagente:** `@api-security-auditor` - Validazione degli input, SQL injection, autenticazione, rate limiting
* **Regole:** tutti gli endpoint richiedono una revisione di sicurezza, rate limiting sugli API pubblici
* **Strumenti esterni:** test automatizzati degli endpoint e scansioni di sicurezza tramite integrazione personalizzata

**Risultato:** revisione di sicurezza automatica prima dell'approvazione della PR.

<Note>
  Gli strumenti di test API e di scansione della sicurezza possono essere integrati tramite implementazioni personalizzate di server MCP o altri metodi di integrazione a seconda dei tuoi strumenti.
</Note>

***

### Accessibilità frontend [#accessibilità-frontend]

**Stack:** Accessibility Auditor + regole WCAG + integrazione Lighthouse

**Flusso di lavoro:**

```
Create component → @a11y-auditor reviews → Lighthouse tests accessibility → Rules enforce >90 score
```

<Note>
  Lighthouse e altri strumenti di accessibilità possono essere integrati tramite server MCP personalizzati o l'integrazione con la pipeline CI/CD a seconda del tuo flusso di lavoro.
</Note>

***

## Esempi di configurazione MCP [#esempi-di-configurazione-mcp]

### Comprendere MCP [#comprendere-mcp]

**Model Context Protocol (MCP)** è un protocollo aperto che standardizza il modo in cui le applicazioni forniscono contesto agli LLM. I server MCP sono eseguibili che implementano il protocollo. Non sono connessioni a database o endpoint API, ma programmi che vengono eseguiti e comunicano tramite JSON-RPC 2.0.

**Concetti chiave:**

* **Server MCP**: eseguibili (pacchetti Node.js, script Python, ecc.) che implementano il protocollo MCP
* **Configurazione**: indica a Verdent come avviare il server (`command` + `args`)
* **Comunicazione**: i server gestiscono la propria logica di business (query, chiamate API, ecc.)

### Configurazione di base [#configurazione-di-base]

**Posizione:** `.mcp.json` nella radice del progetto

<CodeGroup>
  ```json PostgreSQL Server
  {
    "mcpServers": {
      "postgres": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://localhost:5432/myapp_dev"
        ]
      }
    }
  }
  ```

  ```json GitHub Server
  {
    "mcpServers": {
      "github": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-github"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
  ```

  ```json Multiple Servers
  {
    "mcpServers": {
      "postgres": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://localhost:5432/myapp_dev"
        ]
      },
      "github": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-github"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
  ```
</CodeGroup>

**Spiegazione:**

* `mcpServers` - Chiave di primo livello obbligatoria per la configurazione MCP
* `command` - Eseguibile da avviare (tipicamente `npx` per i pacchetti Node.js)
* `args` - Argomenti passati al comando (nome del pacchetto, stringhe di connessione, ecc.)
* `env` - Variabili d'ambiente per autenticazione/configurazione

### Multi-ambiente [#multi-ambiente]

```json
{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DEV_DATABASE_URL}"
      ]
    },
    "postgres-staging": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${STAGING_DATABASE_URL}"
      ]
    },
    "postgres-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${PROD_DATABASE_URL}"
      ]
    }
  }
}
```

**Buona pratica:** usa variabili d'ambiente per le stringhe di connessione per mantenere sicure le credenziali. I server MCP gestiscono internamente il comportamento in sola lettura in base alla loro implementazione. Consulta la documentazione specifica del server per le opzioni di controllo degli accessi.

<Tip>
  **Scopri di più su MCP:**

  * [Model Context Protocol Specification](https://modelcontextprotocol.io/specification)
  * [Registro dei server MCP](https://mcp.so/servers) - Sfoglia i server MCP disponibili
  * [Server MCP ufficiali](https://github.com/modelcontextprotocol) - PostgreSQL, GitHub, Filesystem e altri
</Tip>

***

## Integrazione del workspace [#integrazione-del-workspace]

### Configurazione specifica per il progetto [#configurazione-specifica-per-il-progetto]

**Configurazione:**

1. Salva nella radice del progetto: `.mcp.json`
2. Esegui il commit nel controllo di versione per la condivisione con il team
3. I membri del team usano automaticamente i server MCP del progetto

**Esempio di microservizi:**

```json
{
  "mcpServers": {
    "users-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/users"
      ]
    },
    "orders-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5433/orders"
      ]
    }
  }
}
```

<Note>
  Per servizi aggiuntivi come Kafka, avrai bisogno di un'implementazione di server MCP compatibile. Il registro ufficiale dei server MCP su [mcp.so/servers](https://mcp.so/servers) elenca i server disponibili della community.
</Note>

***

## Collaborazione di team [#collaborazione-di-team]

### Standard AGENTS.md condivisi [#standard-agentsmd-condivisi]

Esegui il commit nel controllo di versione per garantire coerenza a livello di team:

```markdown
# AGENTS.md

## Code Review Process
- Run @code-reviewer before PR
- Address all security warnings
- Minimum 80% test coverage

## Integration Requirements
- @migration-reviewer for database changes
- @api-security-auditor for new endpoints
- @a11y-auditor for UI components

## MCP Servers
- Use postgres-staging MCP server for queries
- Never use postgres-prod MCP server for exploratory queries
```

**Vantaggi:** comportamento coerente, standard applicati, controlli qualità automatici.

***

## Coordinamento multi-agente [#coordinamento-multi-agente]

### Flusso di lavoro per funzionalità complesse [#flusso-di-lavoro-per-funzionalità-complesse]

**Esempio:** nuovo endpoint di pagamento

```
1. Developer request → 2. Main agent generates code →
3. @api-security-auditor reviews security →
4. @migration-reviewer validates schema →
5. MCP tests on staging →
6. Main agent generates tests and PR
```

**Risultato:** endpoint completamente revisionato con applicate le best practice di sicurezza e database.

***

## Best practice di integrazione [#best-practice-di-integrazione]

### Adozione progressiva [#adozione-progressiva]

**Fase 1:** regole di base

```markdown
## Code Standards
- Use TypeScript strict mode
- Run tests before commit
```

**Fase 2:** aggiungi un sottoagente specializzato

```markdown
## Code Review
- Run @security-reviewer before PR
```

**Fase 3:** integra MCP

```markdown
## Database Access
- Use MCP postgres-staging for queries
```

### Combinazioni strategiche [#combinazioni-strategiche]

| Combinazione         | Scopo                                                      | Esempio                                        |
| -------------------- | ---------------------------------------------------------- | ---------------------------------------------- |
| Regole + sottoagenti | Le regole definiscono *quando*, i sottoagenti *analizzano* | AGENTS.md: "Revisiona con @security-reviewer"  |
| Regole + MCP         | Le regole specificano *quali* server, MCP *accede*         | AGENTS.md: "Usa solo db-staging"               |
| Sottoagenti + MCP    | Il sottoagente usa MCP per i *dati esterni*                | Il security auditor interroga gli endpoint API |

### Best practice per la documentazione del team [#best-practice-per-la-documentazione-del-team]

Quando documenti le integrazioni per il tuo team, includi:

* **Sottoagenti personalizzati**: elenca il nome, lo scopo di ciascun sottoagente e quando invocarlo
* **Regole AGENTS.md**: documenta le regole con la motivazione che spiega il "perché" dietro ogni standard
* **Server MCP**: descrivi lo scopo di ciascun server, il livello di accesso (sola lettura/scrittura) e quando usarlo
* **Flussi di lavoro di integrazione**: fornisci flussi di lavoro di esempio che mostrano come i componenti lavorano insieme
* **Risoluzione dei problemi**: documenta i problemi comuni specifici della tua configurazione e le relative soluzioni

<Tip>
  Esegui il commit della documentazione di integrazione insieme ai tuoi file `.mcp.json` e `AGENTS.md` così che i nuovi membri del team possano capire rapidamente la tua configurazione.
</Tip>

***

## Risoluzione dei problemi [#risoluzione-dei-problemi]

<Tabs>
  <Tab title="Problemi con i sottoagenti">
    **Problema:** il sottoagente non si attiva quando previsto

    **Verifica:**

    **Posizione**: il file esiste in `~/.verdent/subagents/[name].md`

    **Frontmatter YAML**: sintassi valida con i campi obbligatori `name` e `description`

    **Policy di invocazione**: corrisponde all'utilizzo (strict richiede una @-menzione esplicita)

    **Descrizione**: la `description` dell'agente descrive accuratamente quando utilizzare il sottoagente

    **Riavvio**: prova a riavviare Verdent per ricaricare le definizioni dei sottoagenti

    ***

    **Cause comuni:**

    * Errore di battitura nel nome del file del sottoagente o nella @-menzione
    * Sintassi YAML non valida nel frontmatter
    * La `description` del sottoagente non corrisponde al contesto dell'attività
  </Tab>

  <Tab title="Problemi con AGENTS.md">
    **Problema:** le regole di AGENTS.md non vengono applicate

    **Verifica:**

    **Posizione**: il file si trova nella directory radice del progetto

    **Sintassi**: Markdown valido senza errori di parsing

    **Stile delle direttive**: usa comandi specifici ("Usa sempre..." e non "Prova a...")

    **Sessione**: avvia una nuova conversazione per testare l'applicazione delle regole da zero

    **Conflitti**: verifica se le regole utente sovrascrivono involontariamente quelle del progetto

    ***

    **Cause comuni:**

    * AGENTS.md nella directory sbagliata (deve essere nella radice del progetto)
    * Istruzioni vaghe che l'AI interpreta in modo diverso
    * Regole applicate ma risultati diversi dall'atteso (affina la formulazione)
  </Tab>

  <Tab title="Problemi con i server MCP">
    **Problema:** il server MCP non si avvia o non si connette

    **Verifica:**

    **Sintassi**: `.mcp.json` contiene JSON valido (usa `jq` per validare)

    **Struttura**: la chiave obbligatoria `mcpServers` è presente al primo livello

    **Configurazione del server**: ogni server ha `command` e `args` specificati correttamente

    **Pacchetto**: il pacchetto del server MCP è accessibile (`npx` scarica i pacchetti automaticamente; il flag `-y` evita la richiesta di conferma)

    **Ambiente**: le variabili nell'oggetto `env` sono impostate correttamente nella tua shell

    **Permessi**: l'eseguibile del server ha i permessi di esecuzione corretti

    ***

    **Cause comuni:**

    * Errore di battitura nel JSON (virgola mancante, parentesi non chiusa)
    * Nome del pacchetto errato nell'array args
    * Variabili d'ambiente mancanti o errate
    * Rete/firewall che blocca l'installazione del pacchetto npx

    ***

    **Passaggi di debug:**

    1. Valida il JSON: `cat .mcp.json | jq .`
    2. Testa il comando manualmente: `npx -y @modelcontextprotocol/server-postgres "postgresql://..."`
    3. Controlla l'ambiente: `echo $GITHUB_TOKEN`
    4. Esamina i log di Verdent per messaggi di errore specifici
  </Tab>
</Tabs>

***

## Vedi anche [#vedi-anche]

<CardGroup cols="2">
  <Card title="Guida all'estensibilità" icon="puzzle-piece" href="/docs/verdent-for-vscode/advanced-features/extensibility">
    Panoramica completa dei metodi di estensione
  </Card>

  <Card title="Integrazione MCP" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp">
    Dettagli sul Model Context Protocol
  </Card>
</CardGroup>