Grove's MCP Server for Pocket Network

Instructions

Implementation Reference

• src/handlers/blockchain-handlers.ts:62-88 (registration)

  Registers the 'call_rpc_method' MCP tool including name, description, and input schema definition.

  {
    name: 'call_rpc_method',
    description: 'Call a JSON-RPC method on a specific blockchain service',
    inputSchema: {
      type: 'object',
      properties: {
        blockchain: {
          type: 'string',
          description: 'Blockchain name (e.g., "ethereum", "polygon")',
        },
        method: {
          type: 'string',
          description: 'RPC method name (e.g., "eth_blockNumber", "eth_getBalance")',
        },
        params: {
          type: 'array',
          description: 'Array of parameters for the RPC method',
        },
        network: {
          type: 'string',
          enum: ['mainnet', 'testnet'],
          description: 'Network type (defaults to mainnet)',
        },
      },
      required: ['blockchain', 'method'],
    },
  },

• src/handlers/blockchain-handlers.ts:202-250 (handler)

  Executes the 'call_rpc_method' tool: performs safety validation, retrieves the appropriate blockchain service, calls the underlying callRPCMethod, and returns formatted result.

  case 'call_rpc_method': {
    const blockchain = args?.blockchain as string;
    const method = args?.method as string;
    const params = (args?.params as any[]) || [];
    const network = (args?.network as 'mainnet' | 'testnet') || 'mainnet';
  
    // SAFETY CHECK: Validate RPC call before execution
    const safetyCheck = validateRPCCall(blockchain, method, params);
    if (!safetyCheck.safe) {
      return {
        content: [
          {
            type: 'text',
            text: `⛔ UNSAFE RPC CALL BLOCKED\n\n` +
                  `Reason: ${safetyCheck.reason}\n\n` +
                  `Suggestion: ${safetyCheck.suggestion}\n\n` +
                  `This protection prevents session crashes from large responses.`,
          },
        ],
        isError: true,
      };
    }
  
    const service = blockchainService.getServiceByBlockchain(blockchain, network);
  
    if (!service) {
      return {
        content: [
          {
            type: 'text',
            text: `Blockchain service not found: ${blockchain} (${network})`,
          },
        ],
        isError: true,
      };
    }
  
    const result = await blockchainService.callRPCMethod(service.id, method, params);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
      isError: !result.success,
    };
  }

• src/services/blockchain-service.ts:153-248 (helper)

  Core helper function implementing the RPC method call: sends JSON-RPC POST request to the service endpoint, handles HTTP and JSON-RPC errors comprehensively, and returns structured EndpointResponse.

  async callRPCMethod(
    serviceId: string,
    method: string,
    params: any[] = []
  ): Promise<EndpointResponse> {
    const service = this.getServiceById(serviceId);
    if (!service) {
      return {
        success: false,
        error: `Service not found: ${serviceId}`,
      };
    }
  
    const rpcUrl = service.rpcUrl;
  
    try {
      const response = await fetch(rpcUrl, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          jsonrpc: '2.0',
          method,
          params,
          id: 1,
        }),
      });
  
      // Handle HTTP errors (rate limiting, server errors, etc.)
      if (!response.ok) {
        const errorText = await response.text().catch(() => 'Unable to read error response');
        let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
  
        // Common HTTP error interpretations
        if (response.status === 429) {
          errorMessage = `Rate limit exceeded (HTTP 429). The endpoint may be experiencing high traffic.`;
        } else if (response.status === 503) {
          errorMessage = `Service temporarily unavailable (HTTP 503). The endpoint may be overloaded.`;
        } else if (response.status >= 500) {
          errorMessage = `Server error (HTTP ${response.status}). The RPC endpoint encountered an internal error.`;
        }
  
        return {
          success: false,
          error: errorMessage,
          data: {
            httpStatus: response.status,
            httpStatusText: response.statusText,
            responseBody: errorText.substring(0, 500), // Limit error body size
          },
          metadata: {
            timestamp: new Date().toISOString(),
            endpoint: rpcUrl,
          },
        };
      }
  
      const data = await response.json();
  
      // Handle JSON-RPC errors
      if (data.error) {
        return {
          success: false,
          error: data.error.message || 'RPC error',
          data: data.error,
          metadata: {
            timestamp: new Date().toISOString(),
            endpoint: rpcUrl,
          },
        };
      }
  
      return {
        success: true,
        data: data.result,
        metadata: {
          timestamp: new Date().toISOString(),
          endpoint: rpcUrl,
        },
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
        data: {
          errorType: error instanceof Error ? error.constructor.name : 'UnknownError',
          errorStack: error instanceof Error ? error.stack : undefined,
        },
        metadata: {
          timestamp: new Date().toISOString(),
          endpoint: rpcUrl,
        },
      };
    }
  }