@theihtisham/mcp-server-firebase 1.0.0

package/dist/utils/errors.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirebaseToolError = void 0;
+exports.handleFirebaseError = handleFirebaseError;
+exports.formatSuccess = formatSuccess;
+exports.formatListResult = formatListResult;
+class FirebaseToolError extends Error {
+    context;
+    constructor(message, context) {
+        super(message);
+        this.name = 'FirebaseToolError';
+        this.context = context;
+    }
+    toStructuredMessage() {
+        const lines = [
+            `[${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');
+    }
+}
+exports.FirebaseToolError = FirebaseToolError;
+function handleFirebaseError(error, service, operation) {
+    if (error instanceof FirebaseToolError) {
+        throw error;
+    }
+    const err = error;
+    let suggestion;
+    let details;
+    // 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 });
+}
+function formatSuccess(data, operation) {
+    return JSON.stringify({
+        success: true,
+        ...(operation && { operation }),
+        data,
+        timestamp: new Date().toISOString(),
+    }, null, 2);
+}
+function formatListResult(items, pageToken, totalCount) {
+    return JSON.stringify({
+        success: true,
+        count: items.length,
+        ...(totalCount !== undefined && { totalCount }),
+        ...(pageToken && { nextPageToken: pageToken }),
+        items,
+    }, null, 2);
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodePageToken = exports.encodePageToken = exports.fetchAllDocuments = exports.paginatedQuery = exports.schemaCache = exports.firestoreCache = exports.LRUCache = exports.formatListResult = exports.formatSuccess = exports.handleFirebaseError = exports.FirebaseToolError = exports.PageSizeSchema = exports.LimitSchema = exports.DataSchema = exports.EmailSchema = exports.UidSchema = exports.StoragePathSchema = exports.DocumentPathSchema = exports.CollectionPathSchema = exports.sanitizeData = exports.validateOperator = exports.validateWhereField = exports.validatePageSize = exports.validateLimit = exports.validateUid = exports.validateEmail = exports.validateStoragePath = exports.validateDocumentPath = exports.validateCollectionPath = void 0;
+var validation_js_1 = require("./validation.js");
+Object.defineProperty(exports, "validateCollectionPath", { enumerable: true, get: function () { return validation_js_1.validateCollectionPath; } });
+Object.defineProperty(exports, "validateDocumentPath", { enumerable: true, get: function () { return validation_js_1.validateDocumentPath; } });
+Object.defineProperty(exports, "validateStoragePath", { enumerable: true, get: function () { return validation_js_1.validateStoragePath; } });
+Object.defineProperty(exports, "validateEmail", { enumerable: true, get: function () { return validation_js_1.validateEmail; } });
+Object.defineProperty(exports, "validateUid", { enumerable: true, get: function () { return validation_js_1.validateUid; } });
+Object.defineProperty(exports, "validateLimit", { enumerable: true, get: function () { return validation_js_1.validateLimit; } });
+Object.defineProperty(exports, "validatePageSize", { enumerable: true, get: function () { return validation_js_1.validatePageSize; } });
+Object.defineProperty(exports, "validateWhereField", { enumerable: true, get: function () { return validation_js_1.validateWhereField; } });
+Object.defineProperty(exports, "validateOperator", { enumerable: true, get: function () { return validation_js_1.validateOperator; } });
+Object.defineProperty(exports, "sanitizeData", { enumerable: true, get: function () { return validation_js_1.sanitizeData; } });
+Object.defineProperty(exports, "CollectionPathSchema", { enumerable: true, get: function () { return validation_js_1.CollectionPathSchema; } });
+Object.defineProperty(exports, "DocumentPathSchema", { enumerable: true, get: function () { return validation_js_1.DocumentPathSchema; } });
+Object.defineProperty(exports, "StoragePathSchema", { enumerable: true, get: function () { return validation_js_1.StoragePathSchema; } });
+Object.defineProperty(exports, "UidSchema", { enumerable: true, get: function () { return validation_js_1.UidSchema; } });
+Object.defineProperty(exports, "EmailSchema", { enumerable: true, get: function () { return validation_js_1.EmailSchema; } });
+Object.defineProperty(exports, "DataSchema", { enumerable: true, get: function () { return validation_js_1.DataSchema; } });
+Object.defineProperty(exports, "LimitSchema", { enumerable: true, get: function () { return validation_js_1.LimitSchema; } });
+Object.defineProperty(exports, "PageSizeSchema", { enumerable: true, get: function () { return validation_js_1.PageSizeSchema; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "FirebaseToolError", { enumerable: true, get: function () { return errors_js_1.FirebaseToolError; } });
+Object.defineProperty(exports, "handleFirebaseError", { enumerable: true, get: function () { return errors_js_1.handleFirebaseError; } });
+Object.defineProperty(exports, "formatSuccess", { enumerable: true, get: function () { return errors_js_1.formatSuccess; } });
+Object.defineProperty(exports, "formatListResult", { enumerable: true, get: function () { return errors_js_1.formatListResult; } });
+var cache_js_1 = require("./cache.js");
+Object.defineProperty(exports, "LRUCache", { enumerable: true, get: function () { return cache_js_1.LRUCache; } });
+Object.defineProperty(exports, "firestoreCache", { enumerable: true, get: function () { return cache_js_1.firestoreCache; } });
+Object.defineProperty(exports, "schemaCache", { enumerable: true, get: function () { return cache_js_1.schemaCache; } });
+var pagination_js_1 = require("./pagination.js");
+Object.defineProperty(exports, "paginatedQuery", { enumerable: true, get: function () { return pagination_js_1.paginatedQuery; } });
+Object.defineProperty(exports, "fetchAllDocuments", { enumerable: true, get: function () { return pagination_js_1.fetchAllDocuments; } });
+Object.defineProperty(exports, "encodePageToken", { enumerable: true, get: function () { return pagination_js_1.encodePageToken; } });
+Object.defineProperty(exports, "decodePageToken", { enumerable: true, get: function () { return pagination_js_1.decodePageToken; } });
+//# sourceMappingURL=index.js.map

package/dist/utils/pagination.d.ts

@@ -0,0 +1,28 @@
+import { Query, DocumentSnapshot } from 'firebase-admin/firestore';
+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 declare function paginatedQuery<T>(baseQuery: Query, options: PaginationOptions, transform: (snap: DocumentSnapshot) => T): Promise<PaginatedResult<T>>;
+/**
+ * Fetch all documents from a collection with automatic pagination.
+ */
+export declare function fetchAllDocuments<T>(baseQuery: Query, transform: (snap: DocumentSnapshot) => T, pageSize?: number, maxTotal?: number): Promise<T[]>;
+/**
+ * Encode a document snapshot as a page token.
+ */
+export declare function encodePageToken(docPath: string): string;
+/**
+ * Decode a page token back to a document path.
+ */
+export declare function decodePageToken(token: string): string;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/utils/pagination.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paginatedQuery = paginatedQuery;
+exports.fetchAllDocuments = fetchAllDocuments;
+exports.encodePageToken = encodePageToken;
+exports.decodePageToken = decodePageToken;
+const validation_js_1 = require("./validation.js");
+/**
+ * Execute a paginated Firestore query.
+ */
+async function paginatedQuery(baseQuery, options, transform) {
+    const pageSize = (0, validation_js_1.validatePageSize)(options.pageSize);
+    let query = baseQuery.limit(pageSize);
+    const allItems = [];
+    let lastDoc;
+    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;
+    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.
+ */
+async function fetchAllDocuments(baseQuery, transform, pageSize = 500, maxTotal = 10000) {
+    let query = baseQuery.limit(pageSize);
+    const allItems = [];
+    let lastDoc;
+    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.
+ */
+function encodePageToken(docPath) {
+    return Buffer.from(docPath).toString('base64');
+}
+/**
+ * Decode a page token back to a document path.
+ */
+function decodePageToken(token) {
+    return Buffer.from(token, 'base64').toString('utf-8');
+}
+//# sourceMappingURL=pagination.js.map

package/dist/utils/validation.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export declare const pathSegmentRegex: RegExp;
+export declare const collectionPathRegex: RegExp;
+export declare function validateCollectionPath(path: string): string;
+export declare function validateDocumentPath(path: string): string;
+export declare function validateStoragePath(path: string): string;
+export declare function validateEmail(email: string): string;
+export declare function validateUid(uid: string): string;
+export declare function validateLimit(limit: number, max?: number): number;
+export declare function validatePageSize(size: number, max?: number): number;
+export declare function validateWhereField(field: string): string;
+export declare function validateOperator(op: string): string;
+export declare function sanitizeData(data: unknown): unknown;
+export declare const CollectionPathSchema: z.ZodString;
+export declare const DocumentPathSchema: z.ZodString;
+export declare const StoragePathSchema: z.ZodString;
+export declare const UidSchema: z.ZodString;
+export declare const EmailSchema: z.ZodString;
+export declare const DataSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const LimitSchema: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+export declare const PageSizeSchema: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageSizeSchema = exports.LimitSchema = exports.DataSchema = exports.EmailSchema = exports.UidSchema = exports.StoragePathSchema = exports.DocumentPathSchema = exports.CollectionPathSchema = exports.collectionPathRegex = exports.pathSegmentRegex = void 0;
+exports.validateCollectionPath = validateCollectionPath;
+exports.validateDocumentPath = validateDocumentPath;
+exports.validateStoragePath = validateStoragePath;
+exports.validateEmail = validateEmail;
+exports.validateUid = validateUid;
+exports.validateLimit = validateLimit;
+exports.validatePageSize = validatePageSize;
+exports.validateWhereField = validateWhereField;
+exports.validateOperator = validateOperator;
+exports.sanitizeData = sanitizeData;
+const zod_1 = require("zod");
+// Shared validation schemas and input sanitization utilities
+exports.pathSegmentRegex = /^[a-zA-Z0-9_-]+$/;
+exports.collectionPathRegex = /^(?:[a-zA-Z0-9_-]+\/(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9_-]+|[a-zA-Z0-9_-]+)$/;
+function validateCollectionPath(path) {
+    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 (!exports.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;
+}
+function validateDocumentPath(path) {
+    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 (!exports.pathSegmentRegex.test(seg)) {
+            throw new Error(`Invalid segment "${seg}" in document path. ` +
+                'Segments must contain only letters, numbers, hyphens, and underscores.');
+        }
+    }
+    return trimmed;
+}
+function validateStoragePath(path) {
+    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;
+}
+function validateEmail(email) {
+    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;
+}
+function validateUid(uid) {
+    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;
+}
+function validateLimit(limit, max = 10000) {
+    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;
+}
+function validatePageSize(size, max = 1000) {
+    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;
+}
+function validateWhereField(field) {
+    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;
+}
+function validateOperator(op) {
+    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;
+}
+function sanitizeData(data) {
+    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 = {};
+        for (const [key, value] of Object.entries(data)) {
+            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
+exports.CollectionPathSchema = zod_1.z.string().min(1).describe('Firestore collection path (e.g., "users" or "users/uid123/orders")');
+exports.DocumentPathSchema = zod_1.z.string().min(1).describe('Firestore document path (e.g., "users/uid123" or "users/uid123/orders/order1")');
+exports.StoragePathSchema = zod_1.z.string().min(1).describe('Cloud Storage path (e.g., "images/photo.jpg")');
+exports.UidSchema = zod_1.z.string().min(1).describe('Firebase Auth UID');
+exports.EmailSchema = zod_1.z.string().email().describe('User email address');
+exports.DataSchema = zod_1.z.record(zod_1.z.unknown()).describe('Document data as a JSON object');
+exports.LimitSchema = zod_1.z.number().int().min(1).max(10000).optional().default(100).describe('Maximum number of results to return (1-10000, default: 100)');
+exports.PageSizeSchema = zod_1.z.number().int().min(1).max(1000).optional().default(100).describe('Number of results per page (1-1000, default: 100)');
+//# sourceMappingURL=validation.js.map

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@theihtisham/mcp-server-firebase",
+  "version": "1.0.0",
+  "description": "MCP server giving AI assistants full Firebase/Firestore access",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mcp-server-firebase": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "firebase",
+    "firestore",
+    "ai",
+    "claude",
+    "model-context-protocol"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "firebase-admin": "^12.7.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/theihtisham/mcp-server-firebase"
+  }
+}

package/src/index.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { initializeFirebase } from './services/firebase.js';
+import { allTools } from './tools/index.js';
+
+const SERVER_NAME = 'mcp-server-firebase';
+const SERVER_VERSION = '1.0.0';
+
+async function main(): Promise<void> {
+  // Validate Firebase configuration on startup
+  try {
+    initializeFirebase();
+  } catch (err) {
+    console.error(
+      `Failed to initialize Firebase: ${(err as Error).message}\n` +
+      'Ensure one of the following is set:\n' +
+      '  - FIREBASE_SERVICE_ACCOUNT_KEY (JSON string)\n' +
+      '  - FIREBASE_SERVICE_ACCOUNT_PATH (file path)\n' +
+      '  - FIREBASE_PROJECT_ID + FIREBASE_CLIENT_EMAIL + FIREBASE_PRIVATE_KEY\n' +
+      '  - Application Default Credentials (gcloud auth application-default login)'
+    );
+    process.exit(1);
+  }
+
+  // Create MCP server using the low-level Server class
+  // This allows us to register tools with raw JSON Schema input schemas
+  const server = new Server(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // Build a map for quick tool lookup
+  const toolMap = new Map(allTools.map((t) => [t.name, t]));
+
+  // Handle tools/list requests
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: allTools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      })),
+    };
+  });
+
+  // Handle tools/call requests
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const toolName = request.params.name;
+    const tool = toolMap.get(toolName);
+
+    if (!tool) {
+      return {
+        content: [{ type: 'text' as const, text: `Error: Unknown tool "${toolName}".` }],
+        isError: true,
+      };
+    }
+
+    try {
+      const args = (request.params.arguments as Record<string, unknown>) ?? {};
+      const result = await tool.handler(args);
+      return {
+        content: [{ type: 'text' as const, text: result }],
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        content: [{ type: 'text' as const, text: `Error: ${message}` }],
+        isError: true,
+      };
+    }
+  });
+
+  // Connect using stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error(`${SERVER_NAME} v${SERVER_VERSION} running on stdio`);
+  console.error(`Registered ${allTools.length} tools`);
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});