query_blockchain

Instructions

Implementation Reference

• src/handlers/blockchain-handlers.ts:16-28 (schema)

  Defines the tool name, description, and input schema (natural language query) for 'query_blockchain'.

  {
    name: 'query_blockchain',
    description: 'Execute a natural language query to interact with blockchain data (e.g., "get the latest height for ethereum")',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Natural language query describing what you want to do',
        },
      },
      required: ['query'],
    },

• src/handlers/blockchain-handlers.ts:125-156 (handler)

  Handler logic for 'query_blockchain': performs safety validation on the query, calls BlockchainRPCService.executeQuery(), formats and returns the RPC result.

  case 'query_blockchain': {
    const query = args?.query as string;
    
    // SAFETY CHECK: Validate query before execution
    const safetyCheck = validateNaturalLanguageQuery(query);
    if (!safetyCheck.safe) {
      return {
        content: [
          {
            type: 'text',
            text: `⛔ UNSAFE QUERY BLOCKED\n\n` +
                  `Reason: ${safetyCheck.reason}\n\n` +
                  `Suggestion: ${safetyCheck.suggestion}\n\n` +
                  `This protection prevents session crashes from large responses.`,
          },
        ],
        isError: true,
      };
    }
    
    const result = await blockchainService.executeQuery(query);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
      isError: !result.success,
    };
  }

• src/services/blockchain-service.ts:253-283 (helper)

  Core implementation delegated by handler: parses natural language query, matches to RPC method/service, builds parameters, executes RPC call via callRPCMethod.

  async executeQuery(query: string): Promise<EndpointResponse> {
    const parsed = this.parseQuery(query);
    const matches = this.findMethodByQuery(parsed.intent);
  
    if (matches.length === 0) {
      return {
        success: false,
        error: `No matching methods found for query: "${query}"`,
      };
    }
  
    // Filter by blockchain if specified
    let filteredMatches = matches;
    if (parsed.blockchain) {
      filteredMatches = matches.filter(
        m => m.service.blockchain === parsed.blockchain
      );
  
      if (filteredMatches.length === 0) {
        filteredMatches = matches; // Fall back to all matches
      }
    }
  
    // Use the first match
    const { method, service } = filteredMatches[0];
  
    // Build params based on method requirements
    const params = this.buildParamsForMethod(method, query);
  
    return this.callRPCMethod(service.id, method.name, params);
  }

• src/index.ts:88-101 (registration)

  Registers the blockchain tools (including query_blockchain schema) by collecting from registerBlockchainHandlers and setting up listTools handler.

  const tools: Tool[] = [
    ...registerBlockchainHandlers(server, blockchainService),
    ...registerDomainHandlers(server, domainResolver),
    ...registerTransactionHandlers(server, advancedBlockchain),
    ...registerTokenHandlers(server, advancedBlockchain),
    ...registerMultichainHandlers(server, advancedBlockchain),
    ...registerContractHandlers(server, advancedBlockchain),
    ...registerUtilityHandlers(server, advancedBlockchain),
    ...registerEndpointHandlers(server, endpointManager),
    ...registerSolanaHandlers(server, solanaService),
    ...registerCosmosHandlers(server, cosmosService),
    ...registerSuiHandlers(server, suiService),
    ...registerDocsHandlers(server, docsManager),
  ];

• src/index.ts:114-126 (registration)

  Dispatches tool calls to handleBlockchainTool (first in sequence), which handles query_blockchain via switch case.

  let result =
    (await handleBlockchainTool(name, args, blockchainService)) ||
    (await handleDomainTool(name, args, domainResolver)) ||
    (await handleTransactionTool(name, args, advancedBlockchain)) ||
    (await handleTokenTool(name, args, advancedBlockchain)) ||
    (await handleMultichainTool(name, args, advancedBlockchain)) ||
    (await handleContractTool(name, args, advancedBlockchain)) ||
    (await handleUtilityTool(name, args, advancedBlockchain)) ||
    (await handleEndpointTool(name, args, endpointManager)) ||
    (await handleSolanaTool(name, args, solanaService)) ||
    (await handleCosmosTool(name, args, cosmosService)) ||
    (await handleSuiTool(name, args, suiService)) ||
    (await handleDocsTool(name, args, docsManager));