@theihtisham/mcp-server-firebase 1.0.0

package/src/utils/cache.ts

@@ -0,0 +1,82 @@
+interface CacheEntry<T> {
+  value: T;
+  expiresAt: number;
+}
+
+export class LRUCache<T> {
+  private cache = new Map<string, CacheEntry<T>>();
+  private readonly maxSize: number;
+  private readonly defaultTtlMs: number;
+
+  constructor(maxSize = 200, defaultTtlMs = 5 * 60 * 1000) {
+    this.maxSize = maxSize;
+    this.defaultTtlMs = defaultTtlMs;
+  }
+
+  get(key: string): T | undefined {
+    const entry = this.cache.get(key);
+    if (!entry) return undefined;
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return undefined;
+    }
+    // Move to end (most recently used)
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    return entry.value;
+  }
+
+  set(key: string, value: T, ttlMs?: number): void {
+    // Remove if exists to update position
+    this.cache.delete(key);
+    // Evict oldest entries if at capacity
+    while (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
+      }
+    }
+    this.cache.set(key, {
+      value,
+      expiresAt: Date.now() + (ttlMs ?? this.defaultTtlMs),
+    });
+  }
+
+  delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+
+  has(key: string): boolean {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  // Invalidate keys matching a prefix (useful for collection-level cache invalidation)
+  invalidatePrefix(prefix: string): number {
+    let count = 0;
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        this.cache.delete(key);
+        count++;
+      }
+    }
+    return count;
+  }
+}
+
+// Singleton caches for the server
+export const firestoreCache = new LRUCache<unknown>(500, 30_000); // 30s TTL for Firestore reads
+export const schemaCache = new LRUCache<unknown>(50, 10 * 60 * 1000); // 10min TTL for schema inference

package/src/utils/errors.ts

@@ -0,0 +1,110 @@
+export interface FirebaseErrorContext {
+  service: string;
+  operation: string;
+  suggestion?: string;
+  details?: string;
+}
+
+export class FirebaseToolError extends Error {
+  public readonly context: FirebaseErrorContext;
+
+  constructor(message: string, context: FirebaseErrorContext) {
+    super(message);
+    this.name = 'FirebaseToolError';
+    this.context = context;
+  }
+
+  toStructuredMessage(): string {
+    const lines: string[] = [
+      `[${this.context.service}/${this.context.operation}] ${this.message}`,
+    ];
+    if (this.context.details) {
+      lines.push(`  Details: ${this.context.details}`);
+    }
+    if (this.context.suggestion) {
+      lines.push(`  Suggestion: ${this.context.suggestion}`);
+    }
+    return lines.join('\n');
+  }
+}
+
+export function handleFirebaseError(error: unknown, service: string, operation: string): never {
+  if (error instanceof FirebaseToolError) {
+    throw error;
+  }
+
+  const err = error as Error & { code?: string; status?: number };
+
+  let suggestion: string | undefined;
+  let details: string | undefined;
+
+  // Map common Firebase error codes to actionable suggestions
+  if (err.code) {
+    switch (err.code) {
+      case 'permission-denied':
+      case 'PERMISSION_DENIED':
+        suggestion = 'Check that your service account has the required IAM permissions for this operation.';
+        break;
+      case 'not-found':
+      case 'NOT_FOUND':
+        suggestion = 'Verify that the resource (document, collection, user, or file) exists and the path is correct.';
+        break;
+      case 'already-exists':
+      case 'ALREADY_EXISTS':
+        suggestion = 'A resource with this identifier already exists. Use update instead of create, or provide a different ID.';
+        break;
+      case 'invalid-argument':
+      case 'INVALID_ARGUMENT':
+        suggestion = 'Check that all required fields are provided and values are in the correct format.';
+        break;
+      case 'resource-exhausted':
+      case 'RESOURCE_EXHAUSTED':
+        suggestion = 'Firebase quota exceeded. Wait and retry, or upgrade your Firebase plan.';
+        break;
+      case 'unauthenticated':
+      case 'UNAUTHENTICATED':
+        suggestion = 'Service account authentication failed. Verify FIREBASE_SERVICE_ACCOUNT_PATH or FIREBASE_SERVICE_ACCOUNT_KEY is set correctly.';
+        break;
+      case 'unavailable':
+      case 'UNAVAILABLE':
+        suggestion = 'Firebase service is temporarily unavailable. Retry with exponential backoff.';
+        break;
+      case 'deadline-exceeded':
+      case 'DEADLINE_EXCEEDED':
+        suggestion = 'Operation timed out. Try reducing the data size or splitting into smaller batches.';
+        break;
+      default:
+        break;
+    }
+  }
+
+  details = err.message;
+
+  throw new FirebaseToolError(
+    err.message || 'An unknown error occurred.',
+    { service, operation, suggestion, details }
+  );
+}
+
+export function formatSuccess(data: unknown, operation?: string): string {
+  return JSON.stringify({
+    success: true,
+    ...(operation && { operation }),
+    data,
+    timestamp: new Date().toISOString(),
+  }, null, 2);
+}
+
+export function formatListResult(
+  items: unknown[],
+  pageToken?: string,
+  totalCount?: number
+): string {
+  return JSON.stringify({
+    success: true,
+    count: items.length,
+    ...(totalCount !== undefined && { totalCount }),
+    ...(pageToken && { nextPageToken: pageToken }),
+    items,
+  }, null, 2);
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export { validateCollectionPath, validateDocumentPath, validateStoragePath, validateEmail, validateUid, validateLimit, validatePageSize, validateWhereField, validateOperator, sanitizeData, CollectionPathSchema, DocumentPathSchema, StoragePathSchema, UidSchema, EmailSchema, DataSchema, LimitSchema, PageSizeSchema, } from './validation.js';
+export { FirebaseToolError, handleFirebaseError, formatSuccess, formatListResult, } from './errors.js';
+export { LRUCache, firestoreCache, schemaCache } from './cache.js';
+export { paginatedQuery, fetchAllDocuments, encodePageToken, decodePageToken, } from './pagination.js';

package/src/utils/pagination.ts

@@ -0,0 +1,105 @@
+import { Query, DocumentSnapshot } from 'firebase-admin/firestore';
+import { validatePageSize } from './validation.js';
+
+export interface PaginationOptions {
+  pageSize: number;
+  pageToken?: string;
+}
+
+export interface PaginatedResult<T> {
+  items: T[];
+  nextPageToken?: string;
+  hasMore: boolean;
+  totalCount: number;
+}
+
+/**
+ * Execute a paginated Firestore query.
+ */
+export async function paginatedQuery<T>(
+  baseQuery: Query,
+  options: PaginationOptions,
+  transform: (snap: DocumentSnapshot) => T
+): Promise<PaginatedResult<T>> {
+  const pageSize = validatePageSize(options.pageSize);
+  let query = baseQuery.limit(pageSize);
+  const allItems: T[] = [];
+  let lastDoc: DocumentSnapshot | undefined;
+
+  if (options.pageToken) {
+    const decodedToken = Buffer.from(options.pageToken, 'base64').toString('utf-8');
+    const lastDocRef = baseQuery.firestore.doc(decodedToken);
+    const lastDocSnap = await lastDocRef.get();
+    if (lastDocSnap.exists) {
+      query = query.startAfter(lastDocSnap);
+    }
+  }
+
+  const snapshot = await query.get();
+
+  for (const doc of snapshot.docs) {
+    allItems.push(transform(doc));
+    lastDoc = doc;
+  }
+
+  const hasMore = snapshot.size === pageSize;
+
+  let nextToken: string | undefined;
+  if (hasMore && lastDoc) {
+    nextToken = Buffer.from(lastDoc.ref.path).toString('base64');
+  }
+
+  return {
+    items: allItems,
+    nextPageToken: nextToken,
+    hasMore,
+    totalCount: allItems.length,
+  };
+}
+
+/**
+ * Fetch all documents from a collection with automatic pagination.
+ */
+export async function fetchAllDocuments<T>(
+  baseQuery: Query,
+  transform: (snap: DocumentSnapshot) => T,
+  pageSize = 500,
+  maxTotal = 10000
+): Promise<T[]> {
+  let query = baseQuery.limit(pageSize);
+  const allItems: T[] = [];
+  let lastDoc: DocumentSnapshot | undefined;
+
+  while (allItems.length < maxTotal) {
+    if (lastDoc) {
+      query = baseQuery.limit(pageSize).startAfter(lastDoc);
+    }
+
+    const snapshot = await query.get();
+
+    for (const doc of snapshot.docs) {
+      allItems.push(transform(doc));
+      lastDoc = doc;
+    }
+
+    if (snapshot.size < pageSize) {
+      break;
+    }
+  }
+
+  return allItems;
+}
+
+/**
+ * Encode a document snapshot as a page token.
+ */
+export function encodePageToken(docPath: string): string {
+  return Buffer.from(docPath).toString('base64');
+}
+
+/**
+ * Decode a page token back to a document path.
+ */
+export function decodePageToken(token: string): string {
+  return Buffer.from(token, 'base64').toString('utf-8');
+}

package/src/utils/validation.ts

@@ -0,0 +1,212 @@
+import { z } from 'zod';
+
+// Shared validation schemas and input sanitization utilities
+
+export const pathSegmentRegex = /^[a-zA-Z0-9_-]+$/;
+export const collectionPathRegex = /^(?:[a-zA-Z0-9_-]+\/(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9_-]+|[a-zA-Z0-9_-]+)$/;
+
+export function validateCollectionPath(path: string): string {
+  const trimmed = path.trim();
+  if (trimmed.length === 0) {
+    throw new Error('Collection path cannot be empty.');
+  }
+  if (trimmed.length > 1500) {
+    throw new Error('Collection path exceeds maximum length of 1500 characters.');
+  }
+  if (!collectionPathRegex.test(trimmed)) {
+    throw new Error(
+      `Invalid collection path: "${trimmed}". ` +
+      'Path segments must contain only letters, numbers, hyphens, and underscores. ' +
+      'Use forward slashes to separate segments (e.g., "users" or "users/uid123/posts").'
+    );
+  }
+  return trimmed;
+}
+
+export function validateDocumentPath(path: string): string {
+  const trimmed = path.trim();
+  if (trimmed.length === 0) {
+    throw new Error('Document path cannot be empty.');
+  }
+  if (trimmed.length > 1500) {
+    throw new Error('Document path exceeds maximum length of 1500 characters.');
+  }
+  const segments = trimmed.split('/');
+  if (segments.length % 2 !== 0) {
+    throw new Error(
+      `Invalid document path: "${trimmed}". ` +
+      'Document paths must have an even number of segments (e.g., "users/uid123" or "users/uid123/posts/post1").'
+    );
+  }
+  for (const seg of segments) {
+    if (!pathSegmentRegex.test(seg)) {
+      throw new Error(
+        `Invalid segment "${seg}" in document path. ` +
+        'Segments must contain only letters, numbers, hyphens, and underscores.'
+      );
+    }
+  }
+  return trimmed;
+}
+
+export function validateStoragePath(path: string): string {
+  const trimmed = path.trim();
+  if (trimmed.length === 0) {
+    throw new Error('Storage path cannot be empty.');
+  }
+  if (trimmed.startsWith('/')) {
+    throw new Error(
+      `Invalid storage path: "${trimmed}". ` +
+      'Path must not start with "/" to prevent path traversal.'
+    );
+  }
+  if (trimmed.startsWith('..')) {
+    throw new Error(
+      `Invalid storage path: "${trimmed}". ` +
+      'Path must not start with ".." to prevent path traversal.'
+    );
+  }
+  if (trimmed.includes('..')) {
+    throw new Error(
+      `Invalid storage path: "${trimmed}". ` +
+      'Path must not contain ".." to prevent path traversal.'
+    );
+  }
+  return trimmed;
+}
+
+export function validateEmail(email: string): string {
+  const trimmed = email.trim().toLowerCase();
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailRegex.test(trimmed)) {
+    throw new Error(
+      `Invalid email address: "${email}". ` +
+      'Please provide a valid email (e.g., user@example.com).'
+    );
+  }
+  return trimmed;
+}
+
+export function validateUid(uid: string): string {
+  const trimmed = uid.trim();
+  if (trimmed.length === 0) {
+    throw new Error('UID cannot be empty.');
+  }
+  if (trimmed.length > 128) {
+    throw new Error('UID exceeds maximum length of 128 characters.');
+  }
+  return trimmed;
+}
+
+export function validateLimit(limit: number, max = 10000): number {
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new Error(`Limit must be a positive integer, got: ${limit}.`);
+  }
+  if (limit > max) {
+    throw new Error(`Limit exceeds maximum of ${max}. Use pagination to retrieve more results.`);
+  }
+  return limit;
+}
+
+export function validatePageSize(size: number, max = 1000): number {
+  if (!Number.isInteger(size) || size < 1) {
+    throw new Error(`Page size must be a positive integer, got: ${size}.`);
+  }
+  if (size > max) {
+    throw new Error(`Page size exceeds maximum of ${max}.`);
+  }
+  return size;
+}
+
+export function validateWhereField(field: string): string {
+  const trimmed = field.trim();
+  if (trimmed.length === 0) {
+    throw new Error('Where clause field cannot be empty.');
+  }
+  // Prevent NoSQL injection: disallow field paths that try to access internals
+  if (trimmed.startsWith('__') || trimmed.includes('$')) {
+    throw new Error(
+      `Invalid field name: "${trimmed}". ` +
+      'Field names must not start with "__" or contain "$".'
+    );
+  }
+  return trimmed;
+}
+
+export function validateOperator(op: string): string {
+  const allowed = [
+    '==', '!=', '<', '<=', '>', '>=',
+    'array-contains', 'array-contains-any', 'in', 'not-in',
+  ];
+  if (!allowed.includes(op)) {
+    throw new Error(
+      `Invalid operator: "${op}". ` +
+      `Allowed operators: ${allowed.join(', ')}.`
+    );
+  }
+  return op;
+}
+
+export function sanitizeData(data: unknown): unknown {
+  if (data === null || data === undefined) {
+    return data;
+  }
+  if (typeof data === 'string' || typeof data === 'number' || typeof data === 'boolean') {
+    return data;
+  }
+  if (data instanceof Date) {
+    return data;
+  }
+  if (Array.isArray(data)) {
+    return data.map(sanitizeData);
+  }
+  if (typeof data === 'object') {
+    const sanitized: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+      if (key.startsWith('$')) {
+        throw new Error(
+          `Invalid field key: "${key}". ` +
+          'Keys must not start with "$" to prevent NoSQL injection.'
+        );
+      }
+      if (key.includes('.')) {
+        throw new Error(
+          `Invalid field key: "${key}". ` +
+          'Keys must not contain "." to prevent NoSQL injection.'
+        );
+      }
+      sanitized[key] = sanitizeData(value);
+    }
+    return sanitized;
+  }
+  return data;
+}
+
+// Common Zod schemas for tool parameters
+export const CollectionPathSchema = z.string().min(1).describe(
+  'Firestore collection path (e.g., "users" or "users/uid123/orders")'
+);
+
+export const DocumentPathSchema = z.string().min(1).describe(
+  'Firestore document path (e.g., "users/uid123" or "users/uid123/orders/order1")'
+);
+
+export const StoragePathSchema = z.string().min(1).describe(
+  'Cloud Storage path (e.g., "images/photo.jpg")'
+);
+
+export const UidSchema = z.string().min(1).describe('Firebase Auth UID');
+
+export const EmailSchema = z.string().email().describe('User email address');
+
+export const DataSchema = z.record(z.unknown()).describe(
+  'Document data as a JSON object'
+);
+
+export const LimitSchema = z.number().int().min(1).max(10000).optional().default(100).describe(
+  'Maximum number of results to return (1-10000, default: 100)'
+);
+
+export const PageSizeSchema = z.number().int().min(1).max(1000).optional().default(100).describe(
+  'Number of results per page (1-1000, default: 100)'
+);

package/tests/cache.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { LRUCache } from '../src/utils/cache.js';
+
+describe('LRUCache', () => {
+  let cache: LRUCache<string>;
+
+  beforeEach(() => {
+    cache = new LRUCache<string>(3, 1000); // max 3 entries, 1s TTL
+  });
+
+  it('stores and retrieves values', () => {
+    cache.set('a', 'value-a');
+    expect(cache.get('a')).toBe('value-a');
+  });
+
+  it('returns undefined for missing keys', () => {
+    expect(cache.get('nonexistent')).toBeUndefined();
+  });
+
+  it('evicts oldest entries when at capacity', () => {
+    cache.set('a', 'va');
+    cache.set('b', 'vb');
+    cache.set('c', 'vc');
+    cache.set('d', 'vd'); // should evict 'a'
+
+    expect(cache.get('a')).toBeUndefined();
+    expect(cache.get('b')).toBe('vb');
+    expect(cache.get('c')).toBe('vc');
+    expect(cache.get('d')).toBe('vd');
+  });
+
+  it('evicts least recently used entries', () => {
+    cache.set('a', 'va');
+    cache.set('b', 'vb');
+    cache.set('c', 'vc');
+
+    // Access 'a' to make it recently used
+    cache.get('a');
+
+    cache.set('d', 'vd'); // should evict 'b' (LRU)
+
+    expect(cache.get('a')).toBe('va');
+    expect(cache.get('b')).toBeUndefined();
+    expect(cache.get('c')).toBe('vc');
+    expect(cache.get('d')).toBe('vd');
+  });
+
+  it('expires entries after TTL', () => {
+    cache.set('a', 'va', 50); // 50ms TTL
+    expect(cache.get('a')).toBe('va');
+
+    return new Promise<void>((resolve) => {
+      setTimeout(() => {
+        expect(cache.get('a')).toBeUndefined();
+        resolve();
+      }, 100);
+    });
+  });
+
+  it('deletes entries', () => {
+    cache.set('a', 'va');
+    expect(cache.delete('a')).toBe(true);
+    expect(cache.get('a')).toBeUndefined();
+    expect(cache.delete('a')).toBe(false);
+  });
+
+  it('clears all entries', () => {
+    cache.set('a', 'va');
+    cache.set('b', 'vb');
+    cache.clear();
+    expect(cache.size).toBe(0);
+    expect(cache.get('a')).toBeUndefined();
+  });
+
+  it('reports correct size', () => {
+    expect(cache.size).toBe(0);
+    cache.set('a', 'va');
+    expect(cache.size).toBe(1);
+    cache.set('b', 'vb');
+    expect(cache.size).toBe(2);
+  });
+
+  it('checks has() correctly', () => {
+    cache.set('a', 'va');
+    expect(cache.has('a')).toBe(true);
+    expect(cache.has('b')).toBe(false);
+  });
+
+  it('has() returns false for expired entries', () => {
+    cache.set('a', 'va', 50);
+    expect(cache.has('a')).toBe(true);
+
+    return new Promise<void>((resolve) => {
+      setTimeout(() => {
+        expect(cache.has('a')).toBe(false);
+        resolve();
+      }, 100);
+    });
+  });
+
+  it('invalidates entries by prefix', () => {
+    cache.set('doc:users/a', 'va');
+    cache.set('doc:users/b', 'vb');
+    cache.set('doc:orders/1', 'vc');
+
+    const count = cache.invalidatePrefix('doc:users');
+    expect(count).toBe(2);
+    expect(cache.get('doc:users/a')).toBeUndefined();
+    expect(cache.get('doc:users/b')).toBeUndefined();
+    expect(cache.get('doc:orders/1')).toBe('vc');
+  });
+
+  it('updates existing key position', () => {
+    cache.set('a', 'va');
+    cache.set('b', 'vb');
+    cache.set('c', 'vc');
+
+    // Update 'a' to move it to end
+    cache.set('a', 'va-updated');
+
+    cache.set('d', 'vd'); // should evict 'b' (now LRU)
+
+    expect(cache.get('a')).toBe('va-updated');
+    expect(cache.get('b')).toBeUndefined();
+  });
+
+  it('allows custom TTL per entry', () => {
+    cache.set('short', 'vs', 50);
+    cache.set('long', 'vl', 5000);
+
+    return new Promise<void>((resolve) => {
+      setTimeout(() => {
+        expect(cache.get('short')).toBeUndefined();
+        expect(cache.get('long')).toBe('vl');
+        resolve();
+      }, 100);
+    });
+  });
+});