Nástroje jazyka DML (Data Manipulat Language) v SQL MCP Serveru

Důležité

Server PROTOKOLU MCP (SQL Model Context Protocol) je k dispozici v Tvůrci rozhraní Data API verze 1.7 a novější. Nejnovější funkce a opravy chyb najdete v nejnovější verzi 2.0.

Sql Model Context Protocol (MCP) Server zveřejňuje sedm nástrojů DML (Data Manipulat Language) agentům AI. Tyto nástroje poskytují typový povrch CRUD pro databázové operace – vytváření, čtení, aktualizace a odstraňování záznamů, agregace dat a provádění uložených procedur. Všechny nástroje respektují řízení přístupu na základě role (RBAC), oprávnění entit a zásady definované ve vaší konfiguraci.

Výstraha

Aby agenti efektivně dotazovali entity, nakonfigurujte metadata polí ve vašich entitách. Bez názvů a popisů polí agenti vidí jenom názvy entit a můžou nesprávně uhodnout názvy sloupců. Podrobnosti najdete v tématu Přidání popisů k entitám .

Co jsou nástroje DML?

Nástroje DML (Data Manipulat Language) zpracovávají operace s daty: vytváření, čtení, aktualizace a odstraňování záznamů, agregace dat a provádění uložených procedur. Na rozdíl od jazyka DDL (Data Definition Language), který upravuje schéma, DML pracuje výhradně na rovině dat v existujících tabulkách a zobrazeních.

Sedm nástrojů DML je:

describe_entities – Zjišťuje dostupné entity a operace.
create_record - Vloží nové řádky.
read_records – Dotazy tabulek a zobrazení
update_record – Upraví existující řádky.
delete_record - Odebere řádky.
execute_entity - Spouští uložené procedury.
aggregate_records – Provádí agregační dotazy.

Poznámka:

Funkce SQL MCP Serveru popsané v této části jsou k dispozici v Tvůrci rozhraní Data API verze 2.0 a novější. Další informace najdete v tématu Co je nového ve verzi 2.0.

Dostupnost nástrojů podle verze

Ne všechny nástroje jsou dostupné ve všech verzích. Než se budete spoléhat na zdokumentované chování, ověřte nástroje dostupné ve vaší nainstalované verzi.

nástroj	1.7.x	2.0+	Ve výchozím nastavení povoleno
`describe_entities`	Ano	Ano	Ano
`create_record`	Ano	Ano	Ano
`read_records`	Ano	Ano	Ano
`update_record`	Ano	Ano	Ano
`delete_record`	Ano	Ano	Ano
`execute_entity`	Ano	Ano	Ano
`aggregate_records`	Ne	Ano	Ano

Poznámka:

Pokud používáte verzi 1.7.x, aggregate_records není k dispozici. Agenti, kteří se pokoušejí provádět dotazy na počet nebo agregační dotazy, musí místo toho načíst všechny odpovídající řádky. Upgradujte na verzi 2.0 nebo novější pro nativní podporu agregace.

Pokud jsou nástroje DML povoleny globálně a pro entitu, SQL MCP Server je zveřejňuje prostřednictvím protokolu MCP. Agenti nikdy nepracují přímo se schématem databáze – pracují prostřednictvím abstraktní vrstvy tvůrce rozhraní Data API.

Nástroje

odpověď list_tools

Když agent zavolá list_tools, SQL MCP Server vrátí:

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

describe_entities

Vrátí entity, které jsou dostupné pro aktuální roli. Každá položka obsahuje názvy polí, popisy a povolené operace. Tento nástroj se na databázi nedotazuje. Místo toho se načte z konfigurace v paměti vytvořené z konfiguračního souboru.

Metadata polí pocházejí z fields dat ve vaší konfiguraci. Pokud ho nezahrnete, agenti uvidí jenom názvy entit s prázdným fields polem. Pokyny k nastavení najdete v tématu Přidání popisů k entitám .

Poznámka:

Odpověď obsahuje pole name a description hodnoty z vaší konfigurace. Datové typy a indikátory primárního klíče nejsou součástí aktuální odpovědi. Parametry uložené procedury také nejsou uvedené. Agenti spoléhají na popisy entit a polí společně s chybovou zpětnou vazbou k určení správného použití.

Parametry

Parameter	Typ	Povinné	Description
`nameOnly`	Boolean	Ne	Když `true`vrátí jednoduchý seznam názvů a popisů entit bez metadat polí.
`entities`	pole řetězců	Ne	Omezuje odpověď na zadané entity. Pokud je tento parametr vynechán, vrátí se všechny entity s podporou MCP.

Příklad požadavku

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

Příklad odpovědi

{
  "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"
      ]
    }
  ]
}

Poznámka:

Možnosti entity používané některou z cruD a spouštění nástrojů DML pocházejí přímo z describe_entities. Interní sémantický popis připojený k jednotlivým nástrojům vynucuje tento dvoustupňový tok.

vytvořit_záznam

Vytvoří nový řádek v tabulce. K vytvoření entity pro aktuální roli je vyžadováno oprávnění. Nástroj ověří vstup ve schématu entity, vynucuje oprávnění na úrovni pole, použije zásady vytváření a vrátí vytvořený záznam s libovolnými vygenerovanými hodnotami.

Parametry

Parameter	Typ	Povinné	Description
`entity`	řetězec	Ano	Název entity, ve které se má vytvořit záznam.
`data`	objekt	Ano	Představují páry klíčů a hodnot pro názvy polí a hodnoty nového záznamu.

read_records

Dotazuje tabulku nebo zobrazení. Podporuje filtrování, řazení, stránkování a výběr polí. Nástroj sestaví deterministické SQL ze strukturovaných parametrů, použije oprávnění ke čtení a projekce polí a vynucuje zásady zabezpečení na úrovni řádků.

Parametry

Parameter	Typ	Povinné	Description
`entity`	řetězec	Ano	Název entity, ze které se má číst.
`select`	řetězec	Ne	Čárkami oddělený seznam názvů polí, které se mají vrátit (například `"id,title,price"`).
`filter`	řetězec	Ne	Výraz filtru ve stylu OData (například `"Price gt 10 and Category eq 'Books'"`).
`orderby`	pole řetězců	Ne	Seřaďte výrazy. Každý prvek je název pole s volitelným směrem (například `["Price desc", "Name asc"]`).
`first`	integer	Ne	Maximální počet záznamů, které se mají vrátit.
`after`	řetězec	Ne	Pokračovací kurzor z předchozí odpovědi pro stránkování.

Výstraha

Parametr orderby musí být pole řetězců, nikoli jeden řetězec. Předání řetězcové hodnoty způsobí UnexpectedError. Místo ["Name asc"]použijte "Name asc" .

Odpověď stránkování

Pokud jsou k dispozici další výsledky, odpověď obsahuje after kurzor. Pokud chcete načíst další stránku, předejte tuto hodnotu jako after parametr v dalším požadavku.

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

after Přítomnost pole označuje, že existuje více stránek. Pokud after chybí, odpověď obsahuje poslední stránku.

Důležité

Výsledky z read_records se automaticky ukládají do mezipaměti pomocí systému ukládání do mezipaměti tvůrcem rozhraní Data API. Můžete nakonfigurovat hodnotu TTL (Time to Live) mezipaměti globálně nebo pro každou entitu , abyste snížili zatížení databáze.

Operace JOIN

Nástroj read_records je navržený pro jednu tabulku nebo zobrazení. V důsledku toho se operace JOIN v tomto nástroji nepodporují. Tento návrh pomáhá rozdělit odpovědnosti, zlepšit výkon a omezit dopad na kontextové okno vaší relace.

Operace JOIN ale nejsou hraničním případem a Tvůrce rozhraní DATA API (DAB) už podporuje sofistikované dotazování prostřednictvím koncového bodu GraphQL. Pro složitější dotazy doporučujeme místo tabulky použít zobrazení. Nástroj execute_entity můžete také použít ke spuštění uložených procedur, které zapouzdří parametrizované dotazy.

aktualizace_záznamu

Upraví existující řádek. Vyžaduje aktualizaci primárního klíče a polí. Nástroj ověří, jestli primární klíč existuje, vynucuje oprávnění k aktualizaci a zásady a aktualizuje pouze pole, která může aktuální role upravit.

Parametry

Parameter	Typ	Povinné	Description
`entity`	řetězec	Ano	Název entity, který se má aktualizovat.
`keys`	objekt	Ano	Páry klíč-hodnota identifikující záznam (například `{"id": 42}`).
`fields`	objekt	Ano	Přiřazení klíče-hodnoty k názvům polí a jejich novým hodnotám.

smazat_záznam

Odebere existující řádek. Vyžaduje primární klíč. Nástroj ověří, že primární klíč existuje, vynucuje oprávnění k odstranění a zásady a provádí bezpečné odstranění s podporou transakcí.

Parametry

Parameter	Typ	Povinné	Description
`entity`	řetězec	Ano	Název entity, ze které se má odstranit.
`keys`	objekt	Ano	Páry klíč-hodnota identifikující záznam (například `{"id": 42}`).

Poznámka:

V některých produkčních scénářích se tento nástroj globálně deaktivuje, aby široce omezil modely. Tato volba je na vás a je vhodné si uvědomit, že oprávnění na úrovni entit zůstávají nejdůležitějším způsobem řízení přístupu. I když je delete-record zapnuto, pokud role nemá oprávnění k odstranění u entity, nemůže tato role pro danou entitu tento nástroj použít.

execute_entity

Spustí uloženou proceduru. Podporuje vstupní parametry a výstupní výsledky. Nástroj ověří vstupní parametry pro podpis procedury, vynucuje oprávnění ke spuštění a bezpečně předává parametry.

Parametry

Parameter	Typ	Povinné	Description
`entity`	řetězec	Ano	Název entity uložené procedury.
`parameters`	objekt	Ne	Páry klíč-hodnota pro názvy a hodnoty vstupních parametrů.

agregovat_záznamy

Provádí agregační dotazy na tabulky a zobrazení. Podporuje běžné agregační funkce, jako je počet, součet, průměr, minimum a maximum. Nástroj sestaví deterministické SQL ze strukturovaných parametrů, použije oprávnění ke čtení a projekce polí a vynucuje zásady zabezpečení na úrovni řádků.

Parametry

Parameter	Typ	Povinné	Description
`entity`	řetězec	Ano	Název entity, který se má agregovat.
`function`	řetězec	Ano	Agregační funkce: `count`, `sum`, `avg`, `min`nebo `max`.
`field`	řetězec	Ano	Pole, které se má agregovat. Použít `"*"` pro `count`.
`filter`	řetězec	Ne	Filtr stylu OData použitý před agregací
`distinct`	Boolean	Ne	Když `true`, odebere duplicitní hodnoty před agregací.
`groupby`	pole řetězců	Ne	Názvy polí pro seskupení výsledků podle (například `["Category", "Status"]`).
`having`	objekt	Ne	Filtruje skupiny podle agregované hodnoty. Používá operátory: `eq`, `neq`, `gt`, `gtelt`, `lte`. `in`
`orderby`	pole řetězců	Ne	Seřaďte výrazy pro seskupené výsledky (například `["count desc"]`).
`first`	integer	Ne	Maximální počet seskupených výsledků, které se mají vrátit.
`after`	řetězec	Ne	Kurzor pokračování pro stránkování seskupených výsledků

Příklad: počet s GROUP BY a HAVING

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

Nástroj aggregate-records lze nakonfigurovat jako logickou hodnotu nebo jako objekt s dalšími nastaveními:

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

Vlastnost query-timeout určuje maximální dobu provádění v sekundách (rozsah: 1–600). Toto nastavení pomáhá zabránit tomu, aby dlouhotrvající agregační dotazy nadměrně využívaly prostředky.

Konfigurace modulu runtime

Konfigurujte nástroje DML globálně v sekci runtime vašeho 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ždá vlastnost nástroje v části runtime.mcp.dml-tools přijímá true nebo false. Nástroj aggregate-records také podporuje formát objektu senabled: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
        }
      }
    }
  }
}

Chcete-li povolit nebo zakázat všechny nástroje DML najednou, nastavte "dml-tools" na true hodnotu nebo false.

Použití rozhraní příkazového řádku

Nastavte vlastnosti jednotlivě pomocí rozhraní příkazového řádku Tvůrce dat:

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

Zakázání nástrojů

Když nástroj zakážete na úrovni modulu runtime, nezobrazí se agentům bez ohledu na oprávnění entity nebo konfiguraci role. Toto nastavení je užitečné, když potřebujete přísné provozní hranice.

Obvyklé scénáře

Zakázání delete-record , aby se zabránilo ztrátě dat v produkčním prostředí
Zakázat create-record pro koncové body jen pro čtení
Zakázat execute-entity, pokud se nepoužívají uložené procedury
Zákaz aggregate-records , pokud nejsou potřeba agregační dotazy

Pokud je nástroj globálně zakázaný, není viditelný v odpovědi a nelze ho aktivovat.

Nastavení entity

Entity se automaticky účastní MCP, pokud je explicitně neomezíte. Vlastnost mcp u entity řídí její účast MCP. Pro explicitní ovládací prvek použijte formát objektu.

Formát objektu

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

Pokud pro entitu nezadáte mcp, nástroje DML budou ve výchozím nastavení povoleny, když je MCP povoleno globálně.

Vlastní nástroje pro uložené procedury

U entit uložených procedur můžete proceduru také zaregistrovat jako pojmenovaný nástroj MCP pomocí custom-tool vlastnosti. Pokyny k nastavení najdete v tématu Konfigurace vlastních nástrojů MCP .

Rozsah ovládacího prvku pro jednotlivé nástroje

Přepínače pro jednotlivé nástroje jsou nakonfigurovány pouze na globální úrovni modulu runtime v části runtime.mcp.dml-tools.

Na úrovni entity, mcp je logická brána nebo objekt s vlastnostmi dml-tools a 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
      }
    }
  }
}

Nástroj je k dispozici pouze v případě, že je povolen globálně a entita umožňuje nástroje DML.

Integrace RBAC

Každá operace nástroje DML vynucuje pravidla řízení přístupu na základě role. Role agenta určuje, které entity jsou viditelné, které operace jsou povolené, která pole jsou zahrnuta a jestli se použijí zásady na úrovni řádků.

Pokud anonymous role povoluje oprávnění jen ke Productsčtení:

describe_entities Zobrazuje read_records se pouze v operacích.
create_record, update_recorda delete_record nejsou k dispozici
Ve schématu se zobrazují pouze pole povolená pro anonymous.

Nakonfigurujte role ve vašem `dab-config.json`:

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

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-06-19

Nástroje jazyka DML (Data Manipulat Language) v SQL MCP Serveru

Co jsou nástroje DML?

Dostupnost nástrojů podle verze

Nástroje

odpověď list_tools

describe_entities

Parametry

Příklad požadavku

Příklad odpovědi

vytvořit_záznam

Parametry

read_records

Parametry

Odpověď stránkování

Operace JOIN

aktualizace_záznamu

Parametry

smazat_záznam

Parametry

execute_entity

Parametry

agregovat_záznamy

Parametry

Příklad: počet s GROUP BY a HAVING

Konfigurace modulu runtime

Použití rozhraní příkazového řádku

Zakázání nástrojů

Obvyklé scénáře

Nastavení entity

Formát objektu

Vlastní nástroje pro uložené procedury

Rozsah ovládacího prvku pro jednotlivé nástroje

Integrace RBAC

Nakonfigurujte role ve vašem dab-config.json:

Související obsah

Váš názor

Další materiály

Nakonfigurujte role ve vašem `dab-config.json`: