Narzędzia języka manipulowania danymi (DML) w programie SQL MCP Server

Serwer MCP (SQL Model Context Protocol) udostępnia siedem narzędzi języka manipulowania danymi (DML) agentom sztucznej inteligencji. Te narzędzia zapewniają typową powierzchnię CRUD dla operacji bazy danych — tworzenie, odczytywanie, aktualizowanie i usuwanie rekordów, agregowanie danych oraz wykonywanie procedur składowanych. Wszystkie narzędzia przestrzegają kontroli dostępu opartej na rolach (RBAC), uprawnień jednostki i zasad zdefiniowanych w konfiguracji.

Co to są narzędzia DML?

Narzędzia DML (Data Manipulation Language) obsługują operacje danych: tworzenie, odczytywanie, aktualizowanie i usuwanie rekordów, agregowanie danych oraz wykonywanie procedur składowanych. W przeciwieństwie do języka DDL (Data Definition Language), który modyfikuje schemat, język DML działa wyłącznie na płaszczyźnie danych w istniejących tabelach i widokach.

Siedem narzędzi DML to:

• describe_entities — Odnajduje dostępne jednostki i operacje
• create_record - Wstawia nowe wiersze
• read_records — Zapytania dotyczące tabel i widoków
• update_record - Modyfikuje istniejące wiersze
• delete_record - Usuwa wiersze
• execute_entity - Uruchamia procedury składowane
• aggregate_records - Wykonuje zapytania agregacji

Gdy narzędzia DML są włączone globalnie i dla jednostki, program SQL MCP Server uwidacznia je za pośrednictwem protokołu MCP. Agenci nigdy nie wchodzą w interakcje bezpośrednio ze schematem bazy danych — pracują za pośrednictwem warstwy abstrakcji konstruktora interfejsu API danych.

Narzędzia

lista_narzędzi odpowiedź

Gdy agent wykonuje żądanie list_tools, program SQL MCP Server zwraca:

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

opisz_entyty

Zwraca jednostki dostępne dla bieżącej roli. Każdy wpis zawiera nazwy pól, opisy i dozwolone operacje. To narzędzie nie odpytuje bazy danych. Zamiast tego odczytuje z konfiguracji w pamięci utworzonej z pliku konfiguracji.

Parametry

Przykładowe żądanie

{
  "method": "tools/call",
  "params": {
    "name": "describe_entities",
    "arguments": {
      "entities": ["Products"]
    }
  }
}

Przykładowa odpowiedź

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

create_record

Tworzy nowy wiersz w tabeli. Wymaga uprawnienia do tworzenia jednostki dla bieżącej roli. Narzędzie weryfikuje dane wejściowe względem schematu jednostki, wymusza uprawnienia na poziomie pola, stosuje zasady tworzenia i zwraca utworzony rekord z wygenerowanymi wartościami.

Parametry

czytaj_rekordy

Wykonuje zapytania dotyczące tabeli lub widoku. Obsługuje filtrowanie, sortowanie, stronicowanie i wybieranie pól. Narzędzie tworzy deterministyczny język SQL z parametrów strukturalnych, stosuje uprawnienia do odczytu i projekcje pól oraz wymusza zasady zabezpieczeń na poziomie wiersza.

Parametry

Odpowiedź paginacji

Gdy dostępnych jest więcej wyników, odpowiedź zawiera after kursor. Przekaż tę wartość jako after parametr w następnym żądaniu, aby pobrać następną stronę.

{
  "value": [ ... ],
  "after": "W3siRW50aXR5TmFtZ..."
}

Obecność after pola wskazuje, że istnieje więcej stron. Gdy after jest nieobecny, dotarłeś do ostatniej strony.

Operacje JOIN

Narzędzie read_records jest przeznaczone dla pojedynczej tabeli lub widoku. W związku z tym operacje JOIN nie są obsługiwane w tym narzędziu. Ten projekt pomaga odizolować odpowiedzialność, poprawić wydajność i ograniczyć wpływ na okno kontekstowe sesji.

Jednak operacje JOIN nie są przypadkiem rzadkim, a Data API builder (DAB) już obsługuje zaawansowane zapytania za pośrednictwem punktu końcowego GraphQL. W przypadku bardziej złożonych zapytań zalecamy użycie widoku zamiast tabeli. Za pomocą execute_entity narzędzia można również uruchamiać procedury składowane w celu hermetyzacji sparametryzowanych zapytań.

aktualizuj_rekord

Modyfikuje istniejący wiersz. Wymaga zaktualizowania klucza podstawowego i pól. Narzędzie sprawdza, czy klucz podstawowy istnieje, wymusza uprawnienia aktualizacji i zasady, a tylko aktualizuje pola, które może modyfikować bieżąca rola.

Parametry

usuń rekord

Usuwa istniejący wiersz. Wymaga klucza podstawowego. Narzędzie weryfikuje, czy klucz podstawowy istnieje, wymusza usuwanie uprawnień i zasad oraz wykonuje bezpieczne usuwanie z obsługą transakcji.

Parametry

execute_entity

Uruchamia procedurę składowaną. Obsługuje parametry wejściowe i wyniki wyjściowe. Narzędzie weryfikuje parametry wejściowe względem podpisu procedury, wymusza uprawnienia wykonywania i bezpiecznie przekazuje parametry.

Parametry

agregacja_rekordów

Wykonuje zapytania agregacyjne w tabelach i widokach. Obsługuje typowe funkcje agregujące, takie jak liczba, suma, średnia, minimum i maksimum. Narzędzie tworzy deterministyczny język SQL z parametrów strukturalnych, stosuje uprawnienia do odczytu i projekcje pól oraz wymusza zasady zabezpieczeń na poziomie wiersza.

Parametry

Przykład użycia funkcji count z klauzulą groupby oraz having

{
  "method": "tools/call",
  "params": {
    "name": "aggregate_records",
    "arguments": {
      "entity": "Todo",
      "function": "count",
      "field": "*",
      "groupby": ["UserId"],
      "having": { "gt": 2 }
    }
  }
}

aggregate-records Narzędzie można skonfigurować jako wartość logiczną lub jako obiekt z dodatkowymi ustawieniami.

{
  "runtime": {
    "mcp": {
      "dml-tools": {
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

Właściwość query-timeout określa maksymalny czas wykonywania w sekundach (zakres: 1–600). To ustawienie pomaga zapobiegać długotrwałym zapytaniom agregacji, które zużywają nadmierne zasoby.

Konfiguracja środowiska uruchomieniowego

Skonfiguruj globalnie narzędzia DML w sekcji globalnych ustawień środowiska uruchomieniowego elementu dab-config.json.

{
  "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,
        "aggregate-records": true
      }
    }
  }
}

Każda właściwość narzędzia w obszarze runtime.mcp.dml-tools akceptuje true lub false. Narzędzie aggregate-records obsługuje również format obiektu z elementami enabled i :query-timeout

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

Aby włączyć lub wyłączyć wszystkie narzędzia DML jednocześnie, ustaw wartość "dml-tools" lub truefalse .

Korzystanie z interfejsu wiersza polecenia (CLI)

Ustaw właściwości indywidualnie przy użyciu CLI konstruktora API danych.

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
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true
dab configure --runtime.mcp.dml-tools.aggregate-records.query-timeout 30

Wyłączanie narzędzi

Po wyłączeniu narzędzia na poziomie środowiska uruchomieniowego nigdy nie pojawia się agentom, niezależnie od uprawnień jednostki lub konfiguracji roli. To ustawienie jest przydatne, gdy potrzebujesz ścisłych granic operacyjnych.

Typowe scenariusze

• Wyłącz delete-record , aby zapobiec utracie danych w środowisku produkcyjnym
• Wyłącz create-record dla punktów końcowych raportowania tylko do odczytu
• Wyłącz execute-entity, gdy nie są używane procedury składowane
• Wyłącz aggregate-records , gdy zapytania agregacji nie są potrzebne

Gdy narzędzie jest wyłączone globalnie, narzędzie jest ukryte przed odpowiedzią list_tools i nie można go wywołać.

Ustawienia encji

Jednostki uczestniczą automatycznie w MCP, chyba że jawnie je ograniczysz. Właściwość mcp w obiekcie kontroluje jego udział w MCP. Użyj formatu obiektu dla jawnej kontrolki.

Format obiektu

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

Jeśli nie określisz mcp jednostki, narzędzia DML są domyślnie włączone, gdy MCP jest włączona globalnie.

Niestandardowe narzędzia dla procedur składowanych

W przypadku encji procedur składowanych użyj właściwości custom-tool, aby zarejestrować tę procedurę jako nazwane narzędzie MCP.

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id"
      },
      "mcp": {
        "custom-tool": true
      }
    }
  }
}

Zakres kontroli poszczególnych narzędzi

Przełączanie poszczególnych narzędzi jest konfigurowane tylko na poziomie globalnego środowiska uruchomieniowego w obszarze runtime.mcp.dml-tools.

Na poziomie jednostki, mcp jest to brama logiczna lub obiekt, posiadający właściwości dml-tools i custom-tool.

{
  "entities": {
    "AuditLogs": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

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

Narzędzie jest dostępne tylko wtedy, gdy jest włączone globalnie, a jednostka zezwala na narzędzia DML.

Integracja kontroli dostępu opartej na rolach

Każda operacja narzędzia DML wymusza reguły kontroli dostępu opartej na rolach. Rola agenta określa, które jednostki są widoczne, które operacje są dozwolone, które pola są uwzględniane i czy mają zastosowanie zasady na poziomie wiersza.

Jeśli rola anonymous zezwala tylko na uprawnienia do odczytu na Products:

• describe_entities pokazuje tylko read_records w operacjach
• create_record, update_recordi delete_record nie są dostępne
• Tylko pola dozwolone dla anonymous są uwzględnione w schemacie

Skonfiguruj role w pliku dab-config.json:

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

Treści powiązane

• Omówienie programu SQL MCP Server
• Dodawanie opisów semantycznych do programu SQL MCP Server
• Dokumentacja konfiguracji narzędzia Data API Builder (DAB)
• Konfiguracja MCP na poziomie jednostki
• Konfiguracja mcp środowiska uruchomieniowego
• Wdrażanie serwera SQL MCP w aplikacjach kontenerowych Azure
• Co nowego w narzędziu Data API Builder w wersji 2.0