Средства языка обработки данных (DML) в SQL MCP Server

Это важно

SQL MCP Server находится в предварительной версии, и эта документация, и реализация подсистемы подлежит изменению в течение этого ознакомительного периода.

SQL MCP Server предоставляет шесть средств языка обработки данных (DML) агентам ИИ. Эти средства предоставляют типизированные поверхности CRUD для операций с базами данных— создание, чтение, обновление и удаление записей, а также выполнение хранимых процедур. Все инструменты поддерживают управление доступом на основе ролей (RBAC), разрешения сущностей и политики, определённые в вашей конфигурации.

Что такое средства DML?

Средства DML (язык обработки данных) обрабатывают операции с данными: создание, чтение, обновление и удаление записей, а также выполнение хранимых процедур. В отличие от DDL (язык определения данных), который изменяет схему, DML работает исключительно на плоскости данных в существующих таблицах и представлениях.

Шесть средств DML:

• describe_entities — обнаруживает доступные сущности и операции
• create_record — вставка новых строк
• read_records — выполнение запросов к таблицам и представлениям
• update_record — изменяет существующие строки
• delete_record — удаляет строки
• execute_entity — выполняет хранимые процедуры

Если средства DML включены глобально и для сущности, SQL MCP Server предоставляет их через протокол MCP. Агенты никогда не взаимодействуют напрямую со схемой базы данных — они работают через уровень абстракции Data API builder.

Средства

ответ команды list_tools

Когда агент вызывает list_tools, SQL MCP Server возвращает:

{
  "tools": [
    { "name": "describe_entities" },
    { "name": "create_record" },
    { "name": "read_records" },
    { "name": "update_record" },
    { "name": "delete_record" },
    { "name": "execute_entity" }
  ]
}

describe_entities

Возвращает сущности, доступные для текущей роли. Каждая запись включает имена полей, типы данных, первичные ключи и разрешенные операции. Это средство не запрашивает базу данных. Вместо этого он считывает из конфигурации в памяти, созданной из вашего файла конфигурации.

{
  "entities": [
    {
      "name": "Products",
      "description": "Product catalog with pricing and inventory",
      "fields": [
        {
          "name": "ProductId",
          "type": "int",
          "isKey": true,
          "description": "Unique product identifier"
        },
        {
          "name": "ProductName",
          "type": "string",
          "description": "Display name of the product"
        },
        {
          "name": "Price",
          "type": "decimal",
          "description": "Retail price in USD"
        }
      ],
      "operations": [
        "read_records",
        "update_record"
      ]
    }
  ]
}

Замечание

Параметры сущности, используемые любыми инструментами CRUD и выполнения DML, берутся непосредственно из describe_entities. Внутреннее семантическое описание, присоединенное к каждому инструменту, применяет этот двухэтапный процесс.

create_record

Создает новую строку в таблице. Требуется разрешение на создание сущности для текущей роли. Средство проверяет входные данные для схемы сущности, применяет разрешения на уровне поля, применяет политики создания и возвращает созданную запись с любыми созданными значениями.

чтение_записей

Запрашивает таблицу или представление. Поддерживает фильтрацию, сортировку, разбиение на страницы и выбор полей. Средство создает детерминированный SQL из структурированных параметров, применяет разрешения на чтение и проекции полей и применяет политики безопасности на уровне строк.

Результаты из read_records автоматически кэшируются с помощью системы кэширования API данных. Вы можете настроить время жизни кэша (TTL) глобально или для каждой сущности для уменьшения нагрузки на базу данных.

обновить_запись

Изменяет существующую строку. Требуется, чтобы первичный ключ и поля обновлялись. Средство проверяет наличие первичного ключа, применяет предполагаемые разрешения и политики обновления, и обновляет только те поля, которые текущая роль может изменять.

удалить_запись

Удаляет существующую строку. Требуется первичный ключ. Средство проверяет наличие первичного ключа, принудительно удаляет разрешения и политики и выполняет безопасное удаление с поддержкой транзакций.

Предупреждение

Некоторые рабочие сценарии отключают это средство глобально для широкого ограничения моделей.

execute_entity

Запускает хранимую процедуру. Поддерживает входные параметры и выходные результаты. Средство проверяет входные параметры по сигнатуре процедуры, применяет разрешения выполнения и безопасно передает параметры.

Конфигурация среды выполнения

В разделе среды выполнения dab-config.json глобально настройте средства DML.

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "path": "/mcp",
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true
      }
    }
  }
}

Использование интерфейса командной строки

Устанавливайте свойства индивидуально, используя командную строку построителя Data API.

dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true

Отключение инструментов

При отключении инструмента на уровне выполнения, он никогда не отображается агентам, независимо от разрешений для сущностей или конфигурации ролей. Этот параметр полезен, если требуется строгие операционные границы.

Распространенные сценарии

• Отключить delete-record чтобы предотвратить потерю данных в производственной среде
• Отключите create-record для конечных точек отчетов в режиме только для чтения
• Отключить execute-entity, если хранимые процедуры не используются

Если средство отключено глобально, средство скрыто из list_tools ответа и не может вызываться.

Параметры сущности

Сущности участвуют в MCP автоматически, если вы явно не ограничиваете их. Свойство dml-tools существует таким образом, чтобы можно было исключить сущность из MCP или сузить ее возможности, но вам не нужно ничего устанавливать для нормального использования.

{
  "entities": {
    "Products": {
      "mcp": {
        "dml-tools": true
      }
    },
    "SensitiveData": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

Если вы не указываете mcp.dml-tools на сущности, по умолчанию используется true, когда MCP включен глобально.

Управление на детализированном уровне

Вы можете отключить определенные инструменты для отдельных сущностей.

{
  "entities": {
    "AuditLogs": {
      "mcp": {
        "dml-tools": {
          "create-record": true,
          "read-records": true,
          "update-record": false,
          "delete-record": false
        }
      }
    }
  }
}

Эта конфигурация позволяет агентам создавать и считывать журналы аудита, но предотвращает изменение или удаление.

Интеграция RBAC

Каждая операция средства DML применяет правила управления доступом на основе ролей. Роль агента определяет, какие сущности видны, какие операции разрешены, какие поля включены и применяются ли политики на уровне строк.

anonymous Если роль разрешает только чтение на Products:

• describe_entities только показывает read_records в операциях
• create_record, update_recordи delete_record недоступны
• Только поля, разрешенные для anonymous, отображаются в схеме.

Настройте роли в вашем dab-config.json

{
  "entities": {
    "Products": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["ProductId", "ProductName", "Price"],
                "exclude": ["Cost"]
              }
            }
          ]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Связанный контент

• Обзор SQL MCP Server
• Добавление семантических описаний в SQL MCP Server
• Справочник по конфигурации строителя API данных (DAB)
• Развертывание SQL MCP Server в приложениях контейнеров Azure