MCP Toolbox for Databases: предоставление клиентам MCP доступа к наборам данных BigQuery
О практической работе
1. Введение
В этой лабораторной работе вы будете использовать MCP Toolbox for Databases, чтобы сделать доступными ваши наборы данных BigQuery.
В ходе выполнения кодовой лаборатории вы будете использовать пошаговый подход следующим образом:
- Определите конкретный набор данных BigQuery («Примечания к выпуску Google Cloud») из общедоступной программы наборов данных BigQuery.
- Настройте MCP Toolbox для баз данных, который подключается к набору данных BigQuery.
- Разработайте агента с помощью Agent Development Kit (ADK), который будет использовать MCP Toolbox для ответа на запросы пользователей о Google Cloud. Заметки о выпуске
Что ты будешь делать?
- Настройте MCP Toolbox for Databases, чтобы предоставить примечания к выпуску Google Cloud, общедоступный набор данных BigQuery, в качестве интерфейса MCP для других клиентов MCP (IDE, инструменты и т. д.).
Чему вы научитесь
- Изучите общедоступные наборы данных BigQuery и выберите конкретный набор данных.
- Настройте MCP Toolbox for Databases для общедоступного набора данных BigQuery, который мы хотим сделать доступным для клиентов MCP.
- Спроектируйте и разработайте агента с помощью Agent Development Kit (ADK) для ответа на запросы пользователей.
- Протестируйте Agent и MCP Toolbox для баз данных в локальной среде.
Что вам понадобится
- Веб-браузер Chrome.
- Локальная среда разработки Python.
2. Прежде чем начать
Создать проект
- В Google Cloud Console на странице выбора проекта выберите или создайте проект Google Cloud.
- Убедитесь, что для вашего проекта Cloud включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .
- Вы будете использовать Cloud Shell , среду командной строки, работающую в Google Cloud, которая поставляется с предустановленной bq. Нажмите Активировать Cloud Shell в верхней части консоли Google Cloud.
- После подключения к Cloud Shell вы проверяете, что вы уже аутентифицированы и что проекту присвоен ваш идентификатор проекта, с помощью следующей команды:
gcloud auth list
- Выполните следующую команду в Cloud Shell, чтобы подтвердить, что команда gcloud знает о вашем проекте.
gcloud config list project
- Если ваш проект не настроен, используйте следующую команду для его настройки:
gcloud config set project <YOUR_PROJECT_ID>
Информацию о командах и использовании gcloud см. в документации .
3. Google Release Notes Dataset и клиенты MCP
Для начала давайте взглянем на заметки о выпуске Google Cloud, которые регулярно обновляются на официальной веб-странице заметок о выпуске Google Cloud , снимок экрана которой представлен ниже:
Вы можете подписаться на URL-адрес фида, но что, если мы могли бы просто спросить в нашем чате агентов об этих примечаниях к выпуску. Может быть, простой запрос типа «Обновите меня по примечаниям к выпуску Google Cloud».
4. MCP Toolbox для баз данных
MCP Toolbox for Databases — это сервер MCP с открытым исходным кодом для баз данных. Он был разработан с учетом корпоративного уровня и качества производства. Он позволяет вам разрабатывать инструменты проще, быстрее и безопаснее, обрабатывая такие сложности, как пул соединений, аутентификация и многое другое.
Toolbox помогает вам создавать инструменты Gen AI, которые позволяют вашим агентам получать доступ к данным в вашей базе данных. Toolbox обеспечивает:
- Упрощенная разработка: интегрируйте инструменты в свой агент менее чем в 10 строк кода, повторно используйте инструменты между несколькими агентами или фреймворками и с легкостью развертывайте новые версии инструментов.
- Лучшая производительность: лучшие практики, такие как пул соединений, аутентификация и многое другое.
- Повышенная безопасность: интегрированная аутентификация для более безопасного доступа к вашим данным
- Сквозное наблюдение: готовые метрики и трассировка со встроенной поддержкой OpenTelemetry.
- Toolbox позволяет легко подключать базы данных к любым помощникам на основе искусственного интеллекта с поддержкой MCP, даже к тем, которые находятся в вашей IDE.
Toolbox располагается между фреймворком оркестровки вашего приложения и вашей базой данных, предоставляя плоскость управления, которая используется для изменения, распространения или вызова инструментов. Он упрощает управление вашими инструментами, предоставляя вам централизованное место для хранения и обновления инструментов, позволяя вам совместно использовать инструменты между агентами и приложениями и обновлять эти инструменты без необходимости повторного развертывания вашего приложения.
Подведем итог простыми словами:
- MCP Toolbox доступен в виде двоичного образа контейнера, или вы можете собрать его из исходного кода.
- Он предоставляет набор инструментов, которые вы настраиваете через файл tools.yaml. Инструменты можно рассматривать как подключающиеся к вашим источникам данных. Вы можете видеть различные источники данных, которые он поддерживает: AlloyDB, BigQuery и т. д.
- Поскольку этот набор инструментов теперь поддерживает MCP, у вас автоматически появляется конечная точка сервера MCP, которую затем могут использовать агенты (IDE), или вы можете использовать их при разработке приложений агентов с использованием различных фреймворков, таких как Agent Development Kit (ADK).
В этой записи блога мы сосредоточимся на областях, выделенных ниже:
Подводя итог, мы собираемся создать конфигурацию в MCP Toolbox for Databases, которая знает, как подключиться к нашему набору данных BigQuery. Затем мы разработаем агента с помощью Agent Development Kit (ADK), который будет интегрироваться с конечной точкой MCP Toolbox и позволит нам отправлять естественные запросы, чтобы узнать о нашем наборе данных. Подумайте об этом как об агентском приложении, которое вы разрабатываете, которое знает, как общаться с вашим набором данных BigQuery, и оно выполняет некоторые запросы.
5. Заметки о выпуске набора данных BigQuery для Google Cloud
Программа Google Cloud Public Dataset Program — это программа, которая делает доступным ряд наборов данных для ваших приложений. Одним из таких наборов данных является база данных Google Cloud Release Notes. Этот набор данных предоставляет вам ту же информацию, что и официальная веб-страница Google Cloud Release Notes, и он доступен как общедоступный набор данных.
В качестве теста я просто проверяю набор данных, выполнив простой запрос, показанный ниже:
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
Это дает мне список записей из набора данных Release Notes, которые были опубликованы за последние 7 дней.
Замените это любым другим набором данных по вашему выбору и соответствующими запросами и параметрами, которые вам нужны. Все, что нам нужно сделать сейчас, это настроить это как источник данных и инструмент в MCP Toolbox for Databases. Давайте посмотрим, как это сделать.
6. Установка MCP Toolbox для баз данных
Откройте терминал на локальном компьютере и создайте папку с именем mcp-toolbox .
mkdir mcp-toolbox
Перейдите в папку mcp-toolbox с помощью команды, показанной ниже:
cd mcp-toolbox
Установите бинарную версию MCP Toolbox for Databases с помощью скрипта, указанного ниже. Команда, указанная ниже, предназначена для Linux, но если вы используете Mac или Windows, убедитесь, что вы загружаете правильный бинарник. Проверьте страницу релизов для вашей операционной системы и архитектуры и загрузите правильный бинарник.
export VERSION=0.7.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Теперь у нас есть готовая к использованию бинарная версия набора инструментов. Следующий шаг — настроить набор инструментов с нашими источниками данных и другими конфигурациями.
7. Настройка MCP Toolbox для баз данных
Теперь нам нужно определить наш набор данных BigQuery и инструменты в файле tools.yaml , который необходим MCP Toolbox for Database. Файл tools.yaml является основным способом настройки Toolbox.
Создайте файл с именем tools.yaml в той же папке, т.е. mcp-toolbox , содержимое которого показано ниже.
Вы можете использовать редактор nano, который доступен в Cloud Shell. Команда nano выглядит следующим образом: " nano tools.yaml ".
Не забудьте заменить значение YOUR_PROJECT_ID на идентификатор вашего проекта 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
Давайте кратко разберемся в этом файле:
- Источники представляют собой различные источники данных, с которыми может взаимодействовать инструмент. Источник представляет собой источник данных, с которым может взаимодействовать инструмент. Вы можете определить Источники как карту в разделе источников вашего файла tools.yaml. Обычно конфигурация источника будет содержать любую информацию, необходимую для подключения и взаимодействия с базой данных. В нашем случае мы определили источник BigQuery
my-bq-source, и вам необходимо указать свой идентификатор проекта Google Cloud. Для получения дополнительной информации обратитесь к справочнику Источники . - Инструменты определяют действия, которые может выполнять агент, например, чтение и запись в источник. Инструмент представляет действие, которое может выполнять ваш агент, например, запуск оператора SQL. Вы можете определить Инструменты как карту в разделе инструментов вашего файла tools.yaml. Обычно инструменту требуется источник для действия. В нашем случае мы определяем один инструмент
search_release_notes_bq. Он ссылается на источник BigQuerymy-bq-source, который мы определили на первом шаге. Он также содержит оператор и инструкцию, которые будут использоваться клиентами AI Agent. Для получения дополнительной информации обратитесь к справочнику Инструменты . - Наконец, у нас есть Toolset, который позволяет вам определять группы инструментов, которые вы хотите загружать вместе. Это может быть полезно для определения различных групп на основе агента или приложения. В нашем случае у нас есть определение toolset, где мы в настоящее время определили только один существующий инструмент
search_release_notes_bq, который мы определили. У вас может быть более одного toolset, который содержит комбинацию различных инструментов.
Итак, в настоящее время мы определили только один инструмент, который получает заметки о выпуске за последние 7 дней по запросу. Но вы также можете иметь различные комбинации с параметрами.
Ознакомьтесь с более подробной информацией о конфигурации ( Источник , Инструменты ) в конфигурации источника данных BigQuery в MCP Toolbox for Databases.
8. Тестирование MCP Toolbox для баз данных
Мы загрузили и настроили Toolbox с файлом tools.yaml в папке mcp-toolbox . Давайте сначала запустим его локально.
Выполните следующую команду:
./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!"
Сервер MCP Toolbox по умолчанию работает на порту 5000 Если вы обнаружите, что порт 5000 уже используется, смело используйте другой порт (например, 7000 ) в соответствии с командой, показанной ниже. Пожалуйста, используйте 7000 вместо порта 5000 в последующих командах.
./toolbox --tools-file "tools.yaml" --port 7000
Давайте воспользуемся Cloud Shell, чтобы это проверить.
Нажмите «Веб-просмотр» в Cloud Shell, как показано ниже:
Нажмите «Изменить порт» и установите порт на 5000, как показано ниже, затем нажмите «Изменить и просмотреть».
Это должно дать следующий результат:
В URL-адресе браузера добавьте в конец URL-адреса следующее:
/api/toolset
Это должно вывести инструменты, которые в данный момент настроены. Пример вывода показан ниже:
{
"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": []
}
}
}
MCP Toolkit for Databases описывает Pythonic-способ проверки и тестирования инструментов, который задокументирован здесь . Мы пропустим это и перейдем непосредственно к Agent Development Kit (ADK) в следующем разделе, где будут использоваться эти инструменты.
9. Написание нашего агента с помощью Agent Development Kit (ADK)
Установите комплект разработки агента (ADK)
Откройте новую вкладку терминала в Cloud Shell и создайте папку с именем my-agents следующим образом. Перейдите также в папку my-agents .
mkdir my-agents
cd my-agents
Теперь давайте создадим виртуальную среду Python с помощью venv следующим образом:
python -m venv .venv
Активируйте виртуальную среду следующим образом:
source .venv/bin/activate
Установите пакеты ADK и MCP Toolbox for Databases вместе с зависимостью langchain следующим образом:
pip install google-adk toolbox-core
Теперь вы сможете вызвать утилиту adk следующим образом.
adk
Он покажет вам список команд.
$ 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.
Создание нашего первого приложения-агента
Теперь мы собираемся использовать adk для создания каркаса для приложения Google Cloud Release Notes Agent Application с помощью команды adk create с именем приложения ** (gcp-releasenotes-agent-app) **, как указано ниже.
adk create gcp-releasenotes-agent-app
Следуйте инструкциям и выберите следующее:
- Модель Gemini для выбора модели корневого агента.
- Выберите Vertex AI в качестве бэкэнда.
- Будут отображены ваш идентификатор проекта Google по умолчанию и регион. Выберите саму настройку по умолчанию.
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
Обратите внимание на папку, в которой были созданы шаблон по умолчанию и необходимые файлы для Агента.
Первым идет файл .env . Содержимое которого показано ниже:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
Значения указывают на то, что мы будем использовать Gemini через Vertex AI вместе с соответствующими значениями для идентификатора и местоположения проекта Google Cloud.
Затем у нас есть файл __init__.py , который помечает папку как модуль и содержит единственный оператор, который импортирует агента из файла agent.py .
from . import agent
Наконец, давайте взглянем на файл agent.py . Содержимое показано ниже:
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',
)
Это самый простой агент, который вы можете написать с помощью ADK. На странице документации ADK агент — это самодостаточный исполнительный блок, предназначенный для автономной работы для достижения определенных целей. Агенты могут выполнять задачи, взаимодействовать с пользователями, использовать внешние инструменты и координировать работу с другими агентами.
В частности, LLMAgent, обычно именуемый Agent, использует Large Language Models (LLM) в качестве своего основного движка для понимания естественного языка, рассуждения, планирования, генерации ответов и динамического принятия решений о том, как действовать или какие инструменты использовать, что делает их идеальными для гибких, ориентированных на язык задач. Узнайте больше об LLM Agents здесь .
Это завершает нашу подготовку к созданию базового агента с использованием Agent Development Kit (ADK). Теперь мы собираемся подключить нашего агента к MCP Toolbox, чтобы он мог использовать этот инструмент для ответа на запросы пользователя (в данном случае это будут заметки о выпуске Google Cloud).
10. Подключение нашего агента к инструментам
Сейчас мы подключим этого Агента к Инструментам. В контексте ADK Инструмент представляет собой определенную возможность, предоставляемую агенту ИИ, позволяющую ему выполнять действия и взаимодействовать с миром за пределами его основных способностей по генерации текста и рассуждениям.
В нашем случае мы собираемся оснастить нашего агента инструментами, которые мы настроили в MCP Toolbox for Databases.
Измените файл agent.py следующим кодом. Обратите внимание, что мы используем порт по умолчанию 5000 в коде, но если вы используете альтернативный номер порта, используйте его.
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,
)
Теперь мы можем протестировать агента, который будет извлекать реальные данные из нашего набора данных BigQuery, настроенного с помощью MCP Toolbox for Databases.
Для этого выполните следующую последовательность:
В одном терминале Cloud Shell запустите MCP Toolbox for Databases. Возможно, он уже запущен локально на порту 5000, как мы тестировали ранее. Если нет, выполните следующую команду (из папки mcp-toolbox ), чтобы запустить сервер:
./toolbox --tools_file "tools.yaml"
В идеале вы должны увидеть вывод, что сервер смог подключиться к нашим источникам данных и загрузил набор инструментов и инструменты. Пример вывода приведен ниже:
./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!"
После успешного запуска сервера MCP запустите Агента в другом терминале с помощью команды adk run (из папки my-agents ), показанной ниже. Вы также можете использовать команду 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`
......
......
Обратите внимание, что агент использует инструмент, который мы настроили в MCP Toolbox для баз данных ( search_release_notes_bq ), и извлекает данные из набора данных BigQuery и соответствующим образом форматирует ответ.
11. Поздравления
Поздравляем, вы успешно настроили MCP Toolbox для баз данных и настроили набор данных BigQuery для доступа в клиентах MCP.