Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Как использовать AlloyDB Omni с MCP Toolbox для интеграции агентов

1. Введение

Чтобы предоставить ИИ-агентам, например Antigravity CLI, безопасный структурированный доступ к базе данных, вы можете интегрировать AlloyDB Omni с MCP Toolbox for Databases.

AlloyDB Omni – это доступная для скачивания контейнеризированная версия AlloyDB для PostgreSQL, которая может работать где угодно: локально, на рабочих станциях разработчиков, на периферии или в облаке. При этом она обеспечивает производительность и совместимость PostgreSQL корпоративного уровня.

MCP Toolbox for Databases – это сервер с открытым исходным кодом от Google, который реализует протокол контекста модели (MCP), чтобы упростить, ускорить и обезопасить создание инструментов на основе генеративного искусственного интеллекта, взаимодействующих с базами данных. Он находится между фреймворком оркестрации агента и базой данных и предоставляет следующие возможности:

Упрощенная разработка. Готовые или настраиваемые инструменты баз данных, которые подключаются к агенту с минимальной настройкой и могут повторно использоваться в нескольких агентах или фреймворках.
Повышенная производительность. Встроенные рекомендации, такие как пулы подключений и управление жизненным циклом.
Повышенная безопасность. Централизованное управление учетными данными и аутентификацией, благодаря которому агентам не требуются необработанные учетные данные базы данных.
Сквозная наблюдаемость. Готовые показатели и трассировка со встроенной поддержкой OpenTelemetry.

В конце этой практической работы у вас будет работающий контейнер AlloyDB Omni, заполненный примерами данных электронной торговли, сервер MCP Toolbox, предоставляющий 31 готовый инструмент администрирования и запросов AlloyDB Omni, и настроенный агент Antigravity CLI (agy), способный проверять схемы, выполнять SQL-запросы, анализировать планы запросов и диагностировать состояние базы данных с помощью запросов на естественном языке.

Схема архитектуры, показывающая сквозной рабочий процесс от агента до клиента MCP (Antigravity CLI), MCP Toolbox и AlloyDB Omni

Требования

Доступ к проекту Google Cloud и Cloud Shell из консоли Google Cloud или рабочей станции Linux.
Docker установлен и запущен.
Установлен клиент PostgreSQL psql.
curl и jq для настройки Antigravity CLI и MCP Toolbox.

Что вы узнаете

Как развернуть и запустить серверный контейнер базы данных AlloyDB Omni с помощью Docker.
Как создавать примеры таблиц, данных и индексов в AlloyDB Omni.
Как скачать, настроить и запустить MCP Toolbox for Databases со встроенным набором инструментов alloydb-omni.
Как настроить Antigravity CLI в качестве MCP-клиента для подключения к серверу MCP Toolbox.
Как использовать запросы на естественном языке в Antigravity CLI, чтобы проверять состояние базы данных, изучать схемы, выполнять SQL-запросы, анализировать планы запросов и проводить диагностику обслуживания.

Что вам понадобится

Рабочая среда терминала с Docker, psql, curl и jq. Вы можете использовать Google Cloud Shell, в котором эти инструменты уже установлены.

2. Настройка и требования

Настройка проекта

Создайте проект Google Cloud

В Google Cloud Console на странице выбора проекта выберите или создайте проект Google Cloud.
Убедитесь, что для вашего облачного проекта Google Cloud включены платежные функции. Подробнее о том, как проверить, включены ли платежные функции для проекта…

Запустить Cloud Shell

Хотя вы можете запустить AlloyDB Omni и MCP Toolbox локально на своем ноутбуке, в этой практической работе вы можете использовать Google Cloud Shell – среду командной строки, работающую в облаке, в которой предварительно установлены Docker, psql, curl и jq.

Значок для активации Cloud Shell

Откройте консоль Google Cloud и нажмите Активировать Cloud Shell на панели инструментов в правом верхнем углу.Вы также можете открыть Cloud Shell одним из следующих способов:
- Если вы используете консоль Google Cloud, нажмите G, а затем S.
- Откройте Cloud Shell.

Обычно подготовка и подключение к среде занимает несколько минут. После завершения операции вы увидите примерно следующее:

Терминал Google Cloud Shell, показывающий, что среда подключена

3. Подготовьте и запустите сервер базы данных AlloyDB Omni

В этом разделе вы извлечете и запустите контейнер AlloyDB Omni Docker и заполните его образцами данных электронной торговли для тестирования.

Запустите сервер базы данных AlloyDB Omni

Определите переменные среды для хоста, порта, базы данных, пользователя и сгенерированного пароля AlloyDB Omni:

export ALLOYDB_OMNI_HOST="127.0.0.1"
export ALLOYDB_OMNI_PORT="5432"
export ALLOYDB_OMNI_DATABASE="postgres"
export ALLOYDB_OMNI_USER="postgres"
export ALLOYDB_OMNI_PASSWORD="$(openssl rand -hex 8)@1aA"
echo "Your generated AlloyDB Omni postgres password is: $ALLOYDB_OMNI_PASSWORD"

Запустите контейнер AlloyDB Omni в фоновом режиме с помощью Docker:

docker run --name alloydbomni \
    -e POSTGRES_PASSWORD=$ALLOYDB_OMNI_PASSWORD \
    -p $ALLOYDB_OMNI_PORT:$ALLOYDB_OMNI_PORT \
    -d google/alloydbomni:latest

Убедитесь, что контейнер запущен и вы можете подключиться к серверу AlloyDB Omni с помощью psql:

docker ps -a
until docker exec alloydbomni pg_isready -U "$ALLOYDB_OMNI_USER" -d "$ALLOYDB_OMNI_DATABASE"; do sleep 2; done
PGPASSWORD=$ALLOYDB_OMNI_PASSWORD psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE -c "SELECT 1;"

Создайте тестовые данные

Создайте примеры таблиц categories, products, customers и orders, вставьте тестовые записи и создайте индексы, чтобы протестировать проверку схемы, SQL-запросы и планы выполнения запросов с помощью MCP Toolbox.

PGPASSWORD="$ALLOYDB_OMNI_PASSWORD" psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE << 'EOF'
CREATE TABLE IF NOT EXISTS categories (
    category_id SERIAL PRIMARY KEY,
    name VARCHAR(50) UNIQUE NOT NULL
);

CREATE TABLE IF NOT EXISTS products (
    product_id SERIAL PRIMARY KEY,
    product_name VARCHAR(100) UNIQUE NOT NULL,
    category VARCHAR(50) NOT NULL,
    price NUMERIC(10, 2) NOT NULL,
    stock INT DEFAULT 0
);

CREATE TABLE IF NOT EXISTS customers (
    customer_id SERIAL PRIMARY KEY,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    email VARCHAR(100) UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS orders (
    order_id SERIAL PRIMARY KEY,
    customer_id INT REFERENCES customers(customer_id),
    order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    total_amount NUMERIC(10, 2)
);

-- Insert sample rows
INSERT INTO categories (name) VALUES
('Smartphones'),
('Laptops'),
('Audio')
ON CONFLICT DO NOTHING;

INSERT INTO products (product_name, category, price, stock) VALUES
('Pixel 9 Pro', 'Smartphones', 999.00, 50),
('MacBook Pro M3', 'Laptops', 1999.00, 20),
('ThinkPad X1 Carbon', 'Laptops', 1450.00, 35),
('Dell XPS 15', 'Laptops', 1700.00, 15),
('Bose QuietComfort', 'Audio', 349.00, 100)
ON CONFLICT DO NOTHING;

INSERT INTO customers (first_name, last_name, email) VALUES
('Ada', 'Lovelace', 'ada@example.com'),
('Alan', 'Turing', 'alan@example.com'),
('Grace', 'Hopper', 'grace@example.com')
ON CONFLICT DO NOTHING;

INSERT INTO orders (order_id, customer_id, total_amount, order_date) VALUES
(1, 1, 999.00, pg_catalog.now() - INTERVAL '7 months'),
(2, 2, 349.00, pg_catalog.now() - INTERVAL '1 month')
ON CONFLICT DO NOTHING;

CREATE INDEX IF NOT EXISTS idx_products_category ON products(category);
CREATE INDEX IF NOT EXISTS idx_orders_customer ON orders(customer_id);
EOF

4. Запустите сервер MCP Toolbox

В этом разделе вы скачаете двоичный файл MCP Toolbox, настроите предварительно созданные определения инструментов AlloyDB Omni и запустите сервер MCP Toolbox.

Скачать MCP Toolbox

Создайте каталог для MCP Toolbox и скачайте двоичный файл toolbox:

mkdir -p ~/mcp/tools
cd ~/mcp
curl -L -O https://storage.googleapis.com/genai-toolbox/v0.31.0/linux/amd64/toolbox
chmod +x toolbox
./toolbox --version

Настройте и запустите сервер MCP Toolbox

Скачайте готовую конфигурацию инструментов alloydb-omni.yaml и запустите сервер MCP Toolbox на порте 5000 (используя экспортированные ранее переменные среды ALLOYDB_OMNI_*):
```
curl -sL --create-dirs -o "tools/alloydb-omni.yaml" "https://raw.githubusercontent.com/googleapis/mcp-toolbox/v0.31.0/internal/prebuiltconfigs/tools/alloydb-omni.yaml"
# Remove the trailing group definition block and YAML document separator for --config-folder compatibility
sed -i '/^kind: group/,$d' tools/alloydb-omni.yaml
sed -i '${/---/d;}' tools/alloydb-omni.yaml

./toolbox --config-folder ./tools/ --port 5000 --address 127.0.0.1
```
В конфигурации alloydb-omni.yaml есть 31 встроенный инструмент, в том числе основные инструменты, которые мы использовали в этой практической работе:
- execute_sql
- get_query_plan
- database_overview
- list_active_queries
- list_tables, list_indexes, list_views, list_triggers
- list_top_bloated_tables, list_locks, list_autovacuum_configurations, list_invalid_indexes
Полный список инструментов можно найти на странице alloydb-omni.yaml на GitHub.
Совет. Оставьте сервер MCP Toolbox работать на этой вкладке терминала и откройте новую вкладку (+ в Cloud Shell), чтобы выполнить остальные команды из этой практической работы.
В новой вкладке терминала убедитесь, что сервер MCP Toolbox запущен и предоставляет доступ к вашим инструментам через конечную точку JSON-RPC /mcp:
```
curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'
```

5. Настройте MCP-клиент (Antigravity CLI)

В этом разделе вы установите Antigravity CLI (agy) и настроите его для подключения к серверу MCP Toolbox.

Как установить Antigravity CLI

Если он не установлен, скачайте и запустите установщик Antigravity CLI (agy) и проверьте версию:

curl -fsSL https://antigravity.google/cli/install.sh -o /tmp/install.sh
bash /tmp/install.sh
rm -f /tmp/install.sh

# If prompted by the installer, add ~/.local/bin to your PATH:
export PATH="$HOME/.local/bin:$PATH"

# Verify the installation
agy --version

Как настроить Antigravity CLI

Добавьте запись сервера MCP Toolbox в файл конфигурации MCP вашего клиента (например, ~/.gemini/config/mcp_config.json для Antigravity CLI, .cursor/mcp.json, .vscode/mcp.json, claude_desktop_config.json или .mcp.json для Claude Code).

Чтобы подключить Antigravity CLI к работающему HTTP-серверу MCP Toolbox на порту 5000, выполните команду agy mcp add и проверьте запись с помощью agy mcp list:
```
export MCP_SERVER="127.0.0.1"
export MCP_PORT="5000"

agy mcp add alloydb-omni "http://${MCP_SERVER}:${MCP_PORT}/mcp"
agy mcp list
```
Эта команда записывает конфигурацию сервера alloydb-omni в ~/.gemini/config/mcp_config.json:
```
{
  "mcpServers": {
    "alloydb-omni": {
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}
```

Проверьте конфигурацию

Запустите Antigravity CLI:
```
agy
```
Если вы запускаете agy впервые, следуйте подсказкам на экране, чтобы войти в систему (с помощью Google OAuth или облачного проекта Google Cloud), и выберите Yes, I trust this folder (Да, я доверяю этой папке), когда появится запрос о том, доверять ли текущему каталогу.
В командной строке Antigravity CLI введите /mcp, чтобы открыть панель MCP Servers (Серверы MCP) и убедиться, что alloydb-omni подключен.
```
/mcp
```
Вывод будет выглядеть примерно так:
```
MCP Servers

Configured (~/.gemini/config/mcp_config.json)
>  ✓ alloydb-omni  Tools: database_overview, execute_sql, get_column_cardinality, get_query_plan, list_active_queries, +26 more

Keyboard: ↑/↓ Navigate  enter Actions
```
Нажмите Esc, чтобы закрыть панель MCP Servers (MCP-серверы) и вернуться к командной строке Antigravity CLI.

6. Как тестировать запросы для AlloyDB Omni

Теперь, когда Antigravity CLI подключен к вашему экземпляру AlloyDB Omni через MCP Toolbox, вы можете взаимодействовать с базой данных, используя запросы на естественном языке.

Как выполнить запрос общих сведений о базе данных

В командной строке Antigravity CLI запросите обзор текущей базы данных:

Give me an overview of the current database.

Когда появится запрос на вызов инструмента, выберите Да или Да, разрешать всегда в этом чате. Выходные данные будут выглядеть примерно так:

> Give me an overview of the current database.

● alloydb-omni/database_overview(Database overview check) (ctrl+o to expand)

  Here is an overview of the current AlloyDB Omni database instance:

  ### Database Overview
  • Instance / Engine: PostgreSQL 17.9 (AlloyDB Omni)
  • Role: Primary (is_replica: false)
  • Uptime: ~7 hours, 57 minutes
  • Connected Database: postgres
  • Connected User: postgres
  • Connections: 11 current / 100 max (1 active, 11% used)

  ### Databases in Instance
  • postgres
  • alloydbadmin (~15.74 MB)
  • alloydbmetadata (~14.82 MB)

Примеры тестов по категориям

Отправьте в Antigravity CLI следующие запросы на естественном языке. Агент автоматически сопоставляет каждый запрос с соответствующим инструментом в наборе инструментов AlloyDB Omni MCP:

1. Обзор и состояние базы данных

Цель тестирования	Запрос на естественном языке	Инструмент запущен
Проверка системы	`Give me an overview of the current database.`	`database_overview`
Активные подключения	`What queries are currently running on the database?`	`list_active_queries`
Установленные расширения	`What extensions are installed in this database?`	`list_installed_extensions`
Доступные расширения	`What extensions are available that I can install?`	`list_available_extensions`

2. Просмотр схемы и каталога

Цель тестирования	Запрос на естественном языке	Инструмент запущен
Как посмотреть список таблиц	`Show me all the tables in the current database.`	`list_tables`
Проверка индексов	`List all indexes in the database and which tables they belong to.`	`list_indexes`
Просмотр представлений	`What views are available in the public schema?`	`list_views`
Как проверить триггеры таблиц	`Show me the triggers defined on the orders table.`	`list_triggers`

3. Запросы и фильтрация данных (`execute_sql`)

Цель тестирования	Запрос на естественном языке	Инструмент запущен
Агрегированный запрос	`Show me the 3 most expensive products in the 'Laptops' category.`	`execute_sql`
Запрос на объединение	`Find all customers who have placed an order in the last 6 months.`	`execute_sql`
Несопоставленные записи	`Which customers haven't placed any orders yet?`	`execute_sql`

4. Производительность запросов и планы выполнения (`get_query_plan`)

Цель тестирования	Запрос на естественном языке	Инструмент запущен
Explain plan	`Explain the query plan for a query that finds all customers who have not placed an order in the last 6 months.`	`get_query_plan`
Проверка индекса	`Get the query plan for SELECT * FROM products WHERE category = 'Audio' and tell me if it uses the index.`	`get_query_plan`

5. Обслуживание и диагностика баз данных

Цель тестирования	Запрос на естественном языке	Инструмент запущен
Раздувание таблиц	`List the top five most bloated tables.`	`list_top_bloated_tables`
Конфликт блокировок	`Show me if there are any active locks or blocked transactions.`	`list_locks`
Настройки autovacuum	`Show me the current autovacuum configuration.`	`list_autovacuum_configurations`
Недопустимые индексы	`Check for any invalid indexes in the database.`	`list_invalid_indexes`

7. Организовать

После завершения практической работы удалите локальный контейнер и запущенные процессы.

Выйдите из Antigravity CLI, введя /quit или дважды нажав Ctrl+D.
Перейдите на вкладку терминала, на которой запущен сервер MCP Toolbox, и нажмите Ctrl+C, чтобы остановить его.
Остановите и удалите контейнер AlloyDB Omni Docker:
```
docker stop alloydbomni
docker rm alloydbomni
```

8. Поздравляю!

Поздравляем! Вы выполнили практическую работу. Вы успешно развернули AlloyDB Omni в контейнере, настроили MCP Toolbox for Databases со встроенным набором инструментов AlloyDB Omni и интегрировали его с Antigravity CLI, чтобы запрашивать данные и управлять базой данных с помощью естественного языка.

Что вы узнали

Как развернуть и проверить контейнер AlloyDB Omni с помощью Docker.
Как заполнить примеры таблиц и индексов для тестирования рабочих процессов агента.
Как настроить и запустить MCP Toolbox for Databases с предварительно созданной конфигурацией инструментов alloydb-omni.
Как подключить Antigravity CLI к MCP Toolbox и выполнять запросы на естественном языке для обнаружения схем, SQL-запросов, анализа планов запросов и диагностики баз данных.

Дополнительную информацию см. в указанных ниже ресурсах.

9. Опрос

Как вы будете использовать это руководство?

Только прочитал

Прочитал и выполнил упражнения