analyze_collection_data

Instructions

Implementation Reference

• src/tools/handlers/analysis.ts:14-110 (handler)

  The core handler function that implements the logic for the 'analyze_collection_data' tool. It fetches collection data, analyzes fields for null rates, uniqueness, min/max for numbers, and generates insights.

  export function createAnalyzeCollectionDataHandler(pb: PocketBase): ToolHandler {
    return async (args: AnalyzeCollectionDataArgs) => {
      try {
        const { collection, options = {} } = args;
        const sampleSize = options.sampleSize || 100;
        
        // Get collection info and records
        const collectionInfo = await pb.collections.getOne(collection);
        const records = await pb
          .collection(collection)
          .getList(1, sampleSize);
        
        // Initialize analysis structure
        const analysis = {
          collectionName: collection,
          recordCount: records.totalItems,
          fields: [] as any[],
          insights: [] as string[],
        };
        
        if (records.items.length === 0) {
          analysis.insights.push("No records available for analysis");
          return createJsonResponse(analysis);
        }
        
        // Analyze each field
        const fields = collectionInfo.fields || [];
        
        for (const field of fields) {
          if (options.fields && !options.fields.includes(field.name)) {
            continue;
          }
          
          const fieldAnalysis = {
            name: field.name,
            type: field.type,
            nonNullValues: 0,
            uniqueValues: new Set(),
            min: null as any,
            max: null as any,
          };
          
          // Analyze field values
          for (const record of records.items) {
            const value = record[field.name];
            
            if (value !== null && value !== undefined) {
              fieldAnalysis.nonNullValues++;
              fieldAnalysis.uniqueValues.add(JSON.stringify(value));
              
              // For numeric fields, track min/max
              if (field.type === "number") {
                if (fieldAnalysis.min === null || value < fieldAnalysis.min) {
                  fieldAnalysis.min = value;
                }
                if (fieldAnalysis.max === null || value > fieldAnalysis.max) {
                  fieldAnalysis.max = value;
                }
              }
            }
          }
          
          // Process analysis results
          const processedAnalysis = {
            ...fieldAnalysis,
            uniqueValueCount: fieldAnalysis.uniqueValues.size,
            fillRate: `${(
              (fieldAnalysis.nonNullValues / records.items.length) * 100
            ).toFixed(2)}%`,
            uniqueValues: undefined, // Remove the Set before serializing
          };
          
          analysis.fields.push(processedAnalysis);
          
          // Generate insights
          if (
            processedAnalysis.uniqueValueCount === records.items.length &&
            records.items.length > 5
          ) {
            analysis.insights.push(
              `Field '${field.name}' contains all unique values, consider using it as an identifier.`
            );
          }
          
          if (processedAnalysis.nonNullValues === 0) {
            analysis.insights.push(
              `Field '${field.name}' has no values. Consider removing it or ensuring it's populated.`
            );
          }
        }
        
        return createJsonResponse(analysis);
      } catch (error: unknown) {
        throw handlePocketBaseError("analyze collection data", error);
      }
    };
  }

• src/tools/schemas/analysis.ts:5-29 (schema)

  The JSON schema defining the input parameters for the 'analyze_collection_data' tool, including collection name and optional analysis options.

  export const analyzeCollectionDataSchema = {
    type: "object",
    properties: {
      collection: {
        type: "string",
        description: "Collection name to analyze",
      },
      options: {
        type: "object",
        description: "Analysis options",
        properties: {
          sampleSize: {
            type: "number",
            description: "Number of records to sample for analysis (default: 100)",
          },
          fields: {
            type: "array",
            items: { type: "string" },
            description: "Specific fields to analyze (if not provided, all fields will be analyzed)",
          },
        },
      },
    },
    required: ["collection"],
  };

• src/server.ts:166-170 (registration)

  The registration of the 'analyze_collection_data' tool in the MCP server array, linking the name, description, input schema, and handler function.

    name: "analyze_collection_data",
    description: "Analyze data patterns and provide insights about a collection",
    inputSchema: analyzeCollectionDataSchema,
    handler: createAnalyzeCollectionDataHandler(pb),
  },

• src/types/index.ts:134-140 (schema)

  TypeScript interface defining the argument types for the analyze_collection_data handler, used for type safety.

  export interface AnalyzeCollectionDataArgs {
    collection: string;
    options?: {
      sampleSize?: number;
      fields?: string[];
    };
  }