Menggunakan Knowledge Catalog dengan MCP, Gemini, dan agen lainnya

Halaman ini menjelaskan cara menghubungkan instance Knowledge Catalog (sebelumnya Dataplex Universal Catalog) ke alat developer seperti Gemini CLI. Menghubungkan Knowledge Catalog ke alat ini memungkinkan penemuan data dan pengelolaan aset yang didukung AI langsung dalam alat Anda.

Untuk pengalaman command line terintegrasi, sebaiknya gunakan ekstensi Knowledge Catalog khusus untuk Gemini CLI. Ekstensi ini menggabungkan server Model Context Protocol (MCP) yang mendasarinya, yang berfungsi sebagai perantara antara Gemini CLI dan Knowledge Catalog, sehingga tidak perlu penyiapan server terpisah.

Atau, Anda dapat menghubungkan IDE dan alat developer lain yang mendukung MCP dengan menggunakan MCP Toolbox for Databases lokal. Kemudian, Anda dapat menggunakan agen AI di IDE yang ada untuk menemukan aset data di Knowledge Catalog. Untuk mengetahui informasi selengkapnya tentang MCP, lihat Pengantar Model Context Protocol.

Panduan ini menunjukkan proses koneksi untuk alat berikut:

Tentang Gemini CLI dan ekstensi

Gemini CLI adalah agen AI percakapan open source dari Google yang mempercepat alur kerja pengembangan dan membantu coding, proses debug, eksplorasi data, dan pembuatan konten. Layanan ini menawarkan pengalaman berbasis agen untuk berinteraksi dengan layanan Data Cloud, seperti Knowledge Catalog, dan database open source populer lainnya.

Untuk mengetahui informasi selengkapnya tentang Gemini CLI, lihat dokumentasi Gemini CLI.

Cara kerja ekstensi

Ekstensi memperluas kemampuan Gemini CLI, sehingga dapat terhubung ke dan mengontrol layanan tertentu serta alat lainnya. Google Cloud Plugin ini memberikan konteks dan pemahaman API kepada Gemini, sehingga memungkinkan interaksi percakapan. Anda dapat memuat ekstensi Gemini CLI dari URL GitHub, direktori lokal, atau registry. Ekstensi ini menawarkan alat, perintah garis miring, dan perintah baru. Alat ini terpisah dari ekstensi IDE, seperti Gemini Code Assist, yang terintegrasi menggunakan MCP Toolbox.

Tentang ekstensi Knowledge Catalog

Ekstensi Knowledge Catalog untuk Gemini CLI mengintegrasikan AI ke dalam tugas tata kelola dan penemuan data Anda. Anda dapat berinteraksi dengan Knowledge Catalog menggunakan perintah bahasa alami di terminal. Berikut beberapa contohnya:

Kategori Alat Contoh perintah bahasa alami
Penemuan dan tata kelola data search_entries
  • Temukan semua set data yang terkait dengan penjualan di Eropa.
  • Tampilkan tabel yang berisi PII pelanggan.
  • Buat daftar semua set data BigQuery di marketing lake di Knowledge Catalog.
lookup_entry
  • Apa skema tabel orders?
  • Jelaskan aturan kualitas data yang diterapkan ke database customer.
  • Siapa yang tercantum sebagai pemilik bisnis untuk tabel customer_details?
search_aspect_types
  • Tampilkan jenis aspek yang terkait dengan aturan kualitas data.
  • Mencantumkan semua jenis aspek yang digunakan untuk tata kelola data.
  • Apakah ada jenis aspek untuk menandai data PII?
Merujuk LLM dengan konteks lookup_context (preview)
  • Jelaskan aset data orders.
  • Tulis kueri SQL yang menghitung jumlah pengguna menurut negara.
  • Menulis pipeline data yang membersihkan tabel products.

Untuk mengetahui informasi selengkapnya tentang ekstensi Knowledge Catalog, lihat Ekstensi Gemini CLI - Knowledge Catalog.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk terhubung ke Knowledge Catalog menggunakan MCP Toolbox atau ekstensi Gemini CLI, minta administrator untuk memberi Anda peran IAM berikut di project Anda:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk terhubung ke Knowledge Catalog menggunakan MCP Toolbox atau ekstensi Gemini CLI. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk terhubung ke Knowledge Catalog menggunakan MCP Toolbox atau ekstensi Gemini CLI:

  • Untuk mengaktifkan API: serviceusage.services.enable
  • Untuk menggunakan alat Knowledge Catalog:
    • dataplex.projects.search
    • dataplex.entries.get
    • dataplex.aspectTypes.get
    • dataplex.aspectTypes.list

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Mengaktifkan Dataplex API

  1. Di konsol Google Cloud , buka halaman pemilih project.

    Buka pemilih project

  2. Pilih atau buat Google Cloud project.

    Peran yang diperlukan untuk memilih atau membuat project

    • Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
    • Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

  3. Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

  4. Mengaktifkan Dataplex API.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

    Mengaktifkan API

  5. Jika Anda menggunakan shell lokal, buat kredensial autentikasi lokal untuk akun pengguna Anda: 

    gcloud auth application-default login

    Anda tidak perlu melakukan langkah ini jika menggunakan Cloud Shell.

    Jika error autentikasi ditampilkan, dan Anda menggunakan penyedia identitas (IdP) eksternal, konfirmasi bahwa Anda telah login ke gcloud CLI dengan identitas gabungan Anda.

Menginstal MCP Toolbox

Anda tidak perlu menginstal MCP Toolbox jika hanya berencana menggunakan Gemini Code Assist atau ekstensi Gemini CLI, karena keduanya menggabungkan kemampuan server yang diperlukan. Untuk IDE dan alat lainnya, ikuti langkah-langkah di bagian ini untuk menginstal MCP Toolbox.

  1. Download MCP Toolbox versi terbaru sebagai program biner. Pilih biner yang sesuai dengan arsitektur CPU dan (OS) Anda. Anda harus menggunakan MCP Toolbox v0.31.0 atau yang lebih baru.

    Linux/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/linux/amd64/toolbox

    Ganti VERSION dengan versi MCP Toolbox, misalnya, v0.31.0.

    macOS (Darwin)/arm64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/arm64/toolbox

    Ganti VERSION dengan versi MCP Toolbox, misalnya, v0.31.0.

    macOS (Darwin)/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/amd64/toolbox

    Ganti VERSION dengan versi MCP Toolbox, misalnya, v0.31.0.

    Windows/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/windows/amd64/toolbox

    Ganti VERSION dengan versi MCP Toolbox, misalnya, v0.31.0.

  2. Jadikan biner sebagai file yang dapat dieksekusi:

    chmod +x toolbox

  3. Verifikasi penginstalannya:

    ./toolbox --version

    Penginstalan yang berhasil akan menampilkan nomor versi, misalnya, 0.15.0.

Menyiapkan klien dan koneksi

Bagian ini menjelaskan cara menghubungkan Knowledge Catalog ke alat Anda.

Jika Anda menggunakan Gemini Code Assist atau Gemini CLI mandiri, Anda tidak perlu menginstal atau mengonfigurasi MCP Toolbox, karena alat ini menggabungkan kemampuan server yang diperlukan. Untuk petunjuk penyiapan, lihat tab Ekstensi Gemini Code Assist atau Gemini CLI.

Untuk alat dan IDE lain yang kompatibel dengan MCP, Anda harus menginstal MCP Toolbox terlebih dahulu. Toolbox ini berfungsi sebagai server Model Context Protocol (MCP) open source yang berada di antara IDE dan Katalog Pengetahuan Anda, sehingga menyediakan bidang kontrol yang aman dan efisien untuk alat AI Anda. Setelah penginstalan, pilih tab untuk alat tertentu Anda guna melihat petunjuk konfigurasi.

Ekstensi Gemini CLI

Metode ini menggunakan ekstensi knowledge-catalog khusus untuk alat Gemini CLI mandiri, dan tidak menggunakan MCP Toolbox.

  1. Instal Gemini CLI.
  2. Instal ekstensi Knowledge Catalog untuk Gemini CLI dari repositori GitHub: 
    gemini extensions install https://github.com/gemini-cli-extensions/knowledge-catalog
  3. Tetapkan variabel lingkungan untuk terhubung ke project Knowledge Catalog Anda: 
    export DATAPLEX_PROJECT="PROJECT_ID"

    Ganti PROJECT_ID dengan project ID Google Cloud Anda.

  4. Mulai Gemini CLI dalam mode interaktif: 
    gemini
     CLI akan otomatis memuat ekstensi Knowledge Catalog dan alatnya, yang dapat Anda gunakan untuk berinteraksi dengan aset data Anda.

Gemini Code Assist

Gemini Code Assist menggabungkan kemampuan server MCP yang diperlukan, sehingga Anda tidak perlu menginstal MCP Toolbox secara terpisah.

  1. Di VS Code, instal ekstensi Gemini Code Assist.
  2. Aktifkan Mode Agen di chat Gemini Code Assist.
  3. Di direktori kerja Anda, buat folder bernama .gemini. Di dalamnya, buat file settings.json.
  4. Tambahkan konfigurasi berikut, ganti variabel lingkungan dengan nilai Anda, lalu simpan: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Kode Claude

  1. Instal Claude Code.
  2. Buat file .mcp.json di root project Anda, jika tidak ada.
  3. Tambahkan konfigurasi, ganti variabel lingkungan dengan nilai Anda, lalu simpan: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Claude desktop

  1. Buka Claude Desktop, lalu buka Setelan.
  2. Untuk membuka file konfigurasi, di tab Developer, klik Edit config.
  3. Tambahkan konfigurasi, ganti variabel lingkungan dengan nilai Anda, lalu simpan: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }
  4. Mulai ulang Claude desktop.
    Layar chat baru menampilkan ikon MCP dengan server MCP baru.

Cline

  1. Di VS Code, buka ekstensi Cline lalu klik ikon MCP Servers.
  2. Untuk membuka file konfigurasi, ketuk Configure MCP Servers.
  3. Tambahkan konfigurasi berikut, ganti variabel lingkungan dengan nilai Anda, lalu simpan: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }
    Status aktif hijau akan muncul setelah server berhasil terhubung.

Kursor

  1. Buat direktori .cursor di root project Anda jika belum ada.
  2. Buat file .cursor/mcp.json jika tidak ada dan buka file tersebut.
  3. Tambahkan konfigurasi berikut, ganti variabel lingkungan dengan nilai Anda, lalu simpan: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }
  4. Buka Kursor, lalu buka Setelan > Setelan Kursor > MCP. Status aktif berwarna hijau akan muncul saat server terhubung.

VS Code (Copilot)

  1. Buka VS Code dan buat direktori .vscode di root project Anda jika belum ada.
  2. Buat file .vscode/mcp.json jika tidak ada, lalu buka file tersebut.
  3. Tambahkan konfigurasi berikut, ganti variabel lingkungan dengan nilai Anda, lalu simpan: 
      {
    "servers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Windsurf

  1. Buka Windsurf dan buka asisten Cascade.
  2. Untuk membuka file konfigurasi, klik ikon MCP, lalu klik Configure.
  3. Tambahkan konfigurasi berikut, ganti variabel lingkungan dengan nilai Anda, lalu simpan: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Menggunakan alat

Alat AI Anda kini terhubung ke Knowledge Catalog. Coba minta asisten AI Anda untuk menemukan beberapa aset data seperti set data BigQuery, instance Cloud SQL, dan lainnya.

Alat berikut tersedia untuk LLM:

  • search_entries: menelusuri aset data
  • lookup_entry: mengambil metadata (misalnya, skema, penggunaan, ringkasan bisnis, dan kontak) aset data
  • search_aspect_types: menelusuri jenis aspek
  • lookup_context (pratinjau): mengambil set metadata lengkap yang telah diformat sebelumnya mengenai satu atau beberapa aset data

Opsional: Menambahkan petunjuk sistem

Petunjuk sistem adalah cara untuk memberikan panduan khusus kepada LLM, membantunya memahami konteks dan merespons dengan lebih akurat. Siapkan petunjuk sistem berdasarkan perintah sistem yang direkomendasikan.

Misalnya, Anda dapat menambahkan petunjuk untuk memandu LLM tentang cara menggunakan alat Katalog Pengetahuan:

  • Saat diminta untuk menemukan set data atau tabel, gunakan alat search_entries.
  • Jika diminta untuk memberikan detail skema atau metadata tabel seperti aturan kualitas data atau kepemilikan, gunakan alat lookup_entry.
  • Saat ditanya tentang aturan atau klasifikasi tata kelola, mulailah dengan menggunakan search_aspect_types untuk menemukan jenis aspek yang relevan.
  • Jika menjawab pertanyaan memerlukan kumpulan metadata yang luas, gunakan alat lookup_context untuk mengambilnya.

Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi petunjuk, lihat Menggunakan petunjuk untuk mendapatkan hasil edit AI yang mengikuti gaya coding Anda.

Langkah berikutnya