MCP Firebird

Instructions

Implementation Reference

• src/db/management.ts:86-195 (handler)

  Core handler function that executes the Firebird database backup using gbak or nbackup CLI tools. Handles options like format, compression, metadata-only, executes the command via spawn, measures size/duration, and returns structured result or error.
  export const backupDatabase = async ( backupPath: string, options: BackupOptions = {}, config = DEFAULT_CONFIG ): Promise<BackupResult> => { const startTime = Date.now(); try { // Check if Firebird tools are installed const toolsCheck = await checkFirebirdTools(); if (!toolsCheck.installed) { throw new FirebirdError( `Firebird client tools are not installed. ${toolsCheck.installInstructions}`, 'MISSING_FIREBIRD_TOOLS' ); } // Ensure the backup directory exists const backupDir = path.dirname(backupPath); if (!fs.existsSync(backupDir)) { fs.mkdirSync(backupDir, { recursive: true }); } // Determine which backup tool to use const format = options.format || 'gbak'; let command: string; let args: string[] = []; // Try to find Firebird bin directory const firebirdBinPath = await findFirebirdBinPath(); if (firebirdBinPath) { logger.info(`Found Firebird bin directory: ${firebirdBinPath}`); // Use full path to command if bin directory was found command = path.join(firebirdBinPath, format); } else { // Use command name only, relying on system PATH command = format; } if (format === 'gbak') { args = [ '-b', // Backup '-v', // Verbose output '-user', config.user || 'SYSDBA', '-password', config.password || 'masterkey' ]; if (options.metadata_only) { args.push('-m'); // Metadata only } if (options.compress) { args.push('-z'); // Compress } // Add connection string and backup path const connectionString = `${config.host}/${config.port}:${config.database}`; args.push(connectionString, backupPath); } else if (format === 'nbackup') { args = [ '-B', '0', // Level 0 backup (full) '-user', config.user || 'SYSDBA', '-password', config.password || 'masterkey' ]; // Add database path and backup path args.push(config.database, backupPath); } else { throw new FirebirdError( `Invalid backup format: ${format}`, 'CONFIGURATION_ERROR' ); } logger.info(`Starting database backup to ${backupPath} using ${format}`); if (options.verbose) { logger.debug(`Backup command: ${command} ${args.join(' ')}`); } // Execute the backup command const result = await executeCommand(command, args, options.verbose); // Get the size of the backup file const stats = fs.statSync(backupPath); const duration = Date.now() - startTime; logger.info(`Backup completed successfully in ${duration}ms, size: ${stats.size} bytes`); return { success: true, backupPath, size: stats.size, duration, details: result }; } catch (error: any) { const duration = Date.now() - startTime; const errorMessage = `Error creating database backup: ${error.message || error}`; logger.error(errorMessage); return { success: false, backupPath, size: 0, duration, error: errorMessage, details: error.details || '' }; } };
• src/tools/database.ts:51-59 (schema)

  Zod schema defining input arguments for the backup-database tool: required backupPath and optional options (format, compress, metadata_only, verbose).
  export const BackupDatabaseArgsSchema = z.object({ backupPath: z.string().min(1).describe("Path where the backup file will be saved"), options: z.object({ format: z.enum(['gbak', 'nbackup']).default('gbak').describe("Backup format: gbak (full backup) or nbackup (incremental)"), compress: z.boolean().default(false).describe("Whether to compress the backup"), metadata_only: z.boolean().default(false).describe("Whether to backup only metadata (no data)"), verbose: z.boolean().default(false).describe("Whether to show detailed progress") }).optional() });
• src/tools/database.ts:373-402 (registration)

  Registers the 'backup-database' tool in the MCP tools Map within setupDatabaseTools function. Includes thin wrapper handler that extracts args, calls core backupDatabase helper, formats result with formatForClaude, and handles errors.
  tools.set("backup-database", { name: "backup-database", description: "Creates a backup of the Firebird database", inputSchema: BackupDatabaseArgsSchema, handler: async (request) => { const { backupPath, options } = request; logger.info(`Executing backup-database tool to: ${backupPath}`); try { const result = await backupDatabase(backupPath, options); return { content: [{ type: "text", text: formatForClaude(result) }] }; } catch (error) { const errorResponse = wrapError(error); logger.error(`Error backing up database: ${errorResponse.error} [${errorResponse.errorType || 'UNKNOWN'}]`); return { content: [{ type: "text", text: formatForClaude(errorResponse) }] }; } } });