@theihtisham/mcp-server-firebase 1.0.0

package/src/services/firebase.ts

@@ -0,0 +1,140 @@
+import * as admin from 'firebase-admin';
+import fs from 'fs';
+
+let app: admin.app.App | null = null;
+
+export interface FirebaseConfig {
+  projectId?: string;
+  storageBucket?: string;
+  databaseURL?: string;
+}
+
+function getServiceAccount(): admin.ServiceAccount | undefined {
+  // 1. Try FIREBASE_SERVICE_ACCOUNT_KEY (JSON string)
+  const keyEnv = process.env['FIREBASE_SERVICE_ACCOUNT_KEY'];
+  if (keyEnv) {
+    try {
+      return JSON.parse(keyEnv) as admin.ServiceAccount;
+    } catch {
+      throw new Error(
+        'FIREBASE_SERVICE_ACCOUNT_KEY is set but contains invalid JSON. ' +
+        'Provide the full service account JSON as a single-line string.'
+      );
+    }
+  }
+
+  // 2. Try FIREBASE_SERVICE_ACCOUNT_PATH (file path)
+  const pathEnv = process.env['FIREBASE_SERVICE_ACCOUNT_PATH'];
+  if (pathEnv) {
+    try {
+      const content = fs.readFileSync(pathEnv, 'utf-8');
+      return JSON.parse(content) as admin.ServiceAccount;
+    } catch (err) {
+      throw new Error(
+        `Failed to read service account file at "${pathEnv}": ${(err as Error).message}. ` +
+        'Ensure the path is correct and the file is valid JSON.'
+      );
+    }
+  }
+
+  // 3. Try individual env vars
+  const projectId = process.env['FIREBASE_PROJECT_ID'];
+  const clientEmail = process.env['FIREBASE_CLIENT_EMAIL'];
+  const privateKey = process.env['FIREBASE_PRIVATE_KEY']?.replace(/\\n/g, '\n');
+
+  if (projectId && clientEmail && privateKey) {
+    return { projectId, clientEmail, privateKey };
+  }
+
+  // 4. Return undefined — rely on Application Default Credentials (ADC)
+  return undefined;
+}
+
+export function initializeFirebase(config?: FirebaseConfig): admin.app.App {
+  if (app) {
+    return app;
+  }
+
+  const serviceAccount = getServiceAccount();
+
+  const initOptions: admin.AppOptions = {};
+
+  if (serviceAccount) {
+    initOptions.credential = admin.credential.cert(serviceAccount);
+  }
+  // If no service account, ADC will be used (works on GCP, with gcloud CLI, etc.)
+
+  if (config?.projectId) {
+    initOptions.projectId = config.projectId;
+  } else if (serviceAccount?.projectId) {
+    initOptions.projectId = serviceAccount.projectId;
+  } else {
+    const envProject = process.env['FIREBASE_PROJECT_ID'];
+    if (envProject) {
+      initOptions.projectId = envProject;
+    }
+  }
+
+  if (config?.storageBucket) {
+    initOptions.storageBucket = config.storageBucket;
+  } else {
+    const envBucket = process.env['FIREBASE_STORAGE_BUCKET'];
+    if (envBucket) {
+      initOptions.storageBucket = envBucket;
+    }
+  }
+
+  if (config?.databaseURL) {
+    initOptions.databaseURL = config.databaseURL;
+  } else {
+    const envDbUrl = process.env['FIREBASE_DATABASE_URL'];
+    if (envDbUrl) {
+      initOptions.databaseURL = envDbUrl;
+    }
+  }
+
+  try {
+    app = admin.initializeApp(initOptions, 'mcp-firebase-server');
+  } catch (err: unknown) {
+    // If app already exists, get it
+    if (err instanceof Error && err.message.includes('already exists')) {
+      app = admin.app('mcp-firebase-server');
+    } else {
+      throw err;
+    }
+  }
+
+  return app;
+}
+
+export function getFirestore(): admin.firestore.Firestore {
+  const firebaseApp = initializeFirebase();
+  return firebaseApp.firestore();
+}
+
+export function getAuth(): admin.auth.Auth {
+  const firebaseApp = initializeFirebase();
+  return firebaseApp.auth();
+}
+
+export function getStorage(): admin.storage.Storage {
+  const firebaseApp = initializeFirebase();
+  return firebaseApp.storage();
+}
+
+export function getRealtimeDb(): admin.database.Database {
+  const firebaseApp = initializeFirebase();
+  return firebaseApp.database();
+}
+
+export function getMessaging(): admin.messaging.Messaging {
+  const firebaseApp = initializeFirebase();
+  return firebaseApp.messaging();
+}
+
+export function getApp(): admin.app.App {
+  if (!app) {
+    return initializeFirebase();
+  }
+  return app;
+}

package/src/tools/auth.ts

@@ -0,0 +1,375 @@
+import { getAuth } from '../services/firebase.js';
+import {
+  validateEmail,
+  validateUid,
+  validatePageSize,
+  handleFirebaseError,
+  formatSuccess,
+  formatListResult,
+} from '../utils/index.js';
+import type { ToolDefinition } from './types.js';
+import * as admin from 'firebase-admin';
+
+// ============================================================
+// AUTH TOOLS
+// ============================================================
+
+export const authTools: ToolDefinition[] = [
+  // ── auth_create_user ──────────────────────────────────
+  {
+    name: 'auth_create_user',
+    description:
+      'Create a new Firebase Authentication user. At minimum provide email or phoneNumber.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        email: { type: 'string', description: 'User email address' },
+        emailVerified: { type: 'boolean', description: 'Whether email is verified (default: false)' },
+        phoneNumber: { type: 'string', description: 'Phone number in E.164 format (e.g., "+15555550100")' },
+        password: { type: 'string', description: 'Password (min 6 characters)' },
+        displayName: { type: 'string', description: 'Display name' },
+        photoURL: { type: 'string', description: 'Photo URL' },
+        disabled: { type: 'boolean', description: 'Whether account is disabled (default: false)' },
+        uid: { type: 'string', description: 'Custom UID (auto-generated if not provided)' },
+      },
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const auth = getAuth();
+        const createOptions: admin.auth.CreateRequest = {};
+
+        if (args['email']) {
+          createOptions.email = validateEmail(args['email'] as string);
+        }
+        if (args['emailVerified'] !== undefined) {
+          createOptions.emailVerified = args['emailVerified'] as boolean;
+        }
+        if (args['phoneNumber']) {
+          createOptions.phoneNumber = (args['phoneNumber'] as string).trim();
+        }
+        if (args['password']) {
+          const password = args['password'] as string;
+          if (password.length < 6) {
+            throw new Error('Password must be at least 6 characters long.');
+          }
+          createOptions.password = password;
+        }
+        if (args['displayName']) {
+          createOptions.displayName = (args['displayName'] as string).trim();
+        }
+        if (args['photoURL']) {
+          createOptions.photoURL = (args['photoURL'] as string).trim();
+        }
+        if (args['disabled'] !== undefined) {
+          createOptions.disabled = args['disabled'] as boolean;
+        }
+        if (args['uid']) {
+          createOptions.uid = validateUid(args['uid'] as string);
+        }
+
+        const userRecord = await auth.createUser(createOptions);
+
+        return formatSuccess({
+          uid: userRecord.uid,
+          email: userRecord.email,
+          phoneNumber: userRecord.phoneNumber,
+          displayName: userRecord.displayName,
+          photoURL: userRecord.photoURL,
+          disabled: userRecord.disabled,
+          emailVerified: userRecord.emailVerified,
+          metadata: {
+            creationTime: userRecord.metadata.creationTime,
+            lastSignInTime: userRecord.metadata.lastSignInTime,
+          },
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'auth', 'create_user');
+      }
+    },
+  },
+
+  // ── auth_get_user ─────────────────────────────────────
+  {
+    name: 'auth_get_user',
+    description: 'Get a Firebase user by UID, email, or phone number.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        uid: { type: 'string', description: 'User UID' },
+        email: { type: 'string', description: 'User email (alternative to uid)' },
+        phoneNumber: { type: 'string', description: 'User phone number (alternative to uid)' },
+      },
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const auth = getAuth();
+        let userRecord: admin.auth.UserRecord;
+
+        if (args['uid']) {
+          userRecord = await auth.getUser(validateUid(args['uid'] as string));
+        } else if (args['email']) {
+          userRecord = await auth.getUserByEmail(validateEmail(args['email'] as string));
+        } else if (args['phoneNumber']) {
+          userRecord = await auth.getUserByPhoneNumber((args['phoneNumber'] as string).trim());
+        } else {
+          throw new Error('Provide at least one of: uid, email, or phoneNumber.');
+        }
+
+        return formatSuccess({
+          uid: userRecord.uid,
+          email: userRecord.email,
+          phoneNumber: userRecord.phoneNumber,
+          displayName: userRecord.displayName,
+          photoURL: userRecord.photoURL,
+          disabled: userRecord.disabled,
+          emailVerified: userRecord.emailVerified,
+          customClaims: userRecord.customClaims,
+          tenantId: userRecord.tenantId,
+          providerData: userRecord.providerData.map((p) => ({
+            providerId: p.providerId,
+            uid: p.uid,
+            email: p.email,
+            displayName: p.displayName,
+            phoneNumber: p.phoneNumber,
+            photoURL: p.photoURL,
+          })),
+          metadata: {
+            creationTime: userRecord.metadata.creationTime,
+            lastSignInTime: userRecord.metadata.lastSignInTime,
+          },
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'auth', 'get_user');
+      }
+    },
+  },
+
+  // ── auth_list_users ───────────────────────────────────
+  {
+    name: 'auth_list_users',
+    description:
+      'List Firebase Auth users with pagination. Returns user summaries.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        pageSize: { type: 'number', description: 'Results per page (1-1000, default 100)' },
+        pageToken: { type: 'string', description: 'Next page token from previous result' },
+      },
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const auth = getAuth();
+        const pageSize = validatePageSize((args['pageSize'] as number) || 100);
+        const pageToken = args['pageToken'] as string | undefined;
+
+        const result = await auth.listUsers(pageSize, pageToken);
+
+        const users = result.users.map((u) => ({
+          uid: u.uid,
+          email: u.email,
+          displayName: u.displayName,
+          disabled: u.disabled,
+          emailVerified: u.emailVerified,
+          creationTime: u.metadata.creationTime,
+          lastSignInTime: u.metadata.lastSignInTime,
+        }));
+
+        return formatListResult(users, result.pageToken);
+      } catch (err) {
+        handleFirebaseError(err, 'auth', 'list_users');
+      }
+    },
+  },
+
+  // ── auth_update_user ──────────────────────────────────
+  {
+    name: 'auth_update_user',
+    description:
+      'Update an existing Firebase user. Only provided fields are updated.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        uid: { type: 'string', description: 'User UID to update' },
+        email: { type: 'string', description: 'New email address' },
+        emailVerified: { type: 'boolean', description: 'Email verification status' },
+        phoneNumber: { type: 'string', description: 'New phone number (null to remove)' },
+        password: { type: 'string', description: 'New password (min 6 characters)' },
+        displayName: { type: 'string', description: 'New display name' },
+        photoURL: { type: 'string', description: 'New photo URL' },
+        disabled: { type: 'boolean', description: 'Whether to disable the account' },
+      },
+      required: ['uid'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const auth = getAuth();
+        const uid = validateUid(args['uid'] as string);
+        const updateOptions: admin.auth.UpdateRequest = {};
+
+        if (args['email'] !== undefined) {
+          updateOptions.email = validateEmail(args['email'] as string);
+        }
+        if (args['emailVerified'] !== undefined) {
+          updateOptions.emailVerified = args['emailVerified'] as boolean;
+        }
+        if (args['phoneNumber'] !== undefined) {
+          updateOptions.phoneNumber = args['phoneNumber'] as string | null;
+        }
+        if (args['password'] !== undefined) {
+          const password = args['password'] as string;
+          if (password.length < 6) {
+            throw new Error('Password must be at least 6 characters long.');
+          }
+          updateOptions.password = password;
+        }
+        if (args['displayName'] !== undefined) {
+          updateOptions.displayName = args['displayName'] as string;
+        }
+        if (args['photoURL'] !== undefined) {
+          updateOptions.photoURL = args['photoURL'] as string;
+        }
+        if (args['disabled'] !== undefined) {
+          updateOptions.disabled = args['disabled'] as boolean;
+        }
+
+        const userRecord = await auth.updateUser(uid, updateOptions);
+
+        return formatSuccess({
+          uid: userRecord.uid,
+          email: userRecord.email,
+          displayName: userRecord.displayName,
+          photoURL: userRecord.photoURL,
+          disabled: userRecord.disabled,
+          emailVerified: userRecord.emailVerified,
+          message: `User "${uid}" updated successfully.`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'auth', 'update_user');
+      }
+    },
+  },
+
+  // ── auth_delete_user ──────────────────────────────────
+  {
+    name: 'auth_delete_user',
+    description: 'Delete a Firebase user by UID.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        uid: { type: 'string', description: 'User UID to delete' },
+      },
+      required: ['uid'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const auth = getAuth();
+        const uid = validateUid(args['uid'] as string);
+        await auth.deleteUser(uid);
+
+        return formatSuccess({
+          uid,
+          message: `User "${uid}" deleted successfully.`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'auth', 'delete_user');
+      }
+    },
+  },
+
+  // ── auth_verify_token ─────────────────────────────────
+  {
+    name: 'auth_verify_token',
+    description:
+      'Verify a Firebase ID token and return the decoded token with user info.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        idToken: { type: 'string', description: 'Firebase ID token to verify' },
+        checkRevoked: { type: 'boolean', description: 'Check if token was revoked (default: true)' },
+      },
+      required: ['idToken'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const auth = getAuth();
+        const idToken = (args['idToken'] as string).trim();
+        const checkRevoked = (args['checkRevoked'] as boolean) ?? true;
+
+        if (idToken.length === 0) {
+          throw new Error('ID token cannot be empty.');
+        }
+
+        const decodedToken = await auth.verifyIdToken(idToken, checkRevoked);
+
+        return formatSuccess({
+          uid: decodedToken.uid,
+          email: decodedToken.email,
+          emailVerified: decodedToken.email_verified,
+          name: decodedToken.name,
+          picture: decodedToken.picture,
+          iss: decodedToken.iss,
+          aud: decodedToken.aud,
+          authTime: new Date(decodedToken.auth_time * 1000).toISOString(),
+          issuedAt: new Date(decodedToken.iat * 1000).toISOString(),
+          expiresAt: new Date(decodedToken.exp * 1000).toISOString(),
+          signInProvider: decodedToken.firebase?.sign_in_provider,
+          valid: true,
+        });
+      } catch (err) {
+        const error = err as Error;
+        return formatSuccess({
+          valid: false,
+          error: error.message,
+          suggestion: 'Ensure the token is a valid, non-expired Firebase ID token.',
+        });
+      }
+    },
+  },
+
+  // ── auth_set_custom_claims ────────────────────────────
+  {
+    name: 'auth_set_custom_claims',
+    description:
+      'Set custom claims on a user for role-based access control.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        uid: { type: 'string', description: 'User UID' },
+        customClaims: { type: 'object', description: 'Custom claims object (max 1000 bytes serialized)' },
+      },
+      required: ['uid', 'customClaims'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const auth = getAuth();
+        const uid = validateUid(args['uid'] as string);
+        const customClaims = args['customClaims'] as Record<string, unknown>;
+
+        const claimsSize = Buffer.byteLength(JSON.stringify(customClaims));
+        if (claimsSize > 1000) {
+          throw new Error(
+            `Custom claims exceed 1000 bytes (got ${claimsSize}). ` +
+            'Reduce the number or size of claims.'
+          );
+        }
+
+        const reservedKeys = ['iss', 'aud', 'auth_time', 'sub', 'iat', 'exp', 'email', 'email_verified', 'firebase'];
+        for (const key of Object.keys(customClaims)) {
+          if (reservedKeys.includes(key)) {
+            throw new Error(`Cannot set reserved claim key: "${key}".`);
+          }
+        }
+
+        await auth.setCustomUserClaims(uid, customClaims);
+
+        return formatSuccess({
+          uid,
+          customClaims,
+          message: `Custom claims set for user "${uid}". Claims take effect on next token refresh.`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'auth', 'set_custom_claims');
+      }
+    },
+  },
+];