firestore_list_documents

Instructions

Implementation Reference

• src/lib/firebase/firestoreClient.ts:61-117 (handler)

  Core handler function for firestore_list_documents tool: queries Firestore collection with optional filters, pagination via pageToken, converts timestamps, generates console URLs, and returns paginated document list with total count.

  export async function listDocuments(collection: string, filters: Array<{ field: string, operator: FirebaseFirestore.WhereFilterOp, value: any }> = [], limit: number = 20, pageToken?: string) {
    const projectId = getProjectId();
    try {
      if (!db) {
        return { content: [{ type: 'text', text: 'Firebase is not initialized. SERVICE_ACCOUNT_KEY_PATH environment variable is required.' }], isError: true };
      }
      
      const collectionRef = db.collection(collection);
      let filteredQuery: Query = collectionRef;
      for (const filter of filters) {
        let filterValue = filter.value;
        if (typeof filterValue === 'string' && !isNaN(Date.parse(filterValue))) {
          filterValue = Timestamp.fromDate(new Date(filterValue));
        }
        filteredQuery = filteredQuery.where(filter.field, filter.operator, filterValue);
      }
      
      // Apply pageToken if provided
      if (pageToken) {
        const startAfterDoc = await collectionRef.doc(pageToken).get();
        filteredQuery = filteredQuery.startAfter(startAfterDoc);
      }
  
      // Get total count of documents matching the filter
      const countSnapshot = await filteredQuery.get();
      const totalCount = countSnapshot.size;
  
      // Get the first 'limit' documents
      const limitedQuery = filteredQuery.limit(limit);
      const snapshot = await limitedQuery.get();
  
      if (snapshot.empty) {
        return { content: [{ type: 'text', text: 'No matching documents found' }], isError: true };
      }
      
      const documents = snapshot.docs.map((doc: any) => {
        const data = doc.data();
        convertTimestampsToISO(data);
        const consoleUrl = `https://console.firebase.google.com/project/${projectId}/firestore/data/${collection}/${doc.id}`;
        return { id: doc.id, url: consoleUrl, document: data };
      });
      
      return { 
        content: [{
          type: 'text', 
          text: JSON.stringify({
            totalCount,
            documents,
            pageToken: documents.length > 0 ? documents[documents.length - 1].id : null,
            hasMore: totalCount > limit
          })
        }]
      };
    } catch (error) {
      return { content: [{ type: 'text', text: `Error listing documents: ${(error as Error).message}` }], isError: true };
    }
  }

• src/index.ts:79-121 (schema)

  Input schema definition for the firestore_list_documents tool, including parameters for collection, filters, limit, and pageToken.

  name: 'firestore_list_documents',
  description: 'List documents from a Firestore collection with optional filtering',
  inputSchema: {
    type: 'object',
    properties: {
      collection: {
        type: 'string',
        description: 'Collection name'
      },
      filters: {
        type: 'array',
        description: 'Array of filter conditions',
        items: {
          type: 'object',
          properties: {
            field: {
              type: 'string',
              description: 'Field name to filter'
            },
            operator: {
              type: 'string',
              description: 'Comparison operator'
            },
            value: {
              type: 'any',
              description: 'Value to compare against (use ISO format for dates)'
            }
          },
          required: ['field', 'operator', 'value']
        }
      },
    limit: {
      type: 'number',
      description: 'Number of documents to return',
      default: 20
    },
    pageToken: {
      type: 'string',
      description: 'Token for pagination to get the next page of results'
    }
    },
    required: ['collection']
  }

• src/index.ts:231-237 (registration)

  Tool dispatch/registration in the CallToolRequestSchema handler: maps tool call to the listDocuments implementation.

  case 'firestore_list_documents':
    return listDocuments(
      args.collection as string,
      args.filters as Array<{ field: string, operator: FirebaseFirestore.WhereFilterOp, value: any }>,
      args.limit as number,
      args.pageToken as string | undefined
    );

• src/lib/firebase/firestoreClient.ts:51-58 (helper)

  Helper function used in listDocuments to convert Firestore Timestamp fields to ISO strings for JSON output.

  function convertTimestampsToISO(data: any) {
    for (const key in data) {
      if (data[key] instanceof Timestamp) {
        data[key] = data[key].toDate().toISOString();
      }
    }
    return data;
  }