HashPilot

Instructions

Implementation Reference

• src/tools/composite.ts:153-208 (handler)

  Main handler function for the 'addressbook_manage' tool. Dispatches to specific accountTools based on the 'operation' parameter (add, list, remove, update, import).

  export async function addressBookManage(args: {
    operation: 'add' | 'list' | 'remove' | 'update' | 'import';
    // Common
    alias?: string;
    nickname?: string;
    // Add/Import specific
    accountId?: string;
    privateKey?: string;
  }): Promise<ToolResult> {
    try {
      logger.info('Address book operation', { operation: args.operation });
  
      switch (args.operation) {
        case 'add':
          return await accountTools.addToAddressBook({
            accountId: args.accountId!,
            alias: args.alias!,
            nickname: args.nickname,
          });
  
        case 'list':
          return await accountTools.listAddressBook();
  
        case 'remove':
          return await accountTools.removeFromAddressBook({
            alias: args.alias!,
          });
  
        case 'update':
          return await accountTools.updateAddressBook({
            alias: args.alias!,
            nickname: args.nickname!,
          });
  
        case 'import':
          return await accountTools.importAccount({
            accountId: args.accountId!,
            privateKey: args.privateKey!,
            alias: args.alias!,
            nickname: args.nickname,
          });
  
        default:
          return {
            success: false,
            error: `Unknown address book operation: ${args.operation}`,
          };
      }
    } catch (error) {
      logger.error('Address book operation failed', { operation: args.operation, error });
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  }

• src/tools/composite.ts:466-505 (schema)

  Tool schema definition for 'addressbook_manage' including name, description, and inputSchema with operation enum and parameters.

    {
      name: 'addressbook_manage',
      description: `Manage Hedera account address book for multi-account workflows.
  
  OPERATIONS:
  - add: Add account to address book (reference only, no private key)
  - import: Import account WITH private key for transaction signing
  - list: Show all saved accounts with aliases and metadata
  - update: Update account nickname
  - remove: Remove account from address book
  
  USE THIS FOR: Managing multiple accounts, organizing workflows, quick account reference.`,
      inputSchema: {
        type: 'object' as const,
        properties: {
          operation: {
            type: 'string',
            enum: ['add', 'import', 'list', 'remove', 'update'],
            description: 'Address book operation',
          },
          accountId: {
            type: 'string',
            description: 'Hedera account ID (for add/import)',
          },
          alias: {
            type: 'string',
            description: 'Unique alias for quick reference',
          },
          nickname: {
            type: 'string',
            description: 'Human-readable name',
          },
          privateKey: {
            type: 'string',
            description: 'Private key in DER format (for import only)',
          },
        },
        required: ['operation'],
      },
    },

• src/index.ts:591-592 (registration)

  Registration and dispatch of 'addressbook_manage' tool call in the main MCP server request handler switch statement.

  case 'addressbook_manage':
    result = await addressBookManage(args as any);

• src/tools/account.ts:184-222 (helper)

  Helper function 'addToAddressBook' called by addressbook_manage for 'add' operation. Adds account reference to address book service.

  export async function addToAddressBook(args: {
    accountId: string;
    alias: string;
    nickname?: string;
  }): Promise<ToolResult> {
    try {
      logger.info('Adding to address book', { accountId: args.accountId, alias: args.alias });
  
      if (addressBook.count() === 0) {
        await addressBook.initialize();
      }
  
      // Verify the account exists
      const accountInfo = await hederaClient.getAccountInfo(args.accountId);
  
      await addressBook.add({
        accountId: args.accountId,
        alias: args.alias,
        nickname: args.nickname,
        publicKey: accountInfo.key,
        memo: accountInfo.memo,
      });
  
      return {
        success: true,
        data: {
          accountId: args.accountId,
          alias: args.alias,
          addedToAddressBook: true,
        },
      };
    } catch (error) {
      logger.error('Failed to add to address book', { error });
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  }

• src/tools/account.ts:227-261 (helper)

  Helper function 'listAddressBook' called by addressbook_manage for 'list' operation. Lists all address book entries without exposing private keys.

  export async function listAddressBook(): Promise<ToolResult> {
    try {
      if (addressBook.count() === 0) {
        await addressBook.initialize();
      }
  
      const entries = addressBook.list();
  
      // Remove private keys from the response
      const safeEntries = entries.map((entry) => ({
        accountId: entry.accountId,
        alias: entry.alias,
        nickname: entry.nickname,
        publicKey: entry.publicKey,
        memo: entry.memo,
        createdAt: entry.createdAt,
        updatedAt: entry.updatedAt,
        hasPrivateKey: !!entry.privateKey,
      }));
  
      return {
        success: true,
        data: {
          count: entries.length,
          accounts: safeEntries,
        },
      };
    } catch (error) {
      logger.error('Failed to list address book', { error });
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  }