Heptabase MCP

Implementation Reference

• src/server.ts:222-270 (handler)

  The main handler function for the 'loadBackup' tool, which resolves the backup path (by ID if provided), calls BackupManager.loadBackup, initializes/updates the data service with the backup data, and returns a success message.
  handler: async (params) => { if (!this.backupManager) { this.backupManager = new BackupManager({ backupPath: this.config.backupPath, extractionPath: this.config.extractionPath, autoExtract: params.extract ?? this.config.autoExtract, watchDirectory: false, keepExtracted: this.config.keepExtracted }); } let backupPath = params.backupPath; // If backupId is provided, find the backup path if (params.backupId) { const backups = await this.backupManager.listBackups(); const backup = backups.find(b => b.backupId === params.backupId); if (!backup) { throw new Error('Backup not found'); } backupPath = backup.backupPath; } const metadata = await this.backupManager.loadBackup(backupPath!); // Initialize data service with the extracted path const dataPath = metadata.extractedPath || path.dirname(metadata.backupPath); // Update existing data service if it exists, otherwise create new one if (this.dataService) { // Update the data path and reload (this.dataService as any).config.dataPath = dataPath; await this.dataService.loadData(); } else { this.dataService = new HeptabaseDataService({ dataPath, cacheEnabled: this.config.cacheEnabled, cacheTTL: this.config.cacheTTL }); await this.dataService.loadData(); } return { content: [{ type: 'text', text: `Backup loaded successfully: ${metadata.backupId}` }] }; }
• src/server.ts:212-218 (schema)

  Zod input schema for the loadBackup tool, validating backupPath or backupId (required at least one), and optional extract flag.
  const loadBackupSchema = z.object({ backupPath: z.string().optional(), backupId: z.string().optional(), extract: z.boolean().optional() }).refine(data => data.backupPath || data.backupId, { message: 'Either backupPath or backupId must be provided' });
• src/server.ts:273-280 (registration)

  Registration of the 'loadBackup' tool with the MCP server, providing inline schema (mirroring loadBackupSchema) and handler that validates params and delegates to this.tools.loadBackup.handler.
  this.server.tool('loadBackup', { backupPath: z.string().optional(), backupId: z.string().optional(), extract: z.boolean().optional() }, async (params) => { const validated = loadBackupSchema.parse(params); return this.tools.loadBackup.handler(validated); });
• src/services/BackupManager.ts:58-97 (helper)

  Core helper method in BackupManager class that performs the actual backup loading: stats file, extracts ZIP if configured and needed, builds and caches BackupMetadata, emits events.
  async loadBackup(backupPath: string): Promise<BackupMetadata> { this.emit('backup:load:start', backupPath); try { const stats = await fs.stat(backupPath); const fileName = path.basename(backupPath); const backupInfo = this.getBackupInfo(fileName); const isCompressed = fileName.endsWith('.zip'); let extractedPath: string | undefined; if (isCompressed && this.config.autoExtract) { const backupName = path.basename(backupPath, '.zip'); extractedPath = path.join(this.config.extractionPath, backupName); // Check if already extracted if (!(await fs.pathExists(extractedPath))) { await this.extractBackup(backupPath, extractedPath); } } const metadata: BackupMetadata = { backupId: path.basename(backupPath, path.extname(backupPath)), backupPath, createdDate: backupInfo.date, fileSize: stats.size, isCompressed, extractedPath, version: backupInfo.version }; this.loadedBackups.set(metadata.backupId, metadata); this.emit('backup:load:complete', metadata); return metadata; } catch (error) { this.emit('backup:load:error', error); throw error; } }