@theihtisham/mcp-server-firebase 1.0.0

package/src/tools/realtime-db.ts

@@ -0,0 +1,307 @@
+import { getRealtimeDb } from '../services/firebase.js';
+import {
+  handleFirebaseError,
+  formatSuccess,
+} from '../utils/index.js';
+import type { ToolDefinition } from './types.js';
+import type { Query } from 'firebase-admin/database';
+
+// ============================================================
+// REALTIME DATABASE TOOLS
+// ============================================================
+
+export function validateRtdbPath(path: string): string {
+  const trimmed = path.trim();
+  if (trimmed.length === 0) {
+    throw new Error('Realtime Database path cannot be empty.');
+  }
+  if (!trimmed.startsWith('/')) {
+    throw new Error(
+      `Invalid Realtime Database path: "${trimmed}". Path must start with "/".`
+    );
+  }
+  if (trimmed.includes('//')) {
+    throw new Error(
+      `Invalid Realtime Database path: "${trimmed}". Path must not contain "//".`
+    );
+  }
+  if (trimmed.includes('..')) {
+    throw new Error(
+      `Invalid Realtime Database path: "${trimmed}". Path must not contain "..".`
+    );
+  }
+  const segments = trimmed.split('/').filter(Boolean);
+  for (const seg of segments) {
+    if (seg.includes('.')) {
+      throw new Error(
+        `Invalid segment "${seg}" in path. Segments must not contain ".".`
+      );
+    }
+    if (seg.includes('$')) {
+      throw new Error(
+        `Invalid segment "${seg}" in path. Segments must not contain "$".`
+      );
+    }
+    if (seg.includes('#')) {
+      throw new Error(
+        `Invalid segment "${seg}" in path. Segments must not contain "#".`
+      );
+    }
+    if (seg.includes('[') || seg.includes(']')) {
+      throw new Error(
+        `Invalid segment "${seg}" in path. Segments must not contain "[" or "]".`
+      );
+    }
+  }
+  return trimmed;
+}
+
+export const realtimeDbTools: ToolDefinition[] = [
+  // ── rtdb_get_data ─────────────────────────────────────
+  {
+    name: 'rtdb_get_data',
+    description:
+      'Read data from Firebase Realtime Database at a given path.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'Database path (e.g., "/users/uid123")' },
+      },
+      required: ['path'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const path = validateRtdbPath(args['path'] as string);
+        const db = getRealtimeDb();
+        const snapshot = await db.ref(path).once('value');
+
+        return formatSuccess({
+          path,
+          exists: snapshot.exists(),
+          data: snapshot.val(),
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'rtdb', 'get_data');
+      }
+    },
+  },
+
+  // ── rtdb_set_data ─────────────────────────────────────
+  {
+    name: 'rtdb_set_data',
+    description:
+      'Set data at a path in Realtime Database. Overwrites any existing data.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'Database path' },
+        data: { description: 'Data to set (any JSON-compatible value)' },
+      },
+      required: ['path', 'data'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const path = validateRtdbPath(args['path'] as string);
+        const data = args['data'];
+
+        const db = getRealtimeDb();
+        await db.ref(path).set(data);
+
+        return formatSuccess({
+          path,
+          message: `Data set successfully at "${path}".`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'rtdb', 'set_data');
+      }
+    },
+  },
+
+  // ── rtdb_push_data ────────────────────────────────────
+  {
+    name: 'rtdb_push_data',
+    description:
+      'Push new data to a list in Realtime Database. Auto-generates a unique key.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'Parent path for the new item' },
+        data: { description: 'Data to push' },
+      },
+      required: ['path', 'data'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const path = validateRtdbPath(args['path'] as string);
+        const data = args['data'];
+
+        const db = getRealtimeDb();
+        const newRef = db.ref(path).push();
+        await newRef.set(data);
+
+        // Get the path string from the reference
+        const newPath = newRef.toString().replace(newRef.root.toString(), '');
+
+        return formatSuccess({
+          path: newPath,
+          key: newRef.key,
+          message: `Data pushed successfully. New key: "${newRef.key}".`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'rtdb', 'push_data');
+      }
+    },
+  },
+
+  // ── rtdb_update_data ──────────────────────────────────
+  {
+    name: 'rtdb_update_data',
+    description:
+      'Update specific fields at a path without overwriting the entire location.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'Database path to update' },
+        data: { type: 'object', description: 'Fields to update' },
+      },
+      required: ['path', 'data'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const path = validateRtdbPath(args['path'] as string);
+        const data = args['data'] as Record<string, unknown>;
+
+        const db = getRealtimeDb();
+        await db.ref(path).update(data);
+
+        return formatSuccess({
+          path,
+          updatedFields: Object.keys(data),
+          message: `Data updated successfully at "${path}".`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'rtdb', 'update_data');
+      }
+    },
+  },
+
+  // ── rtdb_remove_data ──────────────────────────────────
+  {
+    name: 'rtdb_remove_data',
+    description: 'Remove data at a path in Realtime Database.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'Database path to remove' },
+      },
+      required: ['path'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const path = validateRtdbPath(args['path'] as string);
+
+        const db = getRealtimeDb();
+        await db.ref(path).remove();
+
+        return formatSuccess({
+          path,
+          message: `Data removed successfully at "${path}".`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'rtdb', 'remove_data');
+      }
+    },
+  },
+
+  // ── rtdb_query_data ───────────────────────────────────
+  {
+    name: 'rtdb_query_data',
+    description:
+      'Query data in Realtime Database with ordering and filtering.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'Database path to query' },
+        orderBy: {
+          type: 'object',
+          properties: {
+            child: { type: 'string', description: 'Order by child key' },
+            key: { type: 'boolean', description: 'Order by key' },
+            value: { type: 'boolean', description: 'Order by value' },
+          },
+          description: 'Order specification (provide one of child, key, or value)',
+        },
+        startAt: { description: 'Start at this value (inclusive)' },
+        endAt: { description: 'End at this value (inclusive)' },
+        equalTo: { description: 'Filter to exact value' },
+        limitToFirst: { type: 'number', description: 'Limit to first N results' },
+        limitToLast: { type: 'number', description: 'Limit to last N results' },
+      },
+      required: ['path'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const path = validateRtdbPath(args['path'] as string);
+        const orderBy = args['orderBy'] as { child?: string; key?: boolean; value?: boolean } | undefined;
+        const startAt = args['startAt'] as string | number | boolean | null;
+        const endAt = args['endAt'] as string | number | boolean | null;
+        const equalTo = args['equalTo'] as string | number | boolean | null;
+        const limitToFirst = args['limitToFirst'] as number | undefined;
+        const limitToLast = args['limitToLast'] as number | undefined;
+
+        const db = getRealtimeDb();
+        let query: Query = db.ref(path);
+
+        // Apply ordering
+        if (orderBy?.child) {
+          query = query.orderByChild(orderBy.child);
+        } else if (orderBy?.key) {
+          query = query.orderByKey();
+        } else if (orderBy?.value) {
+          query = query.orderByValue();
+        }
+
+        // Apply filters
+        if (equalTo !== undefined) {
+          query = query.equalTo(equalTo as string | number | boolean | null);
+        }
+        if (startAt !== undefined) {
+          query = query.startAt(startAt as string | number | boolean | null);
+        }
+        if (endAt !== undefined) {
+          query = query.endAt(endAt as string | number | boolean | null);
+        }
+
+        // Apply limits
+        if (limitToFirst !== undefined) {
+          if (limitToFirst < 1 || limitToFirst > 10000) {
+            throw new Error('limitToFirst must be between 1 and 10000.');
+          }
+          query = query.limitToFirst(limitToFirst);
+        }
+        if (limitToLast !== undefined) {
+          if (limitToLast < 1 || limitToLast > 10000) {
+            throw new Error('limitToLast must be between 1 and 10000.');
+          }
+          query = query.limitToLast(limitToLast);
+        }
+
+        const snapshot = await query.once('value');
+
+        const results: Array<{ key: string; value: unknown }> = [];
+        snapshot.forEach((child) => {
+          results.push({ key: child.key as string, value: child.val() });
+          return false;
+        });
+
+        return formatSuccess({
+          path,
+          count: results.length,
+          data: results,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'rtdb', 'query_data');
+      }
+    },
+  },
+];

package/src/tools/storage.ts

@@ -0,0 +1,314 @@
+import { getStorage } from '../services/firebase.js';
+import {
+  validateStoragePath,
+  handleFirebaseError,
+  formatSuccess,
+  formatListResult,
+} from '../utils/index.js';
+import type { ToolDefinition } from './types.js';
+
+// ============================================================
+// STORAGE TOOLS
+// ============================================================
+
+export const storageTools: ToolDefinition[] = [
+  // ── storage_upload_file ───────────────────────────────
+  {
+    name: 'storage_upload_file',
+    description:
+      'Upload a file to Firebase Cloud Storage. Provide base64-encoded file content.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'Destination path in Storage (e.g., "images/photo.jpg")' },
+        contentBase64: { type: 'string', description: 'Base64-encoded file content' },
+        contentType: { type: 'string', description: 'MIME type (e.g., "image/png"). Auto-detected if not provided.' },
+        metadata: { type: 'object', description: 'Additional metadata key-value pairs' },
+        public: { type: 'boolean', description: 'Make file publicly accessible (default: false)' },
+      },
+      required: ['path', 'contentBase64'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const destinationPath = validateStoragePath(args['path'] as string);
+        const contentBase64 = (args['contentBase64'] as string).trim();
+        const contentType = args['contentType'] as string | undefined;
+        const metadata = args['metadata'] as Record<string, string> | undefined;
+        const makePublic = (args['public'] as boolean) || false;
+
+        if (!contentBase64) {
+          throw new Error('contentBase64 cannot be empty.');
+        }
+
+        const buffer = Buffer.from(contentBase64, 'base64');
+
+        const storage = getStorage();
+        const bucket = storage.bucket();
+        const file = bucket.file(destinationPath);
+
+        const uploadMetadata: Record<string, unknown> = {};
+        if (contentType) {
+          uploadMetadata.contentType = contentType;
+        }
+        if (metadata) {
+          uploadMetadata.metadata = metadata;
+        }
+
+        await file.save(buffer, {
+          metadata: uploadMetadata,
+          resumable: false,
+          validation: 'crc32c',
+        });
+
+        if (makePublic) {
+          await file.makePublic();
+        }
+
+        const [url] = await file.getSignedUrl({
+          action: 'read',
+          expires: Date.now() + 60 * 60 * 1000,
+        });
+
+        return formatSuccess({
+          path: destinationPath,
+          size: buffer.length,
+          contentType: contentType || 'application/octet-stream',
+          public: makePublic,
+          signedUrl: url,
+          message: `File uploaded to "${destinationPath}" (${buffer.length} bytes).`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'storage', 'upload_file');
+      }
+    },
+  },
+
+  // ── storage_download_file ─────────────────────────────
+  {
+    name: 'storage_download_file',
+    description: 'Download a file from Firebase Cloud Storage. Returns base64-encoded content.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'File path in Storage' },
+      },
+      required: ['path'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const filePath = validateStoragePath(args['path'] as string);
+
+        const storage = getStorage();
+        const bucket = storage.bucket();
+        const file = bucket.file(filePath);
+
+        const [exists] = await file.exists();
+        if (!exists) {
+          return formatSuccess({
+            exists: false,
+            path: filePath,
+            message: `File "${filePath}" does not exist.`,
+          });
+        }
+
+        const [buffer] = await file.download();
+        const [metadata] = await file.getMetadata();
+
+        return formatSuccess({
+          exists: true,
+          path: filePath,
+          size: buffer.length,
+          contentType: (metadata.contentType as string) || 'application/octet-stream',
+          updated: metadata.updated as string,
+          contentBase64: buffer.toString('base64'),
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'storage', 'download_file');
+      }
+    },
+  },
+
+  // ── storage_list_files ────────────────────────────────
+  {
+    name: 'storage_list_files',
+    description:
+      'List files in a Firebase Cloud Storage bucket. Optionally filter by prefix.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        prefix: { type: 'string', description: 'Filter files by prefix (e.g., "images/")' },
+        pageSize: { type: 'number', description: 'Maximum results (1-1000, default 100)' },
+        pageToken: { type: 'string', description: 'Pagination token from previous result' },
+      },
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const prefix = (args['prefix'] as string) || '';
+        const pageSize = Math.min(Math.max((args['pageSize'] as number) || 100, 1), 1000);
+        const pageToken = args['pageToken'] as string | undefined;
+
+        const storage = getStorage();
+        const bucket = storage.bucket();
+
+        const options: { prefix: string; maxResults: number; pageToken?: string; autoPaginate: boolean } = {
+          prefix,
+          maxResults: pageSize,
+          autoPaginate: false,
+        };
+        if (pageToken) {
+          options.pageToken = pageToken;
+        }
+
+        const [files, nextQuery] = await bucket.getFiles(options);
+
+        const fileList = files.map((f) => ({
+          name: f.name,
+          size: f.metadata.size ? parseInt(f.metadata.size as string, 10) : 0,
+          contentType: f.metadata.contentType as string | undefined,
+          updated: f.metadata.updated as string | undefined,
+          timeCreated: f.metadata.timeCreated as string | undefined,
+        }));
+
+        return formatListResult(fileList, nextQuery?.pageToken as string | undefined);
+      } catch (err) {
+        handleFirebaseError(err, 'storage', 'list_files');
+      }
+    },
+  },
+
+  // ── storage_delete_file ───────────────────────────────
+  {
+    name: 'storage_delete_file',
+    description: 'Delete a file from Firebase Cloud Storage.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'File path to delete' },
+      },
+      required: ['path'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const filePath = validateStoragePath(args['path'] as string);
+
+        const storage = getStorage();
+        const bucket = storage.bucket();
+        const file = bucket.file(filePath);
+
+        const [exists] = await file.exists();
+        if (!exists) {
+          return formatSuccess({
+            success: false,
+            path: filePath,
+            message: `File "${filePath}" does not exist.`,
+          });
+        }
+
+        await file.delete();
+
+        return formatSuccess({
+          path: filePath,
+          message: `File "${filePath}" deleted successfully.`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'storage', 'delete_file');
+      }
+    },
+  },
+
+  // ── storage_get_signed_url ────────────────────────────
+  {
+    name: 'storage_get_signed_url',
+    description:
+      'Generate a signed URL for a file in Firebase Cloud Storage.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'File path' },
+        action: { type: 'string', enum: ['read', 'write', 'delete'], description: 'Action for the signed URL (default: read)' },
+        expiresInMs: { type: 'number', description: 'URL expiration in milliseconds (default: 3600000 = 1 hour)' },
+      },
+      required: ['path'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const filePath = validateStoragePath(args['path'] as string);
+        const action = (args['action'] as 'read' | 'write' | 'delete') || 'read';
+        const expiresInMs = (args['expiresInMs'] as number) || 3600000;
+
+        if (expiresInMs < 60000) {
+          throw new Error('Signed URL must be valid for at least 60 seconds.');
+        }
+        if (expiresInMs > 7 * 24 * 3600000) {
+          throw new Error('Signed URL cannot be valid for more than 7 days.');
+        }
+
+        const storage = getStorage();
+        const bucket = storage.bucket();
+        const file = bucket.file(filePath);
+
+        const [exists] = await file.exists();
+        if (!exists) {
+          return formatSuccess({
+            exists: false,
+            path: filePath,
+            message: `File "${filePath}" does not exist.`,
+          });
+        }
+
+        const [url] = await file.getSignedUrl({
+          action,
+          expires: Date.now() + expiresInMs,
+        });
+
+        return formatSuccess({
+          path: filePath,
+          action,
+          signedUrl: url,
+          expiresAt: new Date(Date.now() + expiresInMs).toISOString(),
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'storage', 'get_signed_url');
+      }
+    },
+  },
+
+  // ── storage_get_metadata ──────────────────────────────
+  {
+    name: 'storage_get_metadata',
+    description: 'Get metadata for a file in Firebase Cloud Storage.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        path: { type: 'string', description: 'File path' },
+      },
+      required: ['path'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const filePath = validateStoragePath(args['path'] as string);
+
+        const storage = getStorage();
+        const bucket = storage.bucket();
+        const file = bucket.file(filePath);
+
+        const [metadata] = await file.getMetadata();
+
+        return formatSuccess({
+          name: metadata.name,
+          bucket: metadata.bucket,
+          size: metadata.size ? parseInt(metadata.size as string, 10) : 0,
+          contentType: metadata.contentType as string | undefined,
+          timeCreated: metadata.timeCreated as string | undefined,
+          updated: metadata.updated as string | undefined,
+          storageClass: metadata.storageClass as string | undefined,
+          md5Hash: metadata.md5Hash as string | undefined,
+          crc32c: metadata.crc32c as string | undefined,
+          customMetadata: metadata.metadata || {},
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'storage', 'get_metadata');
+      }
+    },
+  },
+];

package/src/tools/types.ts

@@ -0,0 +1,10 @@
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+  handler: (args: Record<string, unknown>) => Promise<string>;
+}