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