mcp_execute_query
Execute SQL queries on CosmosDB containers to retrieve and analyze document data with parameter support and cross-partition capabilities.
Instructions
Execute a SQL query against a CosmosDB container
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| container_id | Yes | The ID of the container to query | |
| query | Yes | The SQL query to execute | |
| parameters | No | Optional parameters for the query as key-value pairs | |
| max_items | No | Maximum number of items to return | |
| enable_cross_partition | No | Whether to enable cross-partition queries |
Implementation Reference
- src/tools/dataOperations.ts:7-46 (handler)Core implementation of the mcp_execute_query tool handler. Executes SQL queries on CosmosDB containers, supports parameters, limits results, and returns documents with query statistics.
export const mcp_execute_query = async (args: { container_id: string; query: string; parameters?: Record<string, any>; max_items?: number; enable_cross_partition?: boolean; }): Promise<ToolResult<{ documents: any[]; stats: QueryStats }>> => { const { container_id, query, parameters, max_items = 100, enable_cross_partition = true } = args; console.log('Executing mcp_execute_query with:', args); try { const container = getContainer(container_id); const startTime = Date.now(); // Prepare query spec const querySpec = { query, parameters: parameters ? Object.entries(parameters).map(([name, value]) => ({ name: `@${name}`, value })) : [] }; // Execute query const queryIterator = container.items.query(querySpec, { maxItemCount: max_items }); const { resources: documents, requestCharge } = await queryIterator.fetchAll(); const executionTimeMs = Date.now() - startTime; const stats: QueryStats = { requestCharge, executionTimeMs, documentCount: documents.length }; return { success: true, data: { documents, stats } }; } catch (error: any) { console.error(`Error in mcp_execute_query for container ${container_id}: ${error.message}`); return { success: false, error: error.message }; } }; - src/tools.ts:72-103 (schema)Tool metadata and JSON input schema definition for mcp_execute_query, used for tool discovery and validation.
{ name: "mcp_execute_query", description: "Execute a SQL query against a CosmosDB container", inputSchema: { type: "object", properties: { container_id: { type: "string", description: "The ID of the container to query" }, query: { type: "string", description: "The SQL query to execute" }, parameters: { type: "object", description: "Optional parameters for the query as key-value pairs" }, max_items: { type: "number", description: "Maximum number of items to return", default: 100 }, enable_cross_partition: { type: "boolean", description: "Whether to enable cross-partition queries", default: true } }, required: ["container_id", "query"] } }, - src/server.ts:63-66 (registration)Registration of tool list handler, exposing MCP_COSMOSDB_TOOLS (including mcp_execute_query schema) for MCP tool discovery.
// @ts-ignore - Bypass TypeScript errors from the SDK's types server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: MCP_COSMOSDB_TOOLS })); - src/server.ts:103-105 (registration)Dispatch/execution routing for mcp_execute_query tool call in the MCP CallToolRequest handler.
case 'mcp_execute_query': result = await toolHandlers.mcp_execute_query(input as any); break; - src/tools/types.ts:31-36 (helper)Type definitions for QueryStats used in the tool's return type.
export interface QueryStats { requestCharge: number; executionTimeMs: number; documentCount: number; indexHitRatio?: number; }