Utilizzare Knowledge Catalog con MCP, Gemini e altri agenti

Questa pagina spiega come connettere l'istanza di Knowledge Catalog (in precedenza Dataplex Universal Catalog) a strumenti per sviluppatori come Gemini CLI. La connessione di Knowledge Catalog a questi strumenti consente il rilevamento dei dati e la gestione degli asset basati sull'AI direttamente all'interno dell'IDE.

Per un'esperienza a riga di comando integrata, ti consigliamo di utilizzare l'estensione Knowledge Catalog dedicata per Gemini CLI. L'estensione raggruppa il server Model Context Protocol (MCP) sottostante, che funge da intermediario tra Gemini CLI e Knowledge Catalog, eliminando la necessità di una configurazione separata del server.

In alternativa, puoi connettere altri IDE e strumenti per sviluppatori che supportano MCP utilizzando MCP Toolbox for Databases per uso generico. Puoi quindi utilizzare gli agenti AI nell'IDE esistente per scoprire gli asset di dati in Knowledge Catalog. Per saperne di più su MCP, consulta Introduzione al Model Context Protocol.

Questa guida illustra la procedura di connessione per i seguenti strumenti:

Gemini CLI (tramite estensione)
Gemini Code Assist
Claude Code
Claude Desktop
Cline (estensione VS Code)
Cursore
Visual Studio Code (Copilot)
Windsurf (in precedenza Codeium)

Informazioni su Gemini CLI ed estensioni

Gemini CLI è un agente AI conversazionale open source di Google che accelera i workflow di sviluppo e assiste nella codifica, nel debug, nell'esplorazione dei dati e nella creazione di contenuti. Offre un'esperienza basata su agenti per interagire con i servizi Data Cloud, come Knowledge Catalog, e altri database open source popolari.

Per saperne di più su Gemini CLI, consulta la documentazione di Gemini CLI.

Funzionamento delle estensioni

Le estensioni espandono le funzionalità di Gemini CLI, consentendogli di connettersi e controllare servizi specifici Google Cloud e altri strumenti. Forniscono a Gemini il contesto e la comprensione delle API, consentendo l'interazione conversazionale. Puoi caricare le estensioni Gemini CLI da URL GitHub, directory locali o registri. Queste estensioni offrono nuovi strumenti, comandi slash e prompt. Questi sono separati dalle estensioni IDE, come Gemini Code Assist, che si integrano utilizzando MCP Toolbox.

Informazioni sull'estensione Knowledge Catalog

MCP Toolbox for Databases è in versione beta (pre-v1.0) e potrebbe subire modifiche che causano interruzioni fino alla prima release stabile (v1.0).

L'estensione Knowledge Catalog per Gemini CLI integra l'AI nelle attività di governance e rilevamento dei dati. Puoi interagire con Knowledge Catalog utilizzando prompt in linguaggio naturale nel terminale. Ecco alcuni esempi:

Categoria	Strumento	Esempio di prompt in linguaggio naturale
Rilevamento e governance dei dati	`dataplex_search_entries`	Trova tutti i set di dati relativi alle vendite in Europa. Mostrami le tabelle che contengono PII dei clienti. Elenca tutti i set di dati BigQuery nel lake "marketing" in Knowledge Catalog.
	`dataplex_lookup_entry`	Qual è lo schema della tabella "orders"? Descrivi le regole sulla qualità dei dati applicate al database dei clienti. Chi è indicato come proprietario dell'attività per la tabella `customer_details`?
	`dataplex_search_aspect_types`	Mostrami i tipi di aspetto relativi alle regole sulla qualità dei dati. Elenca tutti i tipi di aspetto utilizzati per la governance dei dati. Esistono tipi di aspetto per contrassegnare i dati PII?
LLM di grounding con contesto	`dataplex_lookup_context`	Descrivi l'asset di dati `orders`. Scrivi una query SQL che conta la quantità di utenti per paese. Scrivi una pipeline di dati che pulisce la tabella `products`.

Per saperne di più sull'estensione Knowledge Catalog, consulta l' Estensione Gemini CLI - Knowledge Catalog.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per connetterti a Knowledge Catalog utilizzando MCP Toolbox o l'estensione Gemini CLI, chiedi all'amministratore di concederti i seguenti ruoli IAM nel tuo progetto:

Per abilitare le API: Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin)
Per utilizzare gli strumenti di Knowledge Catalog: Visualizzatore catalogo Dataplex (roles/dataplex.catalogViewer)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per connetterti a Knowledge Catalog utilizzando MCP Toolbox o l'estensione Gemini CLI. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per connetterti a Knowledge Catalog utilizzando MCP Toolbox o l'estensione Gemini CLI, sono necessarie le seguenti autorizzazioni:

Per abilitare le API: serviceusage.services.enable
Per utilizzare gli strumenti di Knowledge Catalog:
- dataplex.projects.search
- dataplex.entries.get
- dataplex.aspectTypes.get
- dataplex.aspectTypes.list

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Abilitare l'API Dataplex

Nella Google Cloud console, vai alla pagina di selezione del progetto.

Vai al selettore di progetti
Seleziona o crea un Google Cloud progetto.
Ruoli richiesti per selezionare o creare un progetto
- Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico: puoi selezionare qualsiasi progetto su cui ti è stato concesso un ruolo.
- Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l' resourcemanager.projects.create autorizzazione. Scopri come concedere i ruoli.
Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno già esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.
Verifica che la fatturazione sia abilitata per il tuo Google Cloud progetto.
Abilita l'API Dataplex.
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre del ruolo IAM Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.
Abilitare l'API

Se utilizzi una shell locale, crea le credenziali di autenticazione locali per il tuo account utente:
```
gcloud auth application-default login
```
Non devi eseguire questa operazione se utilizzi Cloud Shell.

Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver acceduto a gcloud CLI con la tua identità federata.

Installare MCP Toolbox

Non devi installare MCP Toolbox se prevedi di utilizzare solo Gemini Code Assist o l' estensione Gemini CLI, poiché questi strumenti raggruppano le funzionalità del server richieste. Per altri IDE e strumenti, segui i passaggi descritti in questa sezione per installare MCP Toolbox.

Scarica l'ultima versione di MCP Toolbox come file binario. Seleziona il file binario corrispondente al tuo sistema operativo e all'architettura della CPU. Devi utilizzare MCP Toolbox v0.31.0 o versioni successive.
Linux/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/linux/amd64/toolbox
Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.31.0.
macOS (Darwin)/arm64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/arm64/toolbox
Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.31.0.
macOS (Darwin)/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/amd64/toolbox
Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.31.0.
Windows/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/windows/amd64/toolbox
Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.31.0.
Rendi eseguibile il file binario:
```
chmod +x toolbox
```
Verifica l'installazione:
```
./toolbox --version
```
Un'installazione riuscita restituisce il numero di versione, ad esempio 0.15.0.

Configurare client e connessioni

Questa sezione spiega come connettere Knowledge Catalog ai tuoi strumenti.

Se utilizzi Gemini Code Assist o Gemini CLI standalone, non devi installare o configurare MCP Toolbox, poiché questi strumenti raggruppano le funzionalità del server richieste. Per le istruzioni di configurazione, consulta le schede Gemini Code Assist o Estensione Gemini CLI.

Per altri strumenti e IDE compatibili con MCP, devi prima installare MCP Toolbox. La toolbox funge da server Model Context Protocol (MCP) open source che si trova tra l'IDE e Knowledge Catalog, fornendo un piano di controllo sicuro ed efficiente per gli strumenti AI. Dopo l'installazione, seleziona la scheda dello strumento specifico per visualizzare le istruzioni di configurazione.

Estensione Gemini CLI

Questo metodo utilizza l'estensione dataplex dedicata per lo strumento Gemini CLI standalone e non utilizza MCP Toolbox.

Installa il Gemini CLI.
Installa l'estensione Knowledge Catalog per Gemini CLI dal repository GitHub:
```
gemini extensions install https://github.com/gemini-cli-extensions/dataplex
```
Imposta la variabile di ambiente per connetterti al progetto Knowledge Catalog:
```
export DATAPLEX_PROJECT="PROJECT_ID"
```
Sostituisci PROJECT_ID con l'ID progetto Google Cloud .
Avvia Gemini CLI in modalità interattiva:
```
gemini
```
L'interfaccia a riga di comando carica automaticamente l'estensione Knowledge Catalog e i relativi strumenti, che puoi utilizzare per interagire con gli asset di dati.

Gemini Code Assist

Gemini Code Assist raggruppa le funzionalità del server MCP richieste, quindi non devi installare MCP Toolbox separatamente.

In VS Code, installa l' estensione Gemini Code Assist.
Attiva la modalità agente nella chat di Gemini Code Assist.
Nella directory di lavoro, crea una cartella denominata .gemini. Al suo interno, crea un file settings.json.

Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva:

  {
    "mcpServers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Claude Code

Installa Claude Code.
Crea il file .mcp.json nella root del progetto, se non esiste.

Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva:

  {
    "mcpServers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Claude Desktop

Apri Claude Desktop e vai a Impostazioni.
Per aprire il file di configurazione, nella scheda Sviluppatore fai clic su Modifica configurazione.

Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi valori, e salva:

  {
    "mcpServers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Riavvia Claude Desktop.
Nella nuova schermata della chat viene visualizzata un'icona MCP con il nuovo server MCP.

Cline

In VS Code, apri l'estensione Cline e poi fai clic sull'icona Server MCP.
Per aprire il file di configurazione, tocca Configura server MCP.

Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva:

  {
    "mcpServers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Dopo la connessione del server, viene visualizzato uno stato attivo verde.

Cursore

Crea la directory .cursor nella root del progetto, se non esiste.
Crea il file .cursor/mcp.json, se non esiste, e aprilo.

Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva:

  {
    "mcpServers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Apri Cursore e vai a Impostazioni>Impostazioni cursore > MCP. Quando il server si connette, viene visualizzato uno stato attivo verde.

VS Code (Copilot)

Apri VS Code e crea la directory .vscode nella root del progetto, se non esiste.
Crea il file .vscode/mcp.json, se non esiste, e aprilo.

Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva:

  {
    "servers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Windsurf

Apri Windsurf e vai all'assistente Cascade.
Per aprire il file di configurazione, fai clic sull'icona MCP e poi su Configura.

Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva:

  {
    "mcpServers": {
      "dataplex": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Utilizzare gli strumenti

Lo strumento AI è ora connesso a Knowledge Catalog. Prova a chiedere all'assistente AI di trovare alcuni asset di dati come set di dati BigQuery, istanze Cloud SQL e altri.

I seguenti strumenti sono disponibili per l'LLM:

dataplex_search_entries: cerca asset di dati
dataplex_lookup_entry: recupera un sottoinsieme specifico di metadati (ad esempio schema, utilizzo, panoramica attività e contatti) di un singolo asset di dati specifico
dataplex_search_aspect_types: cerca i tipi di aspetto
lookup_context: recupera un set di metadati avanzati preformattati relativi a uno o più asset di dati

(Facoltativo) Aggiungere istruzioni di sistema

Le istruzioni di sistema sono un modo per fornire linee guida specifiche all'LLM, aiutandolo a comprendere il contesto e a rispondere in modo più accurato. Configura le istruzioni di sistema in base al prompt di sistema consigliato.

Ad esempio, puoi aggiungere istruzioni per guidare l'LLM su come utilizzare gli strumenti di Knowledge Catalog:

Quando ti viene chiesto di trovare set di dati o tabelle, utilizza lo strumento dataplex_search_entries.
Se ti viene chiesto lo schema della tabella o i dettagli dei metadati, come le regole sulla qualità dei dati o la proprietà, utilizza lo strumento dataplex_lookup_entry.
Quando ti vengono chieste informazioni sulle regole o classificazioni di governance, inizia utilizzando dataplex_search_aspect_types per trovare i tipi di aspetto pertinenti.
Se per rispondere alle domande è necessario un set di metadati ampio, utilizza lo strumento dataplex_lookup_context per recuperarlo.

Per saperne di più su come configurare le istruzioni, consulta Utilizzare le istruzioni per ottenere modifiche AI che seguono lo stile di codifica.

Passaggi successivi

Cerca le risorse in Knowledge Catalog.
Scopri come importare origini personalizzate in Knowledge Catalog.
Scopri come gestire gli aspetti e arricchire i metadati.

Utilizzare Knowledge Catalog con MCP, Gemini e altri agenti Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Informazioni su Gemini CLI ed estensioni

Funzionamento delle estensioni

Informazioni sull'estensione Knowledge Catalog

Ruoli obbligatori

Autorizzazioni obbligatorie

Abilitare l'API Dataplex

Installare MCP Toolbox

Linux/amd64

macOS (Darwin)/arm64

macOS (Darwin)/amd64

Windows/amd64

Configurare client e connessioni

Estensione Gemini CLI

Gemini Code Assist

Claude Code

Claude Desktop

Cline

Cursore

VS Code (Copilot)

Windsurf

Utilizzare gli strumenti

(Facoltativo) Aggiungere istruzioni di sistema

Passaggi successivi

Utilizzare Knowledge Catalog con MCP, Gemini e altri agenti