HashPilot

Instructions

Implementation Reference

• src/tools/composite.ts:325-368 (handler)

  Primary handler function that executes the 'hcs_message' tool logic. It handles 'submit' and 'query' operations by delegating to consensusTools helpers.

  export async function hcsMessageManage(args: {
    operation: 'submit' | 'query';
    topicId: string;
    // Submit specific
    message?: string;
    submitKey?: string;
    // Query specific
    limit?: number;
    order?: 'asc' | 'desc';
    sequenceNumber?: number;
  }): Promise<ToolResult> {
    try {
      logger.info('HCS message operation', { operation: args.operation });
  
      switch (args.operation) {
        case 'submit':
          return await consensusTools.submitMessage({
            topicId: args.topicId,
            message: args.message!,
            submitKey: args.submitKey,
          });
  
        case 'query':
          return await consensusTools.queryMessages({
            topicId: args.topicId,
            limit: args.limit,
            order: args.order,
            sequenceNumber: args.sequenceNumber,
          });
  
        default:
          return {
            success: false,
            error: `Unknown message operation: ${args.operation}`,
          };
      }
    } catch (error) {
      logger.error('HCS message operation failed', { operation: args.operation, error });
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  }

• src/tools/composite.ts:595-636 (schema)

  Tool definition including name, description, and input schema for validation of 'hcs_message' parameters.

    {
      name: 'hcs_message',
      description: `Hedera Consensus Service (HCS) message operations.
  
  OPERATIONS:
  - submit: Submit message to topic (auto-chunks if >1KB)
  - query: Query historical messages with filtering (FREE via Mirror Node)
  
  USE THIS FOR: Publishing messages, retrieving consensus-ordered data, auditable logs.`,
      inputSchema: {
        type: 'object' as const,
        properties: {
          operation: {
            type: 'string',
            enum: ['submit', 'query'],
            description: 'Message operation',
          },
          topicId: {
            type: 'string',
            description: 'Topic ID (format: 0.0.xxxxx)',
          },
          message: {
            type: 'string',
            description: 'Message content (for submit)',
          },
          limit: {
            type: 'number',
            description: 'Max messages to return (for query)',
          },
          order: {
            type: 'string',
            enum: ['asc', 'desc'],
            description: 'Sort order (for query)',
          },
          sequenceNumber: {
            type: 'number',
            description: 'Filter by sequence number >= value',
          },
        },
        required: ['operation', 'topicId'],
      },
    },

• src/index.ts:600-602 (registration)

  MCP server registration: maps tool name 'hcs_message' to the hcsMessageManage handler in the main request handler switch.

  case 'hcs_message':
    result = await hcsMessageManage(args as any);
    break;

• src/tools/consensus.ts:86-134 (helper)

  Supporting function for submitting messages to HCS topics, called by the main handler for 'submit' operation.

  export async function submitMessage(args: {
    topicId: string;
    message: string;
    submitKey?: string;
  }): Promise<ToolResult> {
    try {
      logger.info('Submitting message to topic', {
        topicId: args.topicId,
        messageLength: args.message.length,
      });
  
      if (!hederaClient.isReady()) {
        await hederaClient.initialize();
      }
  
      // Try to get submit key from address book if not provided
      let submitKey = args.submitKey;
      if (!submitKey && addressBook.count() > 0) {
        // Check if operator account has a submit key in address book
        const client = hederaClient.getClient();
        const operatorId = client.operatorAccountId?.toString();
        if (operatorId) {
          const entries = addressBook.list();
          const entry = entries.find((e) => e.accountId === operatorId);
          if (entry?.privateKey) {
            submitKey = entry.privateKey;
            logger.info('Using submit key from address book');
          }
        }
      }
  
      const result = await hederaClient.submitMessage(args.topicId, args.message, submitKey);
  
      return {
        success: true,
        data: result,
        metadata: {
          executedVia: 'sdk',
          command: 'message submit',
        },
      };
    } catch (error) {
      logger.error('Failed to submit message', { error });
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  }

• src/tools/consensus.ts:139-173 (helper)

  Supporting function for querying messages from HCS topics via Mirror Node, called by the main handler for 'query' operation.

  export async function queryMessages(args: {
    topicId: string;
    sequenceNumber?: number;
    limit?: number;
    order?: 'asc' | 'desc';
  }): Promise<ToolResult> {
    try {
      logger.info('Querying topic messages', { topicId: args.topicId });
  
      if (!hederaClient.isReady()) {
        await hederaClient.initialize();
      }
  
      const result = await hederaClient.queryMessages(args.topicId, {
        sequenceNumber: args.sequenceNumber,
        limit: args.limit,
        order: args.order,
      });
  
      return {
        success: true,
        data: result,
        metadata: {
          executedVia: 'mirror_node',
          command: 'message query',
        },
      };
    } catch (error) {
      logger.error('Failed to query messages', { error });
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  }