@theihtisham/mcp-server-firebase 1.0.0

package/dist/tools/realtime-db.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.realtimeDbTools = void 0;
+exports.validateRtdbPath = validateRtdbPath;
+const firebase_js_1 = require("../services/firebase.js");
+const index_js_1 = require("../utils/index.js");
+// ============================================================
+// REALTIME DATABASE TOOLS
+// ============================================================
+function validateRtdbPath(path) {
+    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;
+}
+exports.realtimeDbTools = [
+    // ── rtdb_get_data ─────────────────────────────────────
+    {
+        name: 'rtdb_get_data',
+        description: 'Read data from Firebase Realtime Database at a given path.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Database path (e.g., "/users/uid123")' },
+            },
+            required: ['path'],
+        },
+        handler: async (args) => {
+            try {
+                const path = validateRtdbPath(args['path']);
+                const db = (0, firebase_js_1.getRealtimeDb)();
+                const snapshot = await db.ref(path).once('value');
+                return (0, index_js_1.formatSuccess)({
+                    path,
+                    exists: snapshot.exists(),
+                    data: snapshot.val(),
+                });
+            }
+            catch (err) {
+                (0, index_js_1.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',
+            properties: {
+                path: { type: 'string', description: 'Database path' },
+                data: { description: 'Data to set (any JSON-compatible value)' },
+            },
+            required: ['path', 'data'],
+        },
+        handler: async (args) => {
+            try {
+                const path = validateRtdbPath(args['path']);
+                const data = args['data'];
+                const db = (0, firebase_js_1.getRealtimeDb)();
+                await db.ref(path).set(data);
+                return (0, index_js_1.formatSuccess)({
+                    path,
+                    message: `Data set successfully at "${path}".`,
+                });
+            }
+            catch (err) {
+                (0, index_js_1.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',
+            properties: {
+                path: { type: 'string', description: 'Parent path for the new item' },
+                data: { description: 'Data to push' },
+            },
+            required: ['path', 'data'],
+        },
+        handler: async (args) => {
+            try {
+                const path = validateRtdbPath(args['path']);
+                const data = args['data'];
+                const db = (0, firebase_js_1.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 (0, index_js_1.formatSuccess)({
+                    path: newPath,
+                    key: newRef.key,
+                    message: `Data pushed successfully. New key: "${newRef.key}".`,
+                });
+            }
+            catch (err) {
+                (0, index_js_1.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',
+            properties: {
+                path: { type: 'string', description: 'Database path to update' },
+                data: { type: 'object', description: 'Fields to update' },
+            },
+            required: ['path', 'data'],
+        },
+        handler: async (args) => {
+            try {
+                const path = validateRtdbPath(args['path']);
+                const data = args['data'];
+                const db = (0, firebase_js_1.getRealtimeDb)();
+                await db.ref(path).update(data);
+                return (0, index_js_1.formatSuccess)({
+                    path,
+                    updatedFields: Object.keys(data),
+                    message: `Data updated successfully at "${path}".`,
+                });
+            }
+            catch (err) {
+                (0, index_js_1.handleFirebaseError)(err, 'rtdb', 'update_data');
+            }
+        },
+    },
+    // ── rtdb_remove_data ──────────────────────────────────
+    {
+        name: 'rtdb_remove_data',
+        description: 'Remove data at a path in Realtime Database.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Database path to remove' },
+            },
+            required: ['path'],
+        },
+        handler: async (args) => {
+            try {
+                const path = validateRtdbPath(args['path']);
+                const db = (0, firebase_js_1.getRealtimeDb)();
+                await db.ref(path).remove();
+                return (0, index_js_1.formatSuccess)({
+                    path,
+                    message: `Data removed successfully at "${path}".`,
+                });
+            }
+            catch (err) {
+                (0, index_js_1.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',
+            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) => {
+            try {
+                const path = validateRtdbPath(args['path']);
+                const orderBy = args['orderBy'];
+                const startAt = args['startAt'];
+                const endAt = args['endAt'];
+                const equalTo = args['equalTo'];
+                const limitToFirst = args['limitToFirst'];
+                const limitToLast = args['limitToLast'];
+                const db = (0, firebase_js_1.getRealtimeDb)();
+                let 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);
+                }
+                if (startAt !== undefined) {
+                    query = query.startAt(startAt);
+                }
+                if (endAt !== undefined) {
+                    query = query.endAt(endAt);
+                }
+                // 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 = [];
+                snapshot.forEach((child) => {
+                    results.push({ key: child.key, value: child.val() });
+                    return false;
+                });
+                return (0, index_js_1.formatSuccess)({
+                    path,
+                    count: results.length,
+                    data: results,
+                });
+            }
+            catch (err) {
+                (0, index_js_1.handleFirebaseError)(err, 'rtdb', 'query_data');
+            }
+        },
+    },
+];
+//# sourceMappingURL=realtime-db.js.map

package/dist/tools/storage.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from './types.js';
+export declare const storageTools: ToolDefinition[];
+//# sourceMappingURL=storage.d.ts.map

package/dist/tools/storage.js

@@ -0,0 +1,279 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storageTools = void 0;
+const firebase_js_1 = require("../services/firebase.js");
+const index_js_1 = require("../utils/index.js");
+// ============================================================
+// STORAGE TOOLS
+// ============================================================
+exports.storageTools = [
+    // ── storage_upload_file ───────────────────────────────
+    {
+        name: 'storage_upload_file',
+        description: 'Upload a file to Firebase Cloud Storage. Provide base64-encoded file content.',
+        inputSchema: {
+            type: 'object',
+            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) => {
+            try {
+                const destinationPath = (0, index_js_1.validateStoragePath)(args['path']);
+                const contentBase64 = args['contentBase64'].trim();
+                const contentType = args['contentType'];
+                const metadata = args['metadata'];
+                const makePublic = args['public'] || false;
+                if (!contentBase64) {
+                    throw new Error('contentBase64 cannot be empty.');
+                }
+                const buffer = Buffer.from(contentBase64, 'base64');
+                const storage = (0, firebase_js_1.getStorage)();
+                const bucket = storage.bucket();
+                const file = bucket.file(destinationPath);
+                const uploadMetadata = {};
+                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 (0, index_js_1.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) {
+                (0, index_js_1.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',
+            properties: {
+                path: { type: 'string', description: 'File path in Storage' },
+            },
+            required: ['path'],
+        },
+        handler: async (args) => {
+            try {
+                const filePath = (0, index_js_1.validateStoragePath)(args['path']);
+                const storage = (0, firebase_js_1.getStorage)();
+                const bucket = storage.bucket();
+                const file = bucket.file(filePath);
+                const [exists] = await file.exists();
+                if (!exists) {
+                    return (0, index_js_1.formatSuccess)({
+                        exists: false,
+                        path: filePath,
+                        message: `File "${filePath}" does not exist.`,
+                    });
+                }
+                const [buffer] = await file.download();
+                const [metadata] = await file.getMetadata();
+                return (0, index_js_1.formatSuccess)({
+                    exists: true,
+                    path: filePath,
+                    size: buffer.length,
+                    contentType: metadata.contentType || 'application/octet-stream',
+                    updated: metadata.updated,
+                    contentBase64: buffer.toString('base64'),
+                });
+            }
+            catch (err) {
+                (0, index_js_1.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',
+            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) => {
+            try {
+                const prefix = args['prefix'] || '';
+                const pageSize = Math.min(Math.max(args['pageSize'] || 100, 1), 1000);
+                const pageToken = args['pageToken'];
+                const storage = (0, firebase_js_1.getStorage)();
+                const bucket = storage.bucket();
+                const options = {
+                    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, 10) : 0,
+                    contentType: f.metadata.contentType,
+                    updated: f.metadata.updated,
+                    timeCreated: f.metadata.timeCreated,
+                }));
+                return (0, index_js_1.formatListResult)(fileList, nextQuery?.pageToken);
+            }
+            catch (err) {
+                (0, index_js_1.handleFirebaseError)(err, 'storage', 'list_files');
+            }
+        },
+    },
+    // ── storage_delete_file ───────────────────────────────
+    {
+        name: 'storage_delete_file',
+        description: 'Delete a file from Firebase Cloud Storage.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path to delete' },
+            },
+            required: ['path'],
+        },
+        handler: async (args) => {
+            try {
+                const filePath = (0, index_js_1.validateStoragePath)(args['path']);
+                const storage = (0, firebase_js_1.getStorage)();
+                const bucket = storage.bucket();
+                const file = bucket.file(filePath);
+                const [exists] = await file.exists();
+                if (!exists) {
+                    return (0, index_js_1.formatSuccess)({
+                        success: false,
+                        path: filePath,
+                        message: `File "${filePath}" does not exist.`,
+                    });
+                }
+                await file.delete();
+                return (0, index_js_1.formatSuccess)({
+                    path: filePath,
+                    message: `File "${filePath}" deleted successfully.`,
+                });
+            }
+            catch (err) {
+                (0, index_js_1.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',
+            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) => {
+            try {
+                const filePath = (0, index_js_1.validateStoragePath)(args['path']);
+                const action = args['action'] || 'read';
+                const expiresInMs = args['expiresInMs'] || 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 = (0, firebase_js_1.getStorage)();
+                const bucket = storage.bucket();
+                const file = bucket.file(filePath);
+                const [exists] = await file.exists();
+                if (!exists) {
+                    return (0, index_js_1.formatSuccess)({
+                        exists: false,
+                        path: filePath,
+                        message: `File "${filePath}" does not exist.`,
+                    });
+                }
+                const [url] = await file.getSignedUrl({
+                    action,
+                    expires: Date.now() + expiresInMs,
+                });
+                return (0, index_js_1.formatSuccess)({
+                    path: filePath,
+                    action,
+                    signedUrl: url,
+                    expiresAt: new Date(Date.now() + expiresInMs).toISOString(),
+                });
+            }
+            catch (err) {
+                (0, index_js_1.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',
+            properties: {
+                path: { type: 'string', description: 'File path' },
+            },
+            required: ['path'],
+        },
+        handler: async (args) => {
+            try {
+                const filePath = (0, index_js_1.validateStoragePath)(args['path']);
+                const storage = (0, firebase_js_1.getStorage)();
+                const bucket = storage.bucket();
+                const file = bucket.file(filePath);
+                const [metadata] = await file.getMetadata();
+                return (0, index_js_1.formatSuccess)({
+                    name: metadata.name,
+                    bucket: metadata.bucket,
+                    size: metadata.size ? parseInt(metadata.size, 10) : 0,
+                    contentType: metadata.contentType,
+                    timeCreated: metadata.timeCreated,
+                    updated: metadata.updated,
+                    storageClass: metadata.storageClass,
+                    md5Hash: metadata.md5Hash,
+                    crc32c: metadata.crc32c,
+                    customMetadata: metadata.metadata || {},
+                });
+            }
+            catch (err) {
+                (0, index_js_1.handleFirebaseError)(err, 'storage', 'get_metadata');
+            }
+        },
+    },
+];
+//# sourceMappingURL=storage.js.map

package/dist/tools/types.d.ts

@@ -0,0 +1,11 @@
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    handler: (args: Record<string, unknown>) => Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/utils/cache.d.ts

@@ -0,0 +1,16 @@
+export declare class LRUCache<T> {
+    private cache;
+    private readonly maxSize;
+    private readonly defaultTtlMs;
+    constructor(maxSize?: number, defaultTtlMs?: number);
+    get(key: string): T | undefined;
+    set(key: string, value: T, ttlMs?: number): void;
+    delete(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    has(key: string): boolean;
+    invalidatePrefix(prefix: string): number;
+}
+export declare const firestoreCache: LRUCache<unknown>;
+export declare const schemaCache: LRUCache<unknown>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/utils/cache.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schemaCache = exports.firestoreCache = exports.LRUCache = void 0;
+class LRUCache {
+    cache = new Map();
+    maxSize;
+    defaultTtlMs;
+    constructor(maxSize = 200, defaultTtlMs = 5 * 60 * 1000) {
+        this.maxSize = maxSize;
+        this.defaultTtlMs = defaultTtlMs;
+    }
+    get(key) {
+        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, value, ttlMs) {
+        // 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) {
+        return this.cache.delete(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+    has(key) {
+        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) {
+        let count = 0;
+        for (const key of this.cache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.cache.delete(key);
+                count++;
+            }
+        }
+        return count;
+    }
+}
+exports.LRUCache = LRUCache;
+// Singleton caches for the server
+exports.firestoreCache = new LRUCache(500, 30_000); // 30s TTL for Firestore reads
+exports.schemaCache = new LRUCache(50, 10 * 60 * 1000); // 10min TTL for schema inference
+//# sourceMappingURL=cache.js.map

package/dist/utils/errors.d.ts

@@ -0,0 +1,15 @@
+export interface FirebaseErrorContext {
+    service: string;
+    operation: string;
+    suggestion?: string;
+    details?: string;
+}
+export declare class FirebaseToolError extends Error {
+    readonly context: FirebaseErrorContext;
+    constructor(message: string, context: FirebaseErrorContext);
+    toStructuredMessage(): string;
+}
+export declare function handleFirebaseError(error: unknown, service: string, operation: string): never;
+export declare function formatSuccess(data: unknown, operation?: string): string;
+export declare function formatListResult(items: unknown[], pageToken?: string, totalCount?: number): string;
+//# sourceMappingURL=errors.d.ts.map