Zestaw narzędzi MCP do obsługi baz danych: udostępnianie zbiorów danych BigQuery klientom MCP
Informacje o tym ćwiczeniu (w Codelabs)
1. Wprowadzenie
W tym laboratorium kodu użyjesz narzędzia MCP do obsługi baz danych, aby udostępnić zbiory danych BigQuery.
W ramach tego ćwiczenia będziesz wykonywać czynności krok po kroku:
- Określ konkretny zbiór danych BigQuery („Informacje o aktualizacjach Google Cloud”) z publicznego programu zbiorów danych BigQuery.
- Skonfiguruj narzędzie MCP dla baz danych, które łączy się ze zbiorem danych BigQuery.
- Utwórz agenta za pomocą pakietu narzędzi dla deweloperów agentów (ADK), który będzie korzystać z MCP Toolbox do odpowiadania na pytania użytkowników dotyczące informacji o aktualizacjach Google Cloud.
Co musisz zrobić
- Skonfiguruj narzędzia MCP dla baz danych, aby udostępnić informacje o wersjach Google Cloud, czyli publiczny zbiór danych BigQuery, jako interfejs MCP dla innych klientów MCP (IDE, narzędzia itp.).
Czego się nauczysz
- Przeglądaj publiczne zbiory danych BigQuery i wybierz konkretny zbiór danych.
- Skonfiguruj narzędzia MCP dla baz danych dla publicznego zbioru danych BigQuery, który chcesz udostępnić klientom MCP.
- Zaprojektuj i opublikuj agenta za pomocą pakietu narzędzi dla deweloperów agentów (ADK), aby odpowiadał na pytania użytkowników.
- przetestuj narzędzia agenta i MCP do obsługi baz danych w środowisku lokalnym;
Czego potrzebujesz
- przeglądarka Chrome;
- Lokalne środowisko programistyczne Pythona.
2. Zanim zaczniesz
Utwórz projekt
- W konsoli Google Cloud na stronie selektora projektu wybierz lub utwórz projekt Google Cloud.
- Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności .
- Użyjesz Cloud Shell, czyli środowiska wiersza poleceń działającego w Google Cloud, które jest wstępnie wczytane w bq. Kliknij Aktywuj Cloud Shell u góry konsoli Google Cloud.
- Po połączeniu z Cloud Shell sprawdź, czy jesteś już uwierzytelniony i czy projekt jest ustawiony na identyfikator Twojego projektu, używając tego polecenia:
gcloud auth list
- Aby sprawdzić, czy polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:
gcloud config list project
- Jeśli projekt nie jest ustawiony, użyj tego polecenia:
gcloud config set project <YOUR_PROJECT_ID>
Informacje o poleceniach i użytkowaniu gcloud znajdziesz w dokumentacji.
3. Zbiór danych z informacjami o wersjach Google i klienci MCP
Najpierw przyjrzyjmy się informacjom o wersjach Google Cloud, które są regularnie aktualizowane na oficjalnej stronie z informacjami o wersjach Google Cloud. Poniżej znajduje się zrzut ekranu tej strony:
Możesz zasubskrybować adres URL kanału, ale czy nie lepiej zapytać o te informacje na czacie z pracownikiem obsługi klienta? Może to być proste zapytanie, np. „Pokaż mi informacje o wersjach Google Cloud”.
4. Zestaw narzędzi MCP dla baz danych
MCP Toolbox for Databases to serwer MCP typu open source przeznaczony do baz danych. Został zaprojektowany z myślą o jakości na poziomie przedsiębiorstwa i produkcji. Dzięki temu możesz tworzyć narzędzia łatwiej, szybciej i bezpieczniej, ponieważ biblioteka ta obsługuje złożone zadania, takie jak łączenie połączeń i uwierzytelnianie.
Toolbox pomaga Ci tworzyć narzędzia oparte na generatywnej AI, które umożliwiają pracownikom obsługi klienta dostęp do danych w Twojej bazie danych. Zestaw narzędzi zawiera:
- Uproszczone tworzenie: integracja narzędzi z agentem w mniej niż 10 wierszach kodu, możliwość ponownego użycia narzędzi w różnych agentach lub ramach oraz łatwiejsze wdrażanie nowych wersji narzędzi.
- Większa wydajność: sprawdzone metody, takie jak grupowanie połączeń, uwierzytelnianie i inne.
- Ulepszone zabezpieczenia: zintegrowana autoryzacja zapewniająca bezpieczniejszy dostęp do danych
- Całkowita obserwowalność: gotowe wskaźniki i śledzenie z wbudowanym wsparciem dla OpenTelemetry.
- Toolbox ułatwia łączenie baz danych z dowolnymi asystentami AI obsługującymi MCP, nawet tymi, które są dostępne w Twoim IDE.
Toolbox znajduje się między systemem sterowania aplikacji a bazą danych. Zapewnia on płaszczyznę kontrolną, która służy do modyfikowania, rozpowszechniania i wywoływania narzędzi. Ułatwia zarządzanie narzędziami, ponieważ zapewnia scentralizowane miejsce do przechowywania i aktualizowania narzędzi. Umożliwia też udostępnianie narzędzi między pracownikami i aplikacji oraz aktualizowanie tych narzędzi bez konieczności ponownego wdrażania aplikacji.
Aby podsumować w prostych słowach:
- MCP Toolbox jest dostępny jako binarne, obraz kontenera lub możesz go skompilować z źródła.
- Udostępnia on zestaw narzędzi, które konfigurujesz za pomocą pliku tools.yaml. Można je połączyć ze swoimi źródłami danych. Możesz zobaczyć różne obsługiwane źródła danych : AlloyDB, BigQuery itp.
- Ponieważ ta skrzynka narzędzi obsługuje teraz MCP, automatycznie masz punkt końcowy serwera MCP, którego mogą używać agenci (IDE), lub możesz go używać podczas tworzenia aplikacji agenta za pomocą różnych frameworków, takich jak pakiet narzędzi do tworzenia agentów (ADK).
W tym poście na blogu skupimy się na tych kwestiach:
Podsumowując, w narzędziu MCP Toolbox dla baz danych utworzymy konfigurację, która wie, jak nawiązać połączenie z naszym zbiorem danych BigQuery. Następnie za pomocą pakietu narzędzi dla agentów (ADK) opracujemy agenta, który zostanie zintegrowany z punktem końcowym MCP Toolbox i umożliwi nam wysyłanie zapytań w języku naturalnym dotyczących naszego zbioru danych. Wyobraź sobie, że jest to aplikacja agentowa, która wie, jak komunikować się ze zbiorem danych BigQuery i wykonywywać niektóre zapytania.
5. Zbiór danych BigQuery dla Google Cloud – informacje o zmianach
Program publicznych zbiorów danych Google Cloud udostępnia zbiory danych na potrzeby aplikacji. Jednym z takich zbiorów danych jest baza danych z informacjami o wersjach Google Cloud. Ten zbiór danych zawiera te same informacje co oficjalna strona z informacjami o aktualizacjach Google Cloud i jest dostępny jako publiczny zbiór danych, do którego można kierować zapytania.
Na potrzeby testu po prostu weryfikuję zbiór danych, uruchamiając proste zapytanie:
SELECT
product_name,description,published_at
FROM
`bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
WHERE
DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
GROUP BY product_name,description,published_at
ORDER BY published_at DESC
Dzięki temu otrzymuję listę rekordów z danych w zbiorze Uwagi o wydańach, które zostały opublikowane w ciągu ostatnich 7 dni.
Zastąp go dowolnym innym zbiorem danych i odpowiednimi zapytaniami i parametrami. Teraz musimy skonfigurować to jako źródło danych i narzędzie w Toolboxie MCP dla baz danych. Zobaczmy, jak to zrobić.
6. Instalowanie MCP Toolbox for Databases
Otwórz terminal na komputerze lokalnym i utwórz folder o nazwie mcp-toolbox
.
mkdir mcp-toolbox
Otwórz folder mcp-toolbox
za pomocą tego polecenia:
cd mcp-toolbox
Zainstaluj binarną wersję MCP Toolbox for Databases za pomocą podanego poniżej skryptu. Podane niżej polecenie jest przeznaczone do systemu Linux, ale jeśli używasz systemu Mac lub Windows, upewnij się, że pobierasz prawidłowy plik binarny. Otwórz stronę wersji dla swojego systemu operacyjnego i architektury i pobierz odpowiedni plik binarny.
export VERSION=0.7.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Mamy już gotową wersję binarną narzędzia. Następnym krokiem jest skonfigurowanie narzędzia za pomocą naszych źródeł danych i innych konfiguracji.
7. Konfigurowanie narzędzia MCP do obsługi baz danych
Teraz musimy zdefiniować zbiór danych BigQuery i narzędzia w pliku tools.yaml
, który jest potrzebny do korzystania z MCP Toolbox for Database. Plik tools.yaml
jest głównym sposobem konfigurowania Toolboxa.
Utwórz plik o nazwie tools.yaml
w tym samym folderze, czyli mcp-toolbox
. Jego treść została podana poniżej.
Możesz użyć edytora nano, który jest dostępny w Cloud Shell. Polecenie nano to „nano tools.yaml
”.
Pamiętaj, aby zastąpić wartość YOUR_PROJECT_ID
identyfikatorem projektu Google Cloud.
sources:
my-bq-source:
kind: bigquery
project: YOUR_PROJECT_ID
tools:
search_release_notes_bq:
kind: bigquery-sql
source: my-bq-source
statement: |
SELECT
product_name,description,published_at
FROM
`bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
WHERE
DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
GROUP BY product_name,description,published_at
ORDER BY published_at DESC
description: |
Use this tool to get information on Google Cloud Release Notes.
toolsets:
my_bq_toolset:
- search_release_notes_bq
Abyśmy mogli szybko zrozumieć plik:
- Źródła to różne źródła danych, z którymi narzędzie może wchodzić w interakcje. Źródło reprezentuje źródło danych, z którym narzędzie może wchodzić w interakcję. Źródła możesz zdefiniować jako mapę w sekcji źródeł w pliku tools.yaml. Konfiguracja źródła zawiera zwykle wszystkie informacje potrzebne do połączenia z bazą danych i interakcji z nią. W naszym przypadku zdefiniowaliśmy źródło BigQuery
my-bq-source
i musisz podać identyfikator projektu Google Cloud. Więcej informacji znajdziesz w materiałach źródłowych. - Narzędzia definiują działania, które może wykonywać agent, np. odczytywanie i zapisywanie w źródle. Narzędzie reprezentuje działanie, które może wykonać agent, np. uruchomienie instrukcji SQL. Narzędzia możesz zdefiniować jako mapę w sekcji narzędzi w pliku tools.yaml. Zwykle narzędzie wymaga źródła danych. W naszym przypadku definiujemy pojedyncze narzędzie
search_release_notes_bq
. Odwołuje się on do źródła BigQuerymy-bq-source
zdefiniowanego w pierwszym kroku. Zawiera ona też oświadczenie i instrukcje, których będą używać klienci agenta AI. Więcej informacji znajdziesz w narzędziach. - Na koniec mamy zestaw narzędzi, który pozwala definiować grupy narzędzi, które chcesz wczytywać razem. Może to być przydatne do definiowania różnych grup na podstawie agenta lub aplikacji. W naszym przypadku definicja zestawu narzędzi zawiera obecnie tylko jedno zdefiniowane przez nas narzędzie
search_release_notes_bq
. Możesz mieć więcej niż 1 zestaw narzędzi, który zawiera kombinację różnych narzędzi.
Obecnie mamy zdefiniowane tylko 1 narzędzie, które zgodnie z zapytaniem pobiera informacje o ostatnich 7 dniach. Możesz też stosować różne kombinacje parametrów.
Więcej informacji o konfiguracji ( źródło i narzędzia) znajdziesz w konfiguracji źródła danych BigQuery w narzędziu MCP Toolbox dla baz danych.
8. Testowanie narzędzi MCP do obsługi baz danych
Pobrana i skonfigurowana została Toolbox za pomocą pliku tools.yaml
w folderze mcp-toolbox
. Najpierw uruchom go lokalnie.
Uruchom to polecenie:
./toolbox --tools-file="tools.yaml"
Po pomyślnym wykonaniu polecenia powinieneś zobaczyć uruchamianie serwera z przykładowymi danymi wyjściowymi podobnymi do tych poniżej:
2025-06-17T07:48:52.989710733Z INFO "Initialized 1 sources."
2025-06-17T07:48:52.989805642Z INFO "Initialized 0 authServices."
2025-06-17T07:48:52.989847035Z INFO "Initialized 1 tools."
2025-06-17T07:48:52.989889742Z INFO "Initialized 2 toolsets."
2025-06-17T07:48:52.990357879Z INFO "Server ready to serve!"
Serwer MCP Toolbox działa domyślnie na porcie 5000
. Jeśli okaże się, że port 5000
jest już używany, możesz użyć innego portu (np. 7000
) zgodnie z poleceniem pokazanym poniżej. W kolejnych poleceniach zamiast portu 5000
używaj portu 7000
.
./toolbox --tools-file "tools.yaml" --port 7000
Zweryfikujmy to za pomocą Cloud Shell.
W Cloud Shell kliknij Podgląd w przeglądarce, jak pokazano poniżej:
Kliknij Zmień port, ustaw port na 5000, jak pokazano poniżej, i kliknij Zmień i wyświetl podgląd.
Powinny się wyświetlić te dane wyjściowe:
W adresie URL przeglądarki dodaj na końcu:
/api/toolset
Powinny się wyświetlić obecnie skonfigurowane narzędzia. Poniżej znajdziesz przykładowe dane wyjściowe:
{
"serverVersion": "0.7.0+binary.linux.amd64.714d990c34ee990e268fac1aa6b89c4883ae5023",
"tools": {
"search_release_notes_bq": {
"description": "Use this tool to get information on Google Cloud Release Notes.\n",
"parameters": [],
"authRequired": []
}
}
}
Zestaw narzędzi MCP do obsługi baz danych zawiera opis sposobu weryfikowania i testowania narzędzi za pomocą Pythona. Dokumentacja jest dostępna tutaj. Pomijamy to i w następnej sekcji przechodzimy bezpośrednio do pakietu narzędzi dewelopera (ADK), który wykorzystuje te narzędzia.
9. Tworzenie agenta za pomocą pakietu narzędzi dla programistów
Instalowanie zestawu do tworzenia aplikacji (ADK)
Otwórz nową kartę terminala w Cloud Shell i utwórz folder o nazwie my-agents
w następujący sposób: Przejdź też do folderu my-agents
.
mkdir my-agents
cd my-agents
Teraz utwórz wirtualne środowisko Pythona za pomocą venv
w ten sposób:
python -m venv .venv
Aby aktywować środowisko wirtualne:
source .venv/bin/activate
Zainstaluj pakiety ADK i MCP Toolbox for Databases wraz z zależnościami łańcucha językowego w ten sposób:
pip install google-adk toolbox-core
Teraz możesz wywołać narzędzie adk
w ten sposób.
adk
Wyświetli się lista poleceń.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
create Creates a new app in the current folder with prepopulated agent template.
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
Tworzenie pierwszej aplikacji agenta
Teraz użyjemy skryptu adk
, aby utworzyć szkielet aplikacji agenta z komunikatami o wersjach Google Cloud za pomocą polecenia adk
create
z nazwą aplikacji **(gcp-releasenotes-agent-app)
**podaną poniżej.
adk create gcp-releasenotes-agent-app
Wykonaj te czynności i wybierz:
- Model Gemini do wyboru modelu dla głównego agenta.
- Jako backend wybierz Vertex AI.
- Wyświetli się domyślny identyfikator projektu Google i region. Wybierz domyślną opcję.
Choose a model for the root agent:
1. gemini-2.0-flash-001
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [YOUR_GOOGLE_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in ../my-agents/gcp-releasenotes-agent-app:
- .env
- __init__.py
- agent.py
Sprawdź folder, w którym utworzono domyślny szablon i pliki wymagane do działania agenta.
Najpierw plik .env
. Poniżej znajdziesz jego treść:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
Wartości te wskazują, że będziemy używać Gemini przez Vertex AI, a także zawierają odpowiednie wartości identyfikatora projektu i lokalizacji Google Cloud.
Następnie mamy plik __init__.py
, który oznacza folder jako moduł i zawiera pojedyncze polecenie, które importuje agenta z pliku agent.py
.
from . import agent
Na koniec przyjrzyjmy się plikowi agent.py
. Treści:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
To najprostszy agent, jaki można napisać za pomocą ADK. Jak czytamy na stronie z dokumentacją ADK, agent to samodzielna jednostka wykonawcza, która działa autonomicznie, aby osiągać określone cele. Może wykonywać zadania, wchodzić w interakcje z użytkownikami, korzystać z zewnętrznych narzędzi i współdziałać z innymi agentami.
W szczególności LLMAgent, który jest często nazywany po prostu „asystentem”, wykorzystuje duże modele językowe (LLM) jako główny mechanizm do rozumienia języka naturalnego, rozumowania, planowania, generowania odpowiedzi i dynamicznego podejmowania decyzji o tym, jak postępować lub których narzędzi używać. Dzięki temu jest idealny do wykonywania elastycznych zadań związanych z językiem. Więcej informacji o agentach LLM znajdziesz tutaj.
To kończy tworzenie szablonu podstawowego agenta za pomocą pakietu ADK. Teraz połączymy naszego agenta z MCP Toolbox, aby mógł on używać tego narzędzia do odpowiadania na pytania użytkownika (w tym przypadku będą to informacje o aktualizacjach Google Cloud).
10. Łączenie pracownika obsługi klienta z narzędziami
Teraz połączymy tego pracownika obsługi klienta z zespołem narzędzi. W kontekście ADK narzędzie reprezentuje określoną funkcję udostępnioną agentowi AI, która umożliwia mu wykonywanie działań i nawiązywanie interakcji ze światem poza jego podstawowymi możliwościami generowania tekstu i rozumowania.
W naszym przypadku chcemy teraz wyposażyć naszego agenta w narzędzia skonfigurowane w Toolboxie MCP dla baz danych.
Zmodyfikuj plik agent.py
, dodając do niego ten kod. Pamiętaj, że w kodzie używamy domyślnego portu 5000, ale jeśli używasz innego portu, użyj go.
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load all the tools
tools = toolbox.load_toolset('my_bq_toolset')
root_agent = Agent(
name="gcp_releasenotes_agent",
model="gemini-2.0-flash",
description=(
"Agent to answer questions about Google Cloud Release notes."
),
instruction=(
"You are a helpful agent who can answer user questions about the Google Cloud Release notes. Use the tools to answer the question"
),
tools=tools,
)
Możemy teraz przetestować agenta, który pobiera prawdziwe dane ze zbioru danych BigQuery skonfigurowanego za pomocą MCP Toolbox for Databases.
Aby to zrobić:
W jednym terminalu Cloud Shell uruchom narzędzia MCP dla baz danych. Może ona już działać lokalnie na porcie 5000, jak to miało miejsce podczas wcześniejszego testowania. Jeśli nie, uruchom to polecenie (z folderu mcp-toolbox
), aby uruchomić serwer:
./toolbox --tools_file "tools.yaml"
W idealnej sytuacji powinieneś zobaczyć, że serwer mógł połączyć się z naszym źródłem danych i wczytał zestaw narzędzi. Poniżej znajdziesz przykładowe dane wyjściowe:
./toolbox --tools-file "tools.yaml"
2025-06-17T07:48:52.989710733Z INFO "Initialized 1 sources."
2025-06-17T07:48:52.989805642Z INFO "Initialized 0 authServices."
2025-06-17T07:48:52.989847035Z INFO "Initialized 1 tools."
2025-06-17T07:48:52.989889742Z INFO "Initialized 2 toolsets."
2025-06-17T07:48:52.990357879Z INFO "Server ready to serve!"
Gdy serwer MCP zostanie uruchomiony, w innym terminalu uruchom agenta za pomocą polecenia adk run
(z folderu my-agents
), jak pokazano poniżej. Możesz też użyć polecenia adk web
.
$ adk run gcp-releasenotes-agent-app/
Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent gcp_releasenotes_agent, type exit to exit.
[user]: get me the google cloud release notes
[gcp_releasenotes_agent]: Here are the Google Cloud Release Notes.
Google SecOps SOAR: Release 6.3.49 is being rolled out to the first phase of regions. This release contains internal and customer bug fixes. Published: 2025-06-14
Compute Engine: Dynamic NICs let you add or remove network interfaces to or from an instance without having to restart or recreate the instance. You can also use Dynamic NICs when you need more network interfaces. The maximum number of vNICs for most machine types in Google Cloud is 10; however, you can configure up to 16 total interfaces by using Dynamic NICs. Published: 2025-06-13
Compute Engine: General purpose C4D machine types, powered by the fifth generation AMD EPYC processors (Turin) and Google Titanium, are generally available. Published: 2025-06-13
Google Agentspace: Google Agentspace Enterprise: App-level feature management. As an Agentspace administrator, you can choose to turn the following features on or off for your end users in the web app: Agents gallery, Prompt gallery, No-code agent, NotebookLM Enterprise. Published: 2025-06-13
Cloud Load Balancing: Cloud Load Balancing supports load balancing to multi-NIC instances that use Dynamic NICs. This capability is in Preview. Published: 2025-06-13
Virtual Private Cloud: Dynamic Network Interfaces (NICs) are available in Preview. Dynamic NICs let you update an instance to add or remove network interfaces without having to restart or recreate the instance. Published: 2025-06-13
Security Command Center: The following Event Threat Detection detectors for Vertex AI have been released to Preview:
- `Persistence: New Geography for AI Service`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Admin Activity`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Data Access`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Admin Activity`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Data Access`
- `Privilege Escalation: Anomalous Impersonation of Service Account for AI Admin Activity`
- `Persistence: New AI API Method`
......
......
Zwróć uwagę, że agent korzysta z narzędzia skonfigurowanego w narzędziowcu MCP dla baz danych (search_release_notes_bq
) i pobiera dane ze zbioru danych BigQuery, a następnie formatuje odpowiedź.
11. Gratulacje
Gratulacje! Konfiguracja MCP Toolbox dla baz danych i konfiguracja zbioru danych BigQuery na potrzeby dostępu w ramach klientów MCP zostały zakończone.