mcp_get_container_stats

Instructions

Implementation Reference

• src/tools/containerAnalysis.ts:126-193 (handler)

  The handler function that executes the tool logic for mcp_get_container_stats. It counts total documents, samples documents to estimate size, and analyzes partition key distribution.

  /**
   * Get statistical information about a container (document count, size, partition distribution)
   */
  export const mcp_get_container_stats = async (args: { container_id: string; sample_size?: number; connection_id?: string }): Promise<ToolResult<ContainerStats>> => {
    const { container_id, sample_size = 1000, connection_id } = args;
    log(`Executing mcp_get_container_stats with: ${JSON.stringify(args)}`);
  
    try {
      const container = getContainer(container_id, connection_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) {
      log(`Error in mcp_get_container_stats for container ${container_id}: ${error.message}`);
      return { success: false, error: error.message };
    }
  };

• src/tools/types.ts:38-49 (schema)

  The ContainerStats and PartitionKeyStats interfaces defining the return type shape for mcp_get_container_stats.

  export interface ContainerStats {
    documentCount: number;
    sizeInKB: number;
    throughput?: number;
    partitionKeyStatistics?: PartitionKeyStats[];
  }
  
  export interface PartitionKeyStats {
    partitionKeyValue: string;
    documentCount: number;
    sizeInKB: number;
  }

• src/tools.ts:64-84 (registration)

  The tool registration definition with name, description, and inputSchema (container_id required, sample_size optional, connection_id optional).

  // 4. Container Statistics
  {
    name: "mcp_get_container_stats",
    description: "Get statistical information about a container including document count, estimated size, and partition key distribution. Use this for capacity planning and performance analysis. Example: mcp_get_container_stats({container_id: 'orders', sample_size: 500})",
    inputSchema: {
      type: "object",
      properties: {
        container_id: {
          type: "string",
          description: "The ID/name of the container to analyze"
        },
        sample_size: {
          type: "number",
          description: "Number of documents to sample for statistics (default: 1000, higher = more accurate but slower)",
          default: 1000
        },
        ...connectionIdProperty
      },
      required: ["container_id"]
    }
  },

• src/tools/containerAnalysis.ts:195-201 (handler)

  Helper function getNestedProperty used to extract partition key values from nested document properties.

  // Helper function to get nested property from object
  function getNestedProperty(obj: any, path: string): any {
    return path.split('/').reduce((current, key) => {
      return current && current[key] !== undefined ? current[key] : undefined;
    }, obj);
  }

• src/server.ts:130-132 (registration)

  The server-side routing/dispatch that maps the 'mcp_get_container_stats' tool name to the handler function.

  case 'mcp_get_container_stats':
      result = await toolHandlers.mcp_get_container_stats(input as any);
      break;