MCP CosmosDB

Instructions

Implementation Reference

• src/tools/containerAnalysis.ts:106-170 (handler)

  The main handler function implementing the mcp_container_stats tool. It queries the CosmosDB container for total document count, reads partition key definition, samples documents to estimate average size and partition distribution, and returns ContainerStats.
  export const mcp_container_stats = async (args: { container_id: string; sample_size?: number }): Promise<ToolResult<ContainerStats>> => { const { container_id, sample_size = 1000 } = args; console.log('Executing mcp_container_stats with:', args); try { const container = getContainer(container_id); // Query to count total documents const countQuery = 'SELECT VALUE COUNT(1) FROM c'; const { resources: countResult } = await container.items.query(countQuery).fetchAll(); const documentCount = countResult[0] || 0; // Get partition key path for statistics const { resource: containerDef } = await container.read(); if (!containerDef || !containerDef.partitionKey || !containerDef.partitionKey.paths || containerDef.partitionKey.paths.length === 0) { throw new Error(`Container ${container_id} does not have a valid partition key defined`); } const partitionKeyPath = containerDef.partitionKey.paths[0]; // Sample documents to estimate size and analyze partitions const sampleQuery = `SELECT TOP ${sample_size} * FROM c`; const { resources: sampleDocs } = await container.items.query(sampleQuery).fetchAll(); // Calculate estimated size based on sample let totalSampleSize = 0; const partitionStats: Record<string, { count: number; size: number }> = {}; sampleDocs.forEach(doc => { const docSize = JSON.stringify(doc).length; totalSampleSize += docSize; // Get partition key value const partitionValue = getNestedProperty(doc, partitionKeyPath.substring(1)); // Remove leading '/' const partitionKey = String(partitionValue || 'undefined'); if (!partitionStats[partitionKey]) { partitionStats[partitionKey] = { count: 0, size: 0 }; } partitionStats[partitionKey].count++; partitionStats[partitionKey].size += docSize; }); // Estimate total size const avgDocSize = sampleDocs.length > 0 ? totalSampleSize / sampleDocs.length : 0; const estimatedSizeInKB = Math.round((documentCount * avgDocSize) / 1024); // Convert partition stats const partitionKeyStatistics = Object.entries(partitionStats).map(([key, stats]) => ({ partitionKeyValue: key, documentCount: Math.round((stats.count / sampleDocs.length) * documentCount), sizeInKB: Math.round(stats.size / 1024) })); const containerStats: ContainerStats = { documentCount, sizeInKB: estimatedSizeInKB, partitionKeyStatistics }; return { success: true, data: containerStats }; } catch (error: any) { console.error(`Error in mcp_container_stats for container ${container_id}: ${error.message}`); return { success: false, error: error.message }; } };
• src/tools.ts:51-69 (registration)

  The MCP tool registration specification for mcp_container_stats, including name, description, and input schema, provided in the ListTools response via MCP_COSMOSDB_TOOLS array.
  { name: "mcp_container_stats", description: "Get statistical information about a container including document count and partition key distribution", inputSchema: { type: "object", properties: { container_id: { type: "string", description: "The ID of the container to analyze" }, sample_size: { type: "number", description: "Sample size for statistics calculation", default: 1000 } }, required: ["container_id"] } },
• src/tools/types.ts:38-49 (schema)

  TypeScript interface definitions for the output structure of the tool: ContainerStats and its nested PartitionKeyStats.
  export interface ContainerStats { documentCount: number; sizeInKB: number; throughput?: number; partitionKeyStatistics?: PartitionKeyStats[]; } export interface PartitionKeyStats { partitionKeyValue: string; documentCount: number; sizeInKB: number; }
• src/tools/containerAnalysis.ts:173-177 (helper)

  Utility function to safely extract nested properties from documents using slash-separated paths, used to retrieve partition key values.
  function getNestedProperty(obj: any, path: string): any { return path.split('/').reduce((current, key) => { return current && current[key] !== undefined ? current[key] : undefined; }, obj); }