Strumenti del server MCP di Azure per Azure Cosmos DB

Il server MCP Azure consente di gestire le risorse Azure Cosmos DB con richieste di linguaggio naturale. È possibile elencare account, database e contenitori, eseguire query e recuperare elementi, eseguire ricerche in base a testo o somiglianza vettoriale, dedurre gli schemi dei contenitori ed eseguire query SQL, senza scrivere codice complesso.

Azure Cosmos DB è un servizio di database multimodello distribuito a livello globale. Per altre informazioni, vedere la documentazione di Azure Cosmos DB.

Annotazioni

Parametri degli strumenti: gli strumenti del server MCP di Azure definiscono i parametri per i dati necessari per completare le attività. Alcuni di questi parametri sono specifici di ogni strumento e sono documentati di seguito. Altri parametri sono globali e condivisi da tutti gli strumenti. Per altre informazioni, vedere Parametri degli strumenti.

Elencare account, database o contenitori

Elenca gli account, i database o i contenitori di Azure Cosmos DB. Per impostazione predefinita, questo strumento restituisce tutti gli account nella sottoscrizione. Specificare il Account per elencare i database in tale account, oppure specificare sia il Account che il Database per elencare i contenitori nel database. I risultati vengono restituiti al livello specificato: account, database o contenitore.

Alcuni prompt di esempio includono:

  • "Elencare tutti gli account Azure Cosmos DB nella sottoscrizione."
  • Mostrami i database nell'account Azure Cosmos DB «prod-cosmos».
  • "Elencare tutti i contenitori nel database "orders-db" per l'account Azure Cosmos DB "my-cosmosdb".
Parametro Obbligatorio o facoltativo Description
Conto Opzionale Nome dell'account Azure Cosmos DB. Se non specificato, elenca tutti gli account nella sottoscrizione. Specificare questo parametro per elencare i database o combinare con Database per elencare i contenitori.
Banca dati Opzionale Nome del database. È necessario specificare Account. Se specificato, elenca i contenitori all'interno di questo database.

Suggerimenti di annotazione degli strumenti:

Distruttivo: ❌ | Idempotente: ✅ | Open World: ❌ | Sola lettura: ✅ | Segreto: ❌ | Locale obbligatorio: ❌

Eseguire query sugli elementi del contenitore

Eseguire query sugli elementi da un contenitore di Azure Cosmos DB. Specificare il nome dell'account, il nome del database e il nome del contenitore e, facoltativamente, fornire una query SQL per filtrare i risultati. La query usa la sintassi dell'API SQL di Azure Cosmos DB e lo strumento restituisce elementi corrispondenti come documenti JSON.

Alcuni prompt di esempio includono:

  • Elenca tutti gli elementi del contenitore "orders" nel database "ecommerce-db" per l'account Azure Cosmos DB "contoso-cosmos".
  • "Eseguire query sugli elementi dal contenitore "orders" nel database 'commerce-db' per l'account 'contoso-cosmos' usando la query SQL 'SELECT * FROM c WHERE c.status = shipped'."
  • Mostra elementi contenenti "outage" nel contenitore "orders" nel database "sales" per l'account Azure Cosmos DB "my-cosmos-account".
Parametro Obbligatorio o facoltativo Description
Conto Obbligatorio Nome dell'account Azure Cosmos DB su cui eseguire una query, ad esempio contoso-cosmos.
Contenitore Obbligatorio Nome del contenitore su cui eseguire una query, ad esempio orders.
Banca dati Obbligatorio Nome del database su cui eseguire una query, ad esempio ecommerce-db.
Quesito Opzionale Query SQL da eseguire sul contenitore. Usa la sintassi dell'API SQL di Azure Cosmos DB.

Suggerimenti di annotazione degli strumenti:

Distruttivo: ❌ | Idempotente: ✅ | Open World: ❌ | Sola lettura: ✅ | Segreto: ❌ | Locale obbligatorio: ❌

Ottieni elemento del contenitore

Recuperare un singolo documento da un contenitore Cosmos DB in base al relativo ID. Quando si specifica una chiave di partizione, la query viene indirizzata a una singola partizione, con costi inferiori rispetto a un fan-out tra partizioni. Senza una chiave di partizione, lo strumento esegue una query tra più partizioni.

Alcuni prompt di esempio includono:

  • Ottieni il documento con ID order-001 dal contenitore orders nel database ecommerce-db per l'account Cosmos DB contoso-cosmos.

  • "Recuperare l'elemento user-42 dal contenitore users nel database app-db per l'account my-cosmos usando la chiave USdi partizione ".

  • "Recuperare il documento product-789 dal contenitore catalog nel database store-db per l'account retail-cosmos".

Parametro Obbligatorio o facoltativo Description
Conto Obbligatorio Nome dell'account Azure Cosmos DB.
Contenitore Obbligatorio Nome del contenitore.
Banca dati Obbligatorio Nome del database.
ID Obbligatorio ID del documento da recuperare.
Chiave di partizione Opzionale Valore della chiave di partizione. Definisce l'ambito della query in una singola partizione per ottenere prestazioni migliori.

Suggerimenti di annotazione degli strumenti:

Distruttivo: ❌ | Idempotente: ✅ | Open World: ❌ | Sola lettura: ✅ | Segreto: ❌ | Locale obbligatorio: ❌

Elencare gli elementi del contenitore modificati di recente

Recuperare i documenti modificati più di recente da un contenitore Cosmos DB, ordinati in base al timestamp di sistema (_ts) in ordine decrescente. Usare il Count parametro per controllare il numero di documenti restituiti.

Alcuni prompt di esempio includono:

  • "Mostra i 10 elementi modificati più di recente nel contenitore orders nel database ecommerce-db per l'account contoso-cosmos".

  • "Ottenere i 5 documenti più recenti dal contenitore events nel database telemetry-db per l'account my-cosmos".

  • "Elencare gli elementi modificati più di recente nel contenitore products nel database catalog-db per l'account retail-cosmos".

Parametro Obbligatorio o facoltativo Description
Conto Obbligatorio Nome dell'account Azure Cosmos DB.
Contenitore Obbligatorio Nome del contenitore.
Banca dati Obbligatorio Nome del database.
Conto Opzionale Numero di documenti da restituire. Intervallo accettato: 1-20. Il valore predefinito è 10.

Suggerimenti di annotazione degli strumenti:

Distruttivo: ❌ | Idempotente: ✅ | Open World: ❌ | Sola lettura: ✅ | Segreto: ❌ | Locale obbligatorio: ❌

Cercare elementi del contenitore in base al testo

Recuperare i primi N documenti in un contenitore Cosmos DB in cui una proprietà specificata corrisponde a una frase di ricerca usando la funzione Cosmos DB FullTextContains . La corrispondenza è basata sulla tokenizzazione delle parole (non sulle sottostringhe) e usa l'analizzatore full-text configurato per il contenitore, quindi si applicano lo stemming e il filtraggio delle parole non significative specifici della lingua. Questo strumento richiede un indice full-text sulla proprietà di destinazione.

Alcuni prompt di esempio includono:

  • Cerca nel contenitore support-tickets nel database helpdesk-db per l'account contoso-cosmos i documenti in cui description contiene network outage.

  • "Trovare i primi 5 documenti nel contenitore articles nel database content-db per l'account my-cosmos in cui body contiene AI governance".

  • Contenitore di ricerca full-text feedback nel database app-db per l'account prod-cosmos per search-phrase nel campo comments.

Parametro Obbligatorio o facoltativo Description
Conto Obbligatorio Nome dell'account Azure Cosmos DB.
Contenitore Obbligatorio Nome del contenitore.
Banca dati Obbligatorio Nome del database.
Frase di ricerca Obbligatorio Frase da cercare usando la funzione Cosmos DB FullTextContains .
Proprietà di ricerca Obbligatorio Proprietà del contenitore in cui eseguire la ricerca. È necessario che sia configurato un indice full-text.
Conto Opzionale Numero di documenti da restituire. Intervallo accettato: 1-20. Il valore predefinito è 10.
Proprietà da selezionare Opzionale Elenco delimitato da virgole di campi da restituire anziché il documento completo.

Suggerimenti di annotazione degli strumenti:

Distruttivo: ❌ | Idempotente: ✅ | Open World: ❌ | Sola lettura: ✅ | Segreto: ❌ | Locale obbligatorio: ❌

Ricerca di elementi del contenitore in base alla somiglianza vettoriale

Recuperare i primi N documenti in un contenitore Cosmos DB più simile a un determinato testo di ricerca usando la funzione Cosmos DB VectorDistance . Lo strumento converte il testo di ricerca in un vettore di query chiamando una distribuzione di incorporamento OpenAI Azure, quindi restituisce i documenti corrispondenti più vicini classificati in base al punteggio di somiglianza (_score). Questo strumento richiede un indice vettoriale nella proprietà di destinazione.

Quando si omette Properties to select, il documento completo viene restituito con la proprietà vector rimossa, perché un tipico incorporamento di 1.536 dimensioni aggiunge circa 30 KB o 10.000 token per risultato.

Alcuni prompt di esempio includono:

  • Trova i 5 documenti più simili a "strategie di ottimizzazione dei costi del cloud" nel contenitore docs nel database knowledge-db per l'account contoso-cosmos, utilizzando la proprietà vettoriale embedding e l'endpoint OpenAI https://my-openai.openai.azure.com/.

  • Contenitore per la ricerca vettoriale products nel database catalog-db per l'account retail-cosmos per elementi simili a "scarpe da corsa leggere", usando la distribuzione di embedding text-embedding-ada-002.

  • Cerca nel contenitore articles nel database content-db per l'account my-cosmos contenuti simili a 'progressi nell'informatica quantistica' e restituisci solo i campi title e summary.

Parametro Obbligatorio o facoltativo Description
Conto Obbligatorio Nome dell'account Azure Cosmos DB.
Contenitore Obbligatorio Nome del contenitore.
Banca dati Obbligatorio Nome del database.
Distribuzione degli embedding Obbligatorio Nome della distribuzione di incorporamento di OpenAI Azure usato per generare il vettore di query.
endpoint di OpenAI Obbligatorio URL dell'endpoint OpenAI Azure, ad esempio https://my-openai.openai.azure.com/).
Cerca testo Obbligatorio Testo da convertire in un vettore di query tramite gli embeddings di Azure OpenAI.
Proprietà vettore Obbligatorio La proprietà del contenitore che contiene gli embedding vettoriali. Deve avere un indice vettoriale di Cosmos DB.
Conto Opzionale Numero di documenti da restituire. Intervallo accettato: 1-20. Il valore predefinito è 10.
Dimensioni di incorporamento Opzionale Lunghezza del vettore di incorporamento richiesta, per i modelli che supportano dimensioni personalizzate , ad esempio text-embedding-3-small o text-embedding-3-large.
Proprietà da selezionare Opzionale Elenco delimitato da virgole di campi da restituire. Se omessa, viene restituito il documento completo con la proprietà vettore rimossa.

Suggerimenti di annotazione degli strumenti:

Distruttivo: ❌ | Idempotente: ✅ | Open World: ❌ | Sola lettura: ✅ | Segreto: ❌ | Locale obbligatorio: ❌

Ricavare lo schema del contenitore

Dedurre uno schema approssimativo per un contenitore Cosmos DB eseguendo il campionamento di documenti e segnalando proprietà di primo livello insieme ai relativi tipi dedotti e al numero di documenti campionati contenuti in ogni proprietà. Gli oggetti annidati e le matrici vengono segnalati come object o array senza ricorsione. Per scoprire una struttura annidata, ad esempio il percorso con notazione punto di una proprietà di tipo vettore, recupera un singolo documento con lo strumento Get container item e ispezionalo direttamente.

Alcuni prompt di esempio includono:

  • Deduci lo schema del contenitore orders nel database ecommerce-db per l'account Cosmos DB contoso-cosmos.

  • "Quali sono le proprietà di primo livello nel contenitore users nel database app-db per l'account my-cosmos? Esempio di 50 documenti."

  • "Mostra lo schema del contenitore telemetry nel database metrics-db per l'account prod-cosmos".

Parametro Obbligatorio o facoltativo Description
Conto Obbligatorio Nome dell'account Azure Cosmos DB.
Contenitore Obbligatorio Nome del contenitore.
Banca dati Obbligatorio Nome del database.
Dimensione del campione Opzionale Numero di documenti da campionare per l'inferenza dello schema.

Suggerimenti di annotazione degli strumenti:

Distruttivo: ❌ | Idempotente: ✅ | Open World: ❌ | Sola lettura: ✅ | Segreto: ❌ | Locale obbligatorio: ❌

Contenuti correlati

  • Last updated on