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 la CLI Gemini. Il collegamento di Knowledge Catalog a questi strumenti consente il rilevamento dei dati basato sull'AI e la gestione degli asset direttamente all'interno dello strumento.

Per un'esperienza a riga di comando integrata, ti consigliamo di utilizzare l'estensione Knowledge Catalog dedicata per Gemini CLI. L'estensione raggruppa un 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 una MCP Toolbox per Database locale. Puoi quindi utilizzare gli agenti AI nel tuo 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:

Informazioni su Gemini CLI e le estensioni

Gemini CLI è un agente AI conversazionale open source di Google che accelera i workflow di sviluppo e aiuta con la programmazione, il debug, l'esplorazione dei dati e la 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.

Come funzionano le estensioni

Le estensioni ampliano le funzionalità di Gemini CLI, consentendole di connettersi e controllare servizi Google Cloud specifici e altri strumenti. Forniscono a Gemini il contesto e la comprensione dell'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. Queste sono separate dalle estensioni IDE, come Gemini Code Assist, che si integrano utilizzando MCP Toolbox.

Informazioni sull'estensione Knowledge Catalog

L'estensione Knowledge Catalog per Gemini CLI integra l'AI nelle attività di governance e scoperta 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
Individuazione e governance dei dati 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 data lake marketing in Knowledge Catalog.
lookup_entry
  • Qual è lo schema della tabella orders?
  • Descrivi le regole sulla qualità dei dati applicate al database customer.
  • Chi è indicato come proprietario dell'attività per la tabella customer_details?
search_aspect_types
  • Mostrami i tipi di aspetto correlati 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?
Grounding dell'LLM con il contesto lookup_context (preview)
  • Descrivi l'asset di dati orders.
  • Scrivi una query SQL che conteggi la quantità di utenti per paese.
  • Scrivi la pipeline di dati che pulisce la tabella products.

Per saperne di più sull'estensione Knowledge Catalog, consulta la sezione 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 sul tuo progetto:

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 connettersi 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 connettersi 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

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

    Vai al selettore di progetti

  2. 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 per il quale ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

  3. Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .

  4. Abilitare l'API Dataplex.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilitare l'API

  5. Se utilizzi una shell locale, crea credenziali di autenticazione locali per il tuo account utente: 

    gcloud auth application-default login

    Non è necessario 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.

Installa MCP Toolbox

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

  1. Scarica l'ultima versione di MCP Toolbox come file binario. Seleziona il file binario che corrisponde 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/mcp-toolbox-for-databases/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/mcp-toolbox-for-databases/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/mcp-toolbox-for-databases/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/mcp-toolbox-for-databases/VERSION/windows/amd64/toolbox

    Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.31.0.

  2. Rendi eseguibile il file binario:

    chmod +x toolbox

  3. 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 è necessario installare o configurare MCP Toolbox, in quanto questi strumenti includono le funzionalità del server richieste. Per le istruzioni di configurazione, consulta le schede Estensione Gemini Code Assist o Gemini CLI.

Per altri strumenti e IDE compatibili con MCP, devi prima installare MCP Toolbox. Il 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 i tuoi strumenti di AI. Dopo l'installazione, seleziona la scheda dello strumento specifico per visualizzare le istruzioni di configurazione.

Estensione Gemini CLI

Questo metodo utilizza l'estensione knowledge-catalog dedicata per lo strumento Gemini CLI autonomo e non utilizza MCP Toolbox.

  1. Installa la Gemini CLI.
  2. Installa l'estensione Knowledge Catalog per Gemini CLI dal repository GitHub: 
    gemini extensions install https://github.com/gemini-cli-extensions/knowledge-catalog
  3. 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 .

  4. Avvia Gemini CLI in modalità interattiva: 
    gemini
     La CLI carica automaticamente l'estensione Knowledge Catalog e i relativi strumenti, che puoi utilizzare per interagire con i tuoi asset di dati.

Gemini Code Assist

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

  1. In VS Code, installa l'estensione Gemini Code Assist.
  2. Attiva la modalità Agente nella chat di Gemini Code Assist.
  3. Nella directory di lavoro, crea una cartella denominata .gemini. Al suo interno, crea un file settings.json.
  4. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Claude Code

  1. Installa Claude Code.
  2. Crea il file .mcp.json nella directory root del progetto, se non esiste.
  3. Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Claude desktop

  1. Apri Claude Desktop e vai a Impostazioni.
  2. Per aprire il file di configurazione, nella scheda Sviluppatore, fai clic su Modifica configurazione.
  3. Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }
  4. Riavvia Claude desktop.
    Nella nuova schermata di chat viene visualizzata un'icona MCP con il nuovo server MCP.

Cline

  1. In VS Code, apri l'estensione Cline e poi fai clic sull'icona MCP Servers.
  2. Per aprire il file di configurazione, tocca Configura server MCP.
  3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }
    Dopo la connessione riuscita del server, viene visualizzato uno stato attivo verde.

Cursore

  1. Crea la directory .cursor nella root del progetto se non esiste.
  2. Crea il file .cursor/mcp.json se non esiste e aprilo.
  3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }
  4. Apri Cursore e vai a Impostazioni > Impostazioni cursore > MCP. Quando il server si connette, viene visualizzato uno stato attivo verde.

VS Code (Copilot)

  1. Apri VS Code e crea la directory .vscode nella root del progetto se non esiste.
  2. Crea il file .vscode/mcp.json se non esiste e aprilo.
  3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "servers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Windsurf

  1. Apri Windsurf e vai all'assistente Cascade.
  2. Per aprire il file di configurazione, fai clic sull'icona MCP, quindi fai clic su Configura.
  3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Utilizzare gli strumenti

Il tuo strumento di 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.

Sono disponibili i seguenti strumenti per il LLM:

  • search_entries: cerca asset di dati
  • lookup_entry: recupera i metadati (ad esempio schema, utilizzo, panoramica attività e contatti) degli asset di dati
  • search_aspect_types: cerca i tipi di aspetto
  • lookup_context (anteprima): recupera un insieme preformattato di metadati relativi a una o più risorse di dati

(Facoltativo) Aggiungi 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 del Knowledge Catalog:

  • Quando ti viene chiesto di trovare set di dati o tabelle, utilizza lo strumento search_entries.
  • Se ti vengono richiesti dettagli sullo schema della tabella o sui metadati, come regole di qualità dei dati o proprietà, utilizza lo strumento lookup_entry.
  • Quando ti vengono chieste regole di governance o classificazioni, inizia utilizzando search_aspect_types per trovare tipi di aspetti pertinenti.
  • Se rispondere alle domande richiede un ampio insieme di metadati, utilizza lo strumento lookup_context per recuperarli.

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

Passaggi successivi