HashPilot

Instructions

Implementation Reference

• src/tools/composite.ts:214-262 (handler)

  Primary handler for 'state_manage' tool. Routes 'backup', 'restore', 'export' operations to stateTools helpers with unified error handling and logging.
  export async function stateManage(args: { operation: 'backup' | 'restore' | 'export'; // Backup/Export specific includePrivateKeys?: boolean; outputPath?: string; filename?: string; format?: 'json' | 'compact' | 'pretty'; // Restore specific backupPath?: string; merge?: boolean; }): Promise<ToolResult> { try { logger.info('State management operation', { operation: args.operation }); switch (args.operation) { case 'backup': return await stateTools.backupState({ includePrivateKeys: args.includePrivateKeys, outputPath: args.outputPath, filename: args.filename, }); case 'restore': return await stateTools.restoreState({ backupPath: args.backupPath!, merge: args.merge, }); case 'export': return await stateTools.exportState({ outputPath: args.outputPath!, format: args.format, includePrivateKeys: args.includePrivateKeys, }); default: return { success: false, error: `Unknown state operation: ${args.operation}`, }; } } catch (error) { logger.error('State management failed', { operation: args.operation, error }); return { success: false, error: error instanceof Error ? error.message : 'Unknown error', }; } }
• src/tools/composite.ts:506-548 (schema)

  Tool schema definition including name, description, and inputSchema validation for the 'state_manage' tool.
  { name: 'state_manage', description: `Manage HashPilot MCP server state through backup/restore/export operations. OPERATIONS: - backup: Create timestamped backup (excludes private keys by default for security) - restore: Restore state from backup file (can merge or replace) - export: Export state to JSON for inspection or sharing USE THIS FOR: State persistence, migration, disaster recovery, debugging.`, inputSchema: { type: 'object' as const, properties: { operation: { type: 'string', enum: ['backup', 'restore', 'export'], description: 'State management operation', }, includePrivateKeys: { type: 'boolean', description: 'Include private keys (INSECURE - use with caution)', }, outputPath: { type: 'string', description: 'Output file path (for backup/export)', }, backupPath: { type: 'string', description: 'Backup file to restore from', }, merge: { type: 'boolean', description: 'Merge with existing state instead of replacing', }, format: { type: 'string', enum: ['json', 'compact', 'pretty'], description: 'Export format (default: pretty)', }, }, required: ['operation'], }, },
• src/index.ts:594-596 (registration)

  Registration in the main tool dispatch switch statement in index.ts, which calls the stateManage handler.
  case 'state_manage': result = await stateManage(args as any); break;
• src/tools/state.ts:13-46 (helper)

  Helper function backupState called by state_manage for backup operations, interacts with stateService.
  export async function backupState(args: { outputPath?: string; includePrivateKeys?: boolean; filename?: string; }): Promise<ToolResult> { try { logger.info('Creating state backup', { includePrivateKeys: args.includePrivateKeys, }); // Warning for including private keys if (args.includePrivateKeys) { logger.warn('⚠️ WARNING: Backup includes UNENCRYPTED private keys!'); logger.warn('⚠️ Store this backup securely and never share it.'); } const result = await stateService.backup(args.includePrivateKeys || false, args.outputPath); return { success: true, data: result, metadata: { executedVia: 'state_service', command: 'state backup', }, }; } catch (error) { logger.error('Failed to backup state', { error }); return { success: false, error: error instanceof Error ? error.message : 'Unknown error', }; } }
• src/tools/state.ts:51-78 (helper)

  Helper function restoreState called by state_manage for restore operations.
  export async function restoreState(args: { backupPath: string; merge?: boolean; }): Promise<ToolResult> { try { logger.info('Restoring state from backup', { backupPath: args.backupPath, merge: args.merge, }); const result = await stateService.restore(args.backupPath, args.merge || false); return { success: true, data: result, metadata: { executedVia: 'state_service', command: 'state restore', }, }; } catch (error) { logger.error('Failed to restore state', { error }); return { success: false, error: error instanceof Error ? error.message : 'Unknown error', }; } }
• src/tools/state.ts:83-121 (helper)

  Helper function exportState called by state_manage for export operations.
  export async function exportState(args: { outputPath: string; format?: 'json' | 'compact' | 'pretty'; includePrivateKeys?: boolean; }): Promise<ToolResult> { try { logger.info('Exporting state', { outputPath: args.outputPath, format: args.format, }); // Warning for including private keys if (args.includePrivateKeys) { logger.warn('⚠️ WARNING: Export includes UNENCRYPTED private keys!'); logger.warn('⚠️ Store this export securely and never share it.'); } const result = await stateService.export( args.outputPath, args.format || 'pretty', args.includePrivateKeys || false ); return { success: true, data: result, metadata: { executedVia: 'state_service', command: 'state export', }, }; } catch (error) { logger.error('Failed to export state', { error }); return { success: false, error: error instanceof Error ? error.message : 'Unknown error', }; } }