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',
      };
    }
  }