@theihtisham/mcp-server-firebase 1.0.0

package/src/tools/functions.ts

@@ -0,0 +1,189 @@
+import { handleFirebaseError, formatSuccess } from '../utils/index.js';
+import type { ToolDefinition } from './types.js';
+
+// ============================================================
+// CLOUD FUNCTIONS TOOLS
+// ============================================================
+
+export const functionsTools: ToolDefinition[] = [
+  // ── functions_list ────────────────────────────────────
+  {
+    name: 'functions_list',
+    description:
+      'List deployed Firebase Cloud Functions with their trigger types and status.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        region: { type: 'string', description: 'Region filter (default: us-central1)' },
+        pageSize: { type: 'number', description: 'Maximum results (default: 100)' },
+      },
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const projectId = process.env['FIREBASE_PROJECT_ID'];
+        if (!projectId) {
+          throw new Error(
+            'FIREBASE_PROJECT_ID is required to list functions. ' +
+            'Set it as an environment variable.'
+          );
+        }
+
+        const region = (args['region'] as string) || 'us-central1';
+        const pageSize = Math.min((args['pageSize'] as number) || 100, 1000);
+
+        const { GoogleAuth } = await import('google-auth-library');
+        const auth = new GoogleAuth({
+          scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+        });
+
+        const client = await auth.getClient();
+        const url = `https://cloudfunctions.googleapis.com/v2/projects/${projectId}/locations/${region}/functions?pageSize=${pageSize}`;
+
+        const response = await client.request({ url });
+        const data = response.data as { functions?: Array<Record<string, unknown>>; nextPageToken?: string };
+
+        const functions = (data.functions || []).map((fn) => ({
+          name: (fn.name as string)?.split('/').pop(),
+          fullName: fn.name,
+          state: fn.state,
+          updateTime: fn.updateTime,
+          buildId: fn.buildId,
+          eventTrigger: fn.eventTrigger ? {
+            eventType: (fn.eventTrigger as Record<string, unknown>).eventType,
+            resource: (fn.eventTrigger as Record<string, unknown>).resource,
+          } : undefined,
+          httpsTrigger: fn.httpsTrigger ? {
+            uri: (fn.httpsTrigger as Record<string, unknown>).uri,
+          } : undefined,
+          entryPoint: fn.entryPoint,
+          runtime: fn.runtime,
+        }));
+
+        return formatSuccess({
+          projectId,
+          region,
+          count: functions.length,
+          functions,
+          nextPageToken: data.nextPageToken,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'functions', 'list');
+      }
+    },
+  },
+
+  // ── functions_trigger ─────────────────────────────────
+  {
+    name: 'functions_trigger',
+    description:
+      'Trigger an HTTP Cloud Function by URL. Sends a POST request with optional data payload.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        url: { type: 'string', description: 'HTTPS trigger URL of the Cloud Function' },
+        data: { description: 'JSON payload to send with the request' },
+        method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'DELETE'], description: 'HTTP method (default: POST)' },
+      },
+      required: ['url'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const url = (args['url'] as string).trim();
+        const data = args['data'];
+        const method = (args['method'] as 'GET' | 'POST' | 'PUT' | 'DELETE') || 'POST';
+
+        if (!url.startsWith('https://')) {
+          throw new Error('URL must start with "https://".');
+        }
+
+        const { GoogleAuth } = await import('google-auth-library');
+        const auth = new GoogleAuth();
+        const client = await auth.getIdTokenClient(url);
+
+        const response = await client.request({
+          url,
+          method,
+          data,
+          responseType: 'json',
+        });
+
+        return formatSuccess({
+          status: response.status,
+          statusText: response.statusText,
+          data: response.data,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'functions', 'trigger');
+      }
+    },
+  },
+
+  // ── functions_get_logs ────────────────────────────────
+  {
+    name: 'functions_get_logs',
+    description:
+      'Get recent logs for a Firebase Cloud Function. Requires FIREBASE_PROJECT_ID.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        functionName: { type: 'string', description: 'Name of the Cloud Function' },
+        region: { type: 'string', description: 'Region (default: us-central1)' },
+        pageSize: { type: 'number', description: 'Maximum log entries (default: 50, max 100)' },
+        filter: { type: 'string', description: 'Additional log filter expression' },
+      },
+      required: ['functionName'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const projectId = process.env['FIREBASE_PROJECT_ID'];
+        if (!projectId) {
+          throw new Error(
+            'FIREBASE_PROJECT_ID is required to get function logs.'
+          );
+        }
+
+        const functionName = (args['functionName'] as string).trim();
+        const region = (args['region'] as string) || 'us-central1';
+        const pageSize = Math.min((args['pageSize'] as number) || 50, 100);
+        const additionalFilter = (args['filter'] as string) || '';
+
+        const { GoogleAuth } = await import('google-auth-library');
+        const auth = new GoogleAuth({
+          scopes: ['https://www.googleapis.com/auth/logging.read'],
+        });
+
+        const client = await auth.getClient();
+        const filter = `resource.type="cloud_function" resource.labels.function_name="${functionName}" resource.labels.region="${region}"${additionalFilter ? ` ${additionalFilter}` : ''}`;
+
+        const url = 'https://logging.googleapis.com/v2/entries:list';
+        const response = await client.request({
+          url,
+          method: 'POST',
+          data: {
+            resourceNames: [`projects/${projectId}`],
+            filter,
+            orderBy: 'timestamp desc',
+            pageSize,
+          },
+        });
+
+        const data = response.data as { entries?: Array<Record<string, unknown>> };
+        const logs = (data.entries || []).map((entry) => ({
+          timestamp: entry.timestamp,
+          severity: entry.severity,
+          textPayload: entry.textPayload,
+          jsonPayload: entry.jsonPayload,
+        }));
+
+        return formatSuccess({
+          functionName,
+          region,
+          count: logs.length,
+          logs,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'functions', 'get_logs');
+      }
+    },
+  },
+];

package/src/tools/index.ts

@@ -0,0 +1,24 @@
+export type { ToolDefinition } from './types.js';
+export { firestoreTools } from './firestore.js';
+export { authTools } from './auth.js';
+export { storageTools } from './storage.js';
+export { realtimeDbTools } from './realtime-db.js';
+export { functionsTools } from './functions.js';
+export { messagingTools } from './messaging.js';
+
+import { firestoreTools } from './firestore.js';
+import { authTools } from './auth.js';
+import { storageTools } from './storage.js';
+import { realtimeDbTools } from './realtime-db.js';
+import { functionsTools } from './functions.js';
+import { messagingTools } from './messaging.js';
+import type { ToolDefinition } from './types.js';
+
+export const allTools: ToolDefinition[] = [
+  ...firestoreTools,
+  ...authTools,
+  ...storageTools,
+  ...realtimeDbTools,
+  ...functionsTools,
+  ...messagingTools,
+];

package/src/tools/messaging.ts

@@ -0,0 +1,324 @@
+import { getMessaging } from '../services/firebase.js';
+import {
+  handleFirebaseError,
+  formatSuccess,
+} from '../utils/index.js';
+import type { ToolDefinition } from './types.js';
+import * as admin from 'firebase-admin';
+
+// ============================================================
+// MESSAGING (FCM) TOOLS
+// ============================================================
+
+export const messagingTools: ToolDefinition[] = [
+  // ── messaging_send ────────────────────────────────────
+  {
+    name: 'messaging_send',
+    description:
+      'Send a push notification to a specific device via FCM token or to a topic.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        token: { type: 'string', description: 'FCM device registration token' },
+        topic: { type: 'string', description: 'Topic name (alternative to token)' },
+        condition: { type: 'string', description: 'Condition expression (alternative to token/topic)' },
+        notification: {
+          type: 'object',
+          properties: {
+            title: { type: 'string', description: 'Notification title' },
+            body: { type: 'string', description: 'Notification body text' },
+            imageUrl: { type: 'string', description: 'Notification image URL' },
+          },
+          description: 'Notification payload',
+        },
+        data: {
+          type: 'object',
+          description: 'Custom data payload (key-value pairs)',
+        },
+        android: {
+          type: 'object',
+          properties: {
+            priority: { type: 'string', enum: ['high', 'normal'], description: 'Message priority' },
+            ttl: { type: 'number', description: 'Time to live in seconds' },
+          },
+          description: 'Android-specific options',
+        },
+        apns: {
+          type: 'object',
+          properties: {
+            badge: { type: 'number', description: 'Badge count' },
+            sound: { type: 'string', description: 'Sound file name' },
+          },
+          description: 'APNs-specific options',
+        },
+      },
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const messaging = getMessaging();
+
+        const hasToken = !!args['token'];
+        const hasTopic = !!args['topic'];
+        const hasCondition = !!args['condition'];
+
+        if ([hasToken, hasTopic, hasCondition].filter(Boolean).length > 1) {
+          throw new Error('Provide exactly one of: token, topic, or condition.');
+        }
+        if (!hasToken && !hasTopic && !hasCondition) {
+          throw new Error('Must provide one of: token, topic, or condition.');
+        }
+
+        // Build message using the appropriate type
+        // We need to construct the message based on the target type
+        let message: admin.messaging.Message;
+
+        if (hasToken) {
+          message = { token: (args['token'] as string).trim() };
+        } else if (hasTopic) {
+          message = { topic: (args['topic'] as string).trim() };
+        } else {
+          message = { condition: (args['condition'] as string).trim() };
+        }
+
+        // Notification
+        if (args['notification']) {
+          const notif = args['notification'] as { title?: string; body?: string; imageUrl?: string };
+          message.notification = {
+            title: notif.title || '',
+            body: notif.body || '',
+            ...(notif.imageUrl && { imageUrl: notif.imageUrl }),
+          };
+        }
+
+        // Data payload (values must be strings for FCM)
+        if (args['data']) {
+          const rawData = args['data'] as Record<string, unknown>;
+          const stringData: Record<string, string> = {};
+          for (const [key, value] of Object.entries(rawData)) {
+            stringData[key] = String(value);
+          }
+          message.data = stringData;
+        }
+
+        // Android config
+        if (args['android']) {
+          const android = args['android'] as { priority?: string; ttl?: number };
+          message.android = {
+            priority: (android.priority as 'high' | 'normal') || 'high',
+            ...(android.ttl !== undefined && { ttl: android.ttl * 1000 }),
+          };
+        }
+
+        // APNs config
+        if (args['apns']) {
+          const apns = args['apns'] as { badge?: number; sound?: string };
+          message.apns = {
+            payload: {
+              aps: {
+                ...(apns.badge !== undefined && { badge: apns.badge }),
+                ...(apns.sound && { sound: apns.sound }),
+              },
+            },
+          };
+        }
+
+        const messageId = await messaging.send(message);
+
+        return formatSuccess({
+          messageId,
+          target: hasToken ? `token:${(args['token'] as string).substring(0, 10)}...` :
+                   hasTopic ? `topic:${args['topic']}` :
+                   `condition:${args['condition']}`,
+          message: 'Notification sent successfully.',
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'messaging', 'send');
+      }
+    },
+  },
+
+  // ── messaging_send_multicast ──────────────────────────
+  {
+    name: 'messaging_send_multicast',
+    description:
+      'Send a push notification to multiple devices (up to 500 tokens) in a single request.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        tokens: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Array of FCM device tokens (max 500)',
+        },
+        notification: {
+          type: 'object',
+          properties: {
+            title: { type: 'string' },
+            body: { type: 'string' },
+            imageUrl: { type: 'string' },
+          },
+          description: 'Notification payload',
+        },
+        data: { type: 'object', description: 'Custom data payload' },
+      },
+      required: ['tokens'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const tokens = args['tokens'] as string[];
+        if (!tokens || tokens.length === 0) {
+          throw new Error('Tokens array cannot be empty.');
+        }
+        if (tokens.length > 500) {
+          throw new Error(
+            `Too many tokens: ${tokens.length}. Maximum is 500 per multicast. ` +
+            'Split into multiple batches.'
+          );
+        }
+
+        const messaging = getMessaging();
+        const message: admin.messaging.MulticastMessage = {
+          tokens: tokens.map((t) => t.trim()),
+        };
+
+        if (args['notification']) {
+          const notif = args['notification'] as { title?: string; body?: string; imageUrl?: string };
+          message.notification = {
+            title: notif.title || '',
+            body: notif.body || '',
+            ...(notif.imageUrl && { imageUrl: notif.imageUrl }),
+          };
+        }
+
+        if (args['data']) {
+          const rawData = args['data'] as Record<string, unknown>;
+          const stringData: Record<string, string> = {};
+          for (const [key, value] of Object.entries(rawData)) {
+            stringData[key] = String(value);
+          }
+          message.data = stringData;
+        }
+
+        const batchResponse = await messaging.sendEachForMulticast(message);
+
+        const failedTokens: string[] = [];
+        if (batchResponse.failureCount > 0) {
+          batchResponse.responses.forEach((resp, idx) => {
+            if (!resp.success) {
+              failedTokens.push(tokens[idx]!);
+            }
+          });
+        }
+
+        return formatSuccess({
+          successCount: batchResponse.successCount,
+          failureCount: batchResponse.failureCount,
+          totalSent: tokens.length,
+          ...(failedTokens.length > 0 && {
+            failedTokens: failedTokens.slice(0, 50),
+            message: `${batchResponse.successCount} succeeded, ${batchResponse.failureCount} failed.`,
+          }),
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'messaging', 'send_multicast');
+      }
+    },
+  },
+
+  // ── messaging_subscribe_topic ─────────────────────────
+  {
+    name: 'messaging_subscribe_topic',
+    description: 'Subscribe device tokens to an FCM topic for topic-based messaging.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        tokens: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Array of FCM tokens to subscribe (max 1000)',
+        },
+        topic: { type: 'string', description: 'Topic name to subscribe to' },
+      },
+      required: ['tokens', 'topic'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const tokens = args['tokens'] as string[];
+        const topic = (args['topic'] as string).trim();
+
+        if (!tokens || tokens.length === 0) {
+          throw new Error('Tokens array cannot be empty.');
+        }
+        if (tokens.length > 1000) {
+          throw new Error('Maximum 1000 tokens per subscribe request.');
+        }
+        if (!topic) {
+          throw new Error('Topic name cannot be empty.');
+        }
+        if (!/^[a-zA-Z0-9-_.~%]+$/.test(topic)) {
+          throw new Error(
+            `Invalid topic name: "${topic}". ` +
+            'Topic names must match: [a-zA-Z0-9-_.~%]+'
+          );
+        }
+
+        const messaging = getMessaging();
+        const response = await messaging.subscribeToTopic(tokens, topic);
+
+        return formatSuccess({
+          successCount: response.successCount,
+          failureCount: response.failureCount,
+          topic,
+          tokensRequested: tokens.length,
+          message: `${response.successCount} tokens subscribed to "${topic}".`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'messaging', 'subscribe_topic');
+      }
+    },
+  },
+
+  // ── messaging_unsubscribe_topic ───────────────────────
+  {
+    name: 'messaging_unsubscribe_topic',
+    description: 'Unsubscribe device tokens from an FCM topic.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        tokens: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Array of FCM tokens to unsubscribe (max 1000)',
+        },
+        topic: { type: 'string', description: 'Topic name to unsubscribe from' },
+      },
+      required: ['tokens', 'topic'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      try {
+        const tokens = args['tokens'] as string[];
+        const topic = (args['topic'] as string).trim();
+
+        if (!tokens || tokens.length === 0) {
+          throw new Error('Tokens array cannot be empty.');
+        }
+        if (!topic) {
+          throw new Error('Topic name cannot be empty.');
+        }
+
+        const messaging = getMessaging();
+        const response = await messaging.unsubscribeFromTopic(tokens, topic);
+
+        return formatSuccess({
+          successCount: response.successCount,
+          failureCount: response.failureCount,
+          topic,
+          tokensRequested: tokens.length,
+          message: `${response.successCount} tokens unsubscribed from "${topic}".`,
+        });
+      } catch (err) {
+        handleFirebaseError(err, 'messaging', 'unsubscribe_topic');
+      }
+    },
+  },
+];