@theihtisham/mcp-server-firebase 1.0.0

package/src/tools/firestore.ts

@@ -0,0 +1,931 @@
+import { getFirestore } from '../services/firebase.js';
+import {
+  validateCollectionPath,
+  validateDocumentPath,
+  validateWhereField,
+  validateOperator,
+  sanitizeData,
+  handleFirebaseError,
+  formatSuccess,
+  formatListResult,
+  firestoreCache,
+  schemaCache,
+} from '../utils/index.js';
+import type { ToolDefinition } from './types.js';
+import {
+  Firestore,
+  Query,
+  WhereFilterOp,
+  DocumentSnapshot,
+  FieldValue,
+  AggregateField,
+  AggregateSpec,
+} from 'firebase-admin/firestore';
+
+// ============================================================
+// FIRESTORE TOOLS
+// ============================================================
+
+export const firestoreTools: ToolDefinition[] = [
+  // ── firestore_query ──────────────────────────────────
+  {
+    name: 'firestore_query',
+    description:
+      'Query Firestore collections with filtering, ordering, and pagination. ' +
+      'Supports where clauses, order by, limit, and cursor-based pagination.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        collection: {
+          type: 'string',
+          description: 'Collection path (e.g., "users" or "users/uid1/orders")',
+        },
+        where: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              field: { type: 'string' },
+              operator: { type: 'string', enum: ['==', '!=', '<', '<=', '>', '>=', 'array-contains', 'array-contains-any', 'in', 'not-in'] },
+              value: { description: 'Value to compare against' },
+            },
+            required: ['field', 'operator', 'value'],
+          },
+          description: 'Array of where clauses for filtering',
+        },
+        orderBy: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              field: { type: 'string' },
+              direction: { type: 'string', enum: ['asc', 'desc'] },
+            },
+            required: ['field'],
+          },
+          description: 'Array of order-by specifications',
+        },
+        limit: { type: 'number', description: 'Maximum results (1-10000, default 100)' },
+        pageToken: { type: 'string', description: 'Pagination token from previous query result' },
+        select: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Fields to include in the result (projection)',
+        },
+      },
+      required: ['collection'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const collectionPath = validateCollectionPath(args['collection'] as string);
+        const limit = Math.min((args['limit'] as number) || 100, 10000);
+        const pageToken = args['pageToken'] as string | undefined;
+        const whereClauses = (args['where'] as Array<{ field: string; operator: string; value: unknown }>) || [];
+        const orderByClauses = (args['orderBy'] as Array<{ field: string; direction?: string }>) || [];
+        const selectFields = args['select'] as string[] | undefined;
+
+        const db = getFirestore();
+        let query: Query = db.collection(collectionPath);
+
+        // Apply where clauses
+        for (const w of whereClauses) {
+          const field = validateWhereField(w.field);
+          const op = validateOperator(w.operator);
+          query = query.where(field, op as WhereFilterOp, w.value);
+        }
+
+        // Apply orderBy
+        for (const o of orderByClauses) {
+          query = query.orderBy(o.field, (o.direction || 'asc') as 'asc' | 'desc');
+        }
+
+        // Apply pagination
+        if (pageToken) {
+          const decodedPath = Buffer.from(pageToken, 'base64').toString('utf-8');
+          const lastDocSnap = await db.doc(decodedPath).get();
+          if (lastDocSnap.exists) {
+            query = query.startAfter(lastDocSnap);
+          }
+        }
+
+        query = query.limit(limit);
+
+        // Apply field selection
+        if (selectFields && selectFields.length > 0) {
+          query = query.select(...selectFields);
+        }
+
+        const snapshot = await query.get();
+        const docs = snapshot.docs.map((doc: DocumentSnapshot) => ({
+          id: doc.id,
+          path: doc.ref.path,
+          data: doc.data(),
+        }));
+
+        let nextPageToken: string | undefined;
+        if (snapshot.size === limit && snapshot.docs.length > 0) {
+          const lastDoc = snapshot.docs[snapshot.docs.length - 1]!;
+          nextPageToken = Buffer.from(lastDoc.ref.path).toString('base64');
+        }
+
+        return formatListResult(docs, nextPageToken);
+      } catch (err) {
+        handleFirebaseError(err, 'firestore', 'query');
+      }
+    },
+  },
+
+  // ── firestore_get_document ────────────────────────────
+  {
+    name: 'firestore_get_document',
+    description: 'Get a single Firestore document by its full path.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'Full document path (e.g., "users/uid123")' },
+      },
+      required: ['path'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const docPath = validateDocumentPath(args['path'] as string);
+        const cacheKey = `doc:${docPath}`;
+
+        const cached = firestoreCache.get(cacheKey);
+        if (cached) {
+          return formatSuccess(cached);
+        }
+
+        const db = getFirestore();
+        const docSnap = await db.doc(docPath).get();
+
+        if (!docSnap.exists) {
+          return formatSuccess({
+            exists: false,
+            path: docPath,
+            message: `Document "${docPath}" does not exist.`,
+          });
+        }
+
+        const result = {
+          exists: true,
+          id: docSnap.id,
+          path: docSnap.ref.path,
+          data: docSnap.data(),
+        };
+
+        firestoreCache.set(cacheKey, result, 10_000);
+        return formatSuccess(result);
+      } catch (err) {
+        handleFirebaseError(err, 'firestore', 'get_document');
+      }
+    },
+  },
+
+  // ── firestore_add_document ────────────────────────────
+  {
+    name: 'firestore_add_document',
+    description:
+      'Add a new document to a Firestore collection. Auto-generates a document ID.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        collection: { type: 'string', description: 'Collection path' },
+        data: { type: 'object', description: 'Document data' },
+      },
+      required: ['collection', 'data'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const collectionPath = validateCollectionPath(args['collection'] as string);
+        const data = sanitizeData(args['data']);
+
+        const db = getFirestore();
+        const docRef = await db.collection(collectionPath).add({
+          ...(data as Record<string, unknown>),
+          _createdAt: FieldValue.serverTimestamp(),
+          _updatedAt: FieldValue.serverTimestamp(),
+        });
+
+        firestoreCache.invalidatePrefix(`doc:${collectionPath}`);
+
+        return formatSuccess({
+          id: docRef.id,
+          path: docRef.path,
+          message: `Document added successfully to "${collectionPath}".`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'firestore', 'add_document');
+      }
+    },
+  },
+
+  // ── firestore_set_document ────────────────────────────
+  {
+    name: 'firestore_set_document',
+    description:
+      'Create or overwrite a document at a specific path. Use merge: true to merge with existing data.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'Full document path (e.g., "users/uid123")' },
+        data: { type: 'object', description: 'Document data' },
+        merge: { type: 'boolean', description: 'If true, merge with existing data instead of overwriting (default: false)' },
+      },
+      required: ['path', 'data'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const docPath = validateDocumentPath(args['path'] as string);
+        const data = sanitizeData(args['data']);
+        const merge = (args['merge'] as boolean) || false;
+
+        const db = getFirestore();
+        await db.doc(docPath).set(
+          {
+            ...(data as Record<string, unknown>),
+            _updatedAt: FieldValue.serverTimestamp(),
+          },
+          { merge }
+        );
+
+        firestoreCache.delete(`doc:${docPath}`);
+        const parts = docPath.split('/');
+        parts.pop();
+        if (parts.length > 0) {
+          firestoreCache.invalidatePrefix(`doc:${parts.join('/')}`);
+        }
+
+        return formatSuccess({
+          path: docPath,
+          merged: merge,
+          message: `Document "${docPath}" ${merge ? 'merged' : 'set'} successfully.`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'firestore', 'set_document');
+      }
+    },
+  },
+
+  // ── firestore_update_document ─────────────────────────
+  {
+    name: 'firestore_update_document',
+    description:
+      'Update specific fields of an existing document. Only the provided fields are modified. ' +
+      'Use dot notation for nested fields (e.g., "address.city").',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'Full document path' },
+        data: { type: 'object', description: 'Fields to update (supports dot notation for nested fields)' },
+      },
+      required: ['path', 'data'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const docPath = validateDocumentPath(args['path'] as string);
+        const data = sanitizeData(args['data']);
+
+        const db = getFirestore();
+        const docRef = db.doc(docPath);
+
+        const docSnap = await docRef.get();
+        if (!docSnap.exists) {
+          return formatSuccess({
+            success: false,
+            message: `Document "${docPath}" does not exist. Use firestore_set_document to create it.`,
+          });
+        }
+
+        await docRef.update({
+          ...(data as Record<string, unknown>),
+          _updatedAt: FieldValue.serverTimestamp(),
+        });
+
+        firestoreCache.delete(`doc:${docPath}`);
+
+        return formatSuccess({
+          path: docPath,
+          message: `Document "${docPath}" updated successfully.`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'firestore', 'update_document');
+      }
+    },
+  },
+
+  // ── firestore_delete_document ─────────────────────────
+  {
+    name: 'firestore_delete_document',
+    description:
+      'Delete a Firestore document. Optionally delete all subcollections recursively.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'Full document path' },
+        recursive: { type: 'boolean', description: 'If true, delete all subcollections recursively (default: false)' },
+      },
+      required: ['path'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const docPath = validateDocumentPath(args['path'] as string);
+        const recursive = (args['recursive'] as boolean) || false;
+
+        const db = getFirestore();
+        const docRef = db.doc(docPath);
+
+        if (recursive) {
+          await deleteDocumentRecursive(db, docRef);
+        } else {
+          await docRef.delete();
+        }
+
+        firestoreCache.delete(`doc:${docPath}`);
+        const parts = docPath.split('/');
+        parts.pop();
+        if (parts.length > 0) {
+          firestoreCache.invalidatePrefix(`doc:${parts.join('/')}`);
+        }
+
+        return formatSuccess({
+          path: docPath,
+          recursive,
+          message: `Document "${docPath}" deleted${recursive ? ' recursively' : ''}.`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'firestore', 'delete_document');
+      }
+    },
+  },
+
+  // ── firestore_batch_write ─────────────────────────────
+  {
+    name: 'firestore_batch_write',
+    description:
+      'Execute multiple write operations atomically in a single batch. ' +
+      'Supports set, update, and delete operations. Maximum 500 operations per batch.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        operations: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              type: { type: 'string', enum: ['set', 'update', 'delete'], description: 'Operation type' },
+              path: { type: 'string', description: 'Document path' },
+              data: { type: 'object', description: 'Data for set/update operations' },
+              merge: { type: 'boolean', description: 'For set operations, merge with existing data' },
+            },
+            required: ['type', 'path'],
+          },
+          description: 'Array of write operations (max 500)',
+        },
+      },
+      required: ['operations'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const operations = args['operations'] as Array<{
+          type: 'set' | 'update' | 'delete';
+          path: string;
+          data?: Record<string, unknown>;
+          merge?: boolean;
+        }>;
+
+        if (!operations || operations.length === 0) {
+          throw new Error('Operations array cannot be empty.');
+        }
+        if (operations.length > 500) {
+          throw new Error(
+            'Batch write exceeds maximum of 500 operations. ' +
+            'Split into multiple batch writes of 500 or fewer operations.'
+          );
+        }
+
+        const db = getFirestore();
+        const batch = db.batch();
+
+        for (const op of operations) {
+          const docPath = validateDocumentPath(op.path);
+          const ref = db.doc(docPath);
+
+          switch (op.type) {
+            case 'set': {
+              const data = sanitizeData(op.data) as Record<string, unknown>;
+              batch.set(ref, {
+                ...data,
+                _updatedAt: FieldValue.serverTimestamp(),
+              }, { merge: op.merge ?? false });
+              break;
+            }
+            case 'update': {
+              const data = sanitizeData(op.data) as Record<string, unknown>;
+              batch.update(ref, {
+                ...data,
+                _updatedAt: FieldValue.serverTimestamp(),
+              });
+              break;
+            }
+            case 'delete': {
+              batch.delete(ref);
+              break;
+            }
+          }
+        }
+
+        await batch.commit();
+
+        for (const op of operations) {
+          firestoreCache.delete(`doc:${op.path}`);
+        }
+
+        return formatSuccess({
+          operationsCount: operations.length,
+          message: `Batch write completed successfully with ${operations.length} operations.`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'firestore', 'batch_write');
+      }
+    },
+  },
+
+  // ── firestore_transaction ─────────────────────────────
+  {
+    name: 'firestore_transaction',
+    description:
+      'Execute a transaction that reads documents and performs conditional writes atomically.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        readPaths: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Document paths to read at the start of the transaction',
+        },
+        operations: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              type: { type: 'string', enum: ['set', 'update', 'delete'] },
+              path: { type: 'string' },
+              data: { type: 'object' },
+              merge: { type: 'boolean' },
+            },
+            required: ['type', 'path'],
+          },
+          description: 'Write operations to execute',
+        },
+      },
+      required: ['readPaths', 'operations'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const readPaths = (args['readPaths'] as string[]).map((p) => validateDocumentPath(p));
+        const operations = args['operations'] as Array<{
+          type: 'set' | 'update' | 'delete';
+          path: string;
+          data?: Record<string, unknown>;
+          merge?: boolean;
+        }>;
+
+        const db = getFirestore();
+
+        const result = await db.runTransaction(async (transaction) => {
+          const reads: Record<string, unknown> = {};
+          for (const path of readPaths) {
+            const docSnap = await transaction.get(db.doc(path));
+            reads[path] = docSnap.exists ? { exists: true, data: docSnap.data() } : { exists: false };
+          }
+
+          for (const op of operations) {
+            const docPath = validateDocumentPath(op.path);
+            const ref = db.doc(docPath);
+
+            switch (op.type) {
+              case 'set': {
+                const data = sanitizeData(op.data) as Record<string, unknown>;
+                transaction.set(ref, {
+                  ...data,
+                  _updatedAt: FieldValue.serverTimestamp(),
+                }, { merge: op.merge ?? false });
+                break;
+              }
+              case 'update': {
+                const data = sanitizeData(op.data) as Record<string, unknown>;
+                transaction.update(ref, {
+                  ...data,
+                  _updatedAt: FieldValue.serverTimestamp(),
+                });
+                break;
+              }
+              case 'delete': {
+                transaction.delete(ref);
+                break;
+              }
+            }
+          }
+
+          return reads;
+        });
+
+        return formatSuccess({
+          readDocuments: result,
+          writesApplied: operations.length,
+          message: 'Transaction completed successfully.',
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'firestore', 'transaction');
+      }
+    },
+  },
+
+  // ── firestore_list_collections ────────────────────────
+  {
+    name: 'firestore_list_collections',
+    description:
+      'List subcollections of a document, or root-level collections if no document path is provided.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        documentPath: { type: 'string', description: 'Optional document path to list its subcollections' },
+      },
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const db = getFirestore();
+        const docPath = args['documentPath'] as string | undefined;
+
+        let collections: FirebaseFirestore.CollectionReference[];
+        if (docPath) {
+          validateDocumentPath(docPath);
+          collections = await db.doc(docPath).listCollections();
+        } else {
+          collections = await db.listCollections();
+        }
+
+        const result = collections.map((col) => ({
+          id: col.id,
+          path: col.path,
+        }));
+
+        return formatSuccess(result);
+      } catch (err) {
+        handleFirebaseError(err, 'firestore', 'list_collections');
+      }
+    },
+  },
+
+  // ── firestore_list_subcollections ─────────────────────
+  {
+    name: 'firestore_list_subcollections',
+    description: 'List all subcollections of a specific document.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'Document path to inspect' },
+      },
+      required: ['path'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const docPath = validateDocumentPath(args['path'] as string);
+        const db = getFirestore();
+        const collections = await db.doc(docPath).listCollections();
+
+        const result = collections.map((col) => ({
+          id: col.id,
+          path: col.path,
+        }));
+
+        return formatSuccess({
+          documentPath: docPath,
+          subcollections: result,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'firestore', 'list_subcollections');
+      }
+    },
+  },
+
+  // ── firestore_aggregate_query ─────────────────────────
+  {
+    name: 'firestore_aggregate_query',
+    description:
+      'Run aggregation queries (count, sum, average) on Firestore collections with optional filters.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        collection: { type: 'string', description: 'Collection path' },
+        aggregations: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              type: { type: 'string', enum: ['count', 'sum', 'avg'], description: 'Aggregation type' },
+              field: { type: 'string', description: 'Field to aggregate (not needed for count)' },
+              alias: { type: 'string', description: 'Alias for the result' },
+            },
+            required: ['type'],
+          },
+          description: 'Aggregation operations to perform',
+        },
+        where: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              field: { type: 'string' },
+              operator: { type: 'string' },
+              value: {},
+            },
+            required: ['field', 'operator', 'value'],
+          },
+          description: 'Optional where clauses to filter before aggregating',
+        },
+      },
+      required: ['collection', 'aggregations'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const collectionPath = validateCollectionPath(args['collection'] as string);
+        const aggregations = args['aggregations'] as Array<{
+          type: 'count' | 'sum' | 'avg';
+          field?: string;
+          alias?: string;
+        }>;
+        const whereClauses = (args['where'] as Array<{ field: string; operator: string; value: unknown }>) || [];
+
+        const db = getFirestore();
+        let query: Query = db.collection(collectionPath);
+
+        for (const w of whereClauses) {
+          const field = validateWhereField(w.field);
+          const op = validateOperator(w.operator);
+          query = query.where(field, op as WhereFilterOp, w.value);
+        }
+
+        const aggregateSpec: AggregateSpec = {};
+        for (const agg of aggregations) {
+          const alias = agg.alias || `${agg.type}_${agg.field || 'all'}`;
+          switch (agg.type) {
+            case 'count':
+              aggregateSpec[alias] = AggregateField.count();
+              break;
+            case 'sum':
+              if (!agg.field) throw new Error('Sum aggregation requires a "field" parameter.');
+              aggregateSpec[alias] = AggregateField.sum(agg.field);
+              break;
+            case 'avg':
+              if (!agg.field) throw new Error('Average aggregation requires a "field" parameter.');
+              aggregateSpec[alias] = AggregateField.average(agg.field);
+              break;
+          }
+        }
+
+        const snapshot = await query.aggregate(aggregateSpec).get();
+        const results: Record<string, unknown> = {};
+        for (const agg of aggregations) {
+          const alias = agg.alias || `${agg.type}_${agg.field || 'all'}`;
+          results[alias] = snapshot.data()[alias];
+        }
+
+        return formatSuccess(results);
+      } catch (err) {
+        handleFirebaseError(err, 'firestore', 'aggregate_query');
+      }
+    },
+  },
+
+  // ── firestore_listen_changes ──────────────────────────
+  {
+    name: 'firestore_listen_changes',
+    description:
+      'Listen for real-time changes on a Firestore collection or document for a short duration.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'Collection or document path to watch' },
+        durationMs: { type: 'number', description: 'Duration to listen in milliseconds (1000-30000, default 5000)' },
+      },
+      required: ['path'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const path = (args['path'] as string).trim();
+        const durationMs = Math.min(Math.max((args['durationMs'] as number) || 5000, 1000), 30000);
+
+        const db = getFirestore();
+        const segments = path.split('/');
+        const changes: Array<{
+          type: string;
+          path: string;
+          data?: unknown;
+          duration: number;
+        }> = [];
+
+        let unsubscribe: (() => void) | undefined;
+
+        const startTime = Date.now();
+
+        await new Promise<void>((resolve) => {
+          if (segments.length % 2 === 0) {
+            validateDocumentPath(path);
+            unsubscribe = db.doc(path).onSnapshot(
+              (snap) => {
+                changes.push({
+                  type: snap.exists ? 'modified' : 'removed',
+                  path: snap.ref.path,
+                  data: snap.data(),
+                  duration: Date.now() - startTime,
+                });
+              },
+              (err) => {
+                changes.push({
+                  type: 'error',
+                  path,
+                  data: err.message,
+                  duration: Date.now() - startTime,
+                });
+              }
+            );
+          } else {
+            validateCollectionPath(path);
+            unsubscribe = db.collection(path).onSnapshot(
+              (snap) => {
+                snap.docChanges().forEach((change) => {
+                  changes.push({
+                    type: change.type,
+                    path: change.doc.ref.path,
+                    data: change.doc.data(),
+                    duration: Date.now() - startTime,
+                  });
+                });
+              },
+              (err) => {
+                changes.push({
+                  type: 'error',
+                  path,
+                  data: err.message,
+                  duration: Date.now() - startTime,
+                });
+              }
+            );
+          }
+
+          setTimeout(() => {
+            if (unsubscribe) unsubscribe();
+            resolve();
+          }, durationMs);
+        });
+
+        return formatSuccess({
+          path,
+          listenedForMs: durationMs,
+          changesDetected: changes.length,
+          changes,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'firestore', 'listen_changes');
+      }
+    },
+  },
+
+  // ── firestore_infer_schema ────────────────────────────
+  {
+    name: 'firestore_infer_schema',
+    description:
+      'Infer the schema of a Firestore collection by sampling documents. Returns field names, types, and occurrence counts.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        collection: { type: 'string', description: 'Collection path to analyze' },
+        sampleSize: { type: 'number', description: 'Number of documents to sample (1-100, default 20)' },
+      },
+      required: ['collection'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const collectionPath = validateCollectionPath(args['collection'] as string);
+        const sampleSize = Math.min(Math.max((args['sampleSize'] as number) || 20, 1), 100);
+
+        const cacheKey = `schema:${collectionPath}`;
+        const cached = schemaCache.get(cacheKey);
+        if (cached) {
+          return formatSuccess(cached);
+        }
+
+        const db = getFirestore();
+        const snapshot = await db.collection(collectionPath).limit(sampleSize).get();
+
+        if (snapshot.empty) {
+          return formatSuccess({
+            collection: collectionPath,
+            documentCount: 0,
+            message: 'Collection is empty. No schema to infer.',
+          });
+        }
+
+        const fieldStats: Record<string, {
+          types: Record<string, number>;
+          count: number;
+          nullable: boolean;
+          sampleValues: unknown[];
+        }> = {};
+
+        for (const doc of snapshot.docs) {
+          const data = doc.data();
+          inferFields(data, '', fieldStats, 0);
+        }
+
+        const totalDocs = snapshot.size;
+        const schema: Record<string, unknown> = {};
+        for (const [field, stats] of Object.entries(fieldStats)) {
+          const dominantType = Object.entries(stats.types)
+            .sort((a, b) => b[1] - a[1])[0]![0];
+          schema[field] = {
+            type: dominantType,
+            presence: `${((stats.count / totalDocs) * 100).toFixed(1)}%`,
+            nullable: stats.nullable,
+            sampleValues: stats.sampleValues.slice(0, 3),
+          };
+        }
+
+        const result = {
+          collection: collectionPath,
+          documentsSampled: totalDocs,
+          fields: schema,
+        };
+
+        schemaCache.set(cacheKey, result, 10 * 60 * 1000);
+        return formatSuccess(result);
+      } catch (err) {
+        handleFirebaseError(err, 'firestore', 'infer_schema');
+      }
+    },
+  },
+];
+
+// ── Helpers ──────────────────────────────────────────────
+
+async function deleteDocumentRecursive(db: Firestore, docRef: FirebaseFirestore.DocumentReference): Promise<void> {
+  const collections = await docRef.listCollections();
+  for (const col of collections) {
+    const snapshot = await col.limit(500).get();
+    for (const doc of snapshot.docs) {
+      await deleteDocumentRecursive(db, doc.ref);
+    }
+  }
+  await docRef.delete();
+}
+
+function inferFields(
+  data: unknown,
+  prefix: string,
+  fieldStats: Record<string, { types: Record<string, number>; count: number; nullable: boolean; sampleValues: unknown[] }>,
+  depth: number
+): void {
+  if (depth > 10) return;
+
+  if (data === null || data === undefined) return;
+
+  if (typeof data !== 'object' || Array.isArray(data)) return;
+
+  for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+    if (key.startsWith('_')) continue;
+    const fieldPath = prefix ? `${prefix}.${key}` : key;
+
+    if (!fieldStats[fieldPath]) {
+      fieldStats[fieldPath] = { types: {}, count: 0, nullable: false, sampleValues: [] };
+    }
+
+    const stats = fieldStats[fieldPath]!;
+    stats.count++;
+
+    if (value === null || value === undefined) {
+      stats.nullable = true;
+      stats.types['null'] = (stats.types['null'] || 0) + 1;
+    } else if (Array.isArray(value)) {
+      stats.types['array'] = (stats.types['array'] || 0) + 1;
+      if (stats.sampleValues.length < 3) {
+        stats.sampleValues.push(value.slice(0, 2));
+      }
+    } else if (value instanceof Date) {
+      stats.types['timestamp'] = (stats.types['timestamp'] || 0) + 1;
+      if (stats.sampleValues.length < 3) {
+        stats.sampleValues.push(value.toISOString());
+      }
+    } else if (typeof value === 'object') {
+      stats.types['map'] = (stats.types['map'] || 0) + 1;
+      inferFields(value, fieldPath, fieldStats, depth + 1);
+    } else {
+      const type = typeof value;
+      stats.types[type] = (stats.types[type] || 0) + 1;
+      if (stats.sampleValues.length < 3) {
+        stats.sampleValues.push(value);
+      }
+    }
+  }
+}