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 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 le competenze sottostanti direttamente nell'estensione, il che semplifica l'installazione e la configurazione.

In alternativa, puoi connettere altri IDE e strumenti per sviluppatori che supportano MCP utilizzando una versione locale di MCP Toolbox for Databases. 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 a Model Context Protocol.

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

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.

Come funzionano le estensioni Gemini CLI?

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 nuove competenze, comandi slash e prompt. Questi sono separati dalle estensioni IDE, come Gemini Code Assist, che si integrano utilizzando MCP Toolbox.

Quali strumenti MCP fornisce Knowledge Catalog?

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

Per tutte le competenze disponibili, consulta le competenze di Knowledge Catalog su GitHub.

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 saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni obbligatorie 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 le competenze 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 Google Cloud console, 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 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.

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

  4. Abilita l'API Dataplex.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

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

  1. 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/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 autonomo, 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 knowledge-catalog dedicata per lo strumento Gemini CLI autonomo e non utilizza MCP Toolbox.

  1. Installa il 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 tuo progetto Knowledge Catalog: 
    export DATAPLEX_PROJECT="PROJECT_ID"
     Sostituisci quanto segue:
    • PROJECT_ID: l' Google Cloud ID progetto.
  4. Avvia Gemini CLI in modalità interattiva: 
    gemini

    La CLI carica automaticamente l'estensione Knowledge Catalog e le relative competenze, che puoi utilizzare per interagire con il database.

    In Gemini CLI, utilizza il /extensions comando per verificare che l'estensione sia installata.

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. Imposta la variabile di ambiente per connetterti al tuo progetto Knowledge Catalog: 
    export DATAPLEX_PROJECT="PROJECT_ID"
     Sostituisci quanto segue:
    • PROJECT_ID: l' Google Cloud ID progetto.
  3. Avvia l'agente: 
    claude
  4. Installa il plug-in: 
    /plugin install knowledge-catalog@claude-plugins-official

Codex

  1. Installa il marketplace Data Agent Kit: 
    codex plugin marketplace add GoogleCloudPlatform/data-agent-kit
  2. Installa il plug-in Knowledge Catalog: 
    codex plugin install dataplex@data-agent-kit
  3. Configura le variabili di ambiente per connetterti al tuo progetto Knowledge Catalog: 
    export DATAPLEX_PROJECT="PROJECT_ID"
     Sostituisci quanto segue:
    • PROJECT_ID: l' Google Cloud ID progetto.
  4. (Facoltativo) Aggiorna il marketplace: 
    codex plugin marketplace upgrade data-agent-kit

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.
    La nuova schermata della chat mostra un'icona MCP con il nuovo server MCP.

Cline

  1. In VS Code, apri l'estensione Cline e fai clic sull'icona Server MCP.
  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 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 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 le competenze

L'assistente 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.

Per tutte le competenze disponibili, consulta le competenze di Knowledge Catalog su GitHub.

(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 le competenze di Knowledge Catalog:

  • Quando ti viene chiesto di trovare set di dati o tabelle, utilizza la competenza search_entries.
  • Se ti vengono chiesti dettagli sullo schema della tabella o sui metadati, come regole di qualità dei dati o proprietà, utilizza la competenza lookup_entry.
  • Quando ti vengono chieste regole o classificazioni di governance, inizia utilizzando search_aspect_types per trovare i tipi di aspetto pertinenti.
  • Se rispondere alle domande richiede un ampio set di metadati, utilizza la competenza 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