Bright Data Web MCP

Instructions

Implementation Reference

• server.js:687-743 (handler)

  Generic handler for the web_data_facebook_company_reviews tool. It triggers a dataset collection on BrightData using the specific dataset_id, polls the snapshot status up to 600 times (1s intervals), reports progress if available, and returns the JSON string of the collected data or throws timeout/error.

  execute: tool_fn(`web_data_${id}`, async(data, ctx)=>{
      let trigger_response = await axios({
          url: 'https://api.brightdata.com/datasets/v3/trigger',
          params: {dataset_id, include_errors: true},
          method: 'POST',
          data: [data],
          headers: api_headers(),
      });
      if (!trigger_response.data?.snapshot_id)
          throw new Error('No snapshot ID returned from request');
      let snapshot_id = trigger_response.data.snapshot_id;
      console.error(`[web_data_${id}] triggered collection with `
          +`snapshot ID: ${snapshot_id}`);
      let max_attempts = 600;
      let attempts = 0;
      while (attempts < max_attempts)
      {
          try {
              if (ctx && ctx.reportProgress)
              {
                  await ctx.reportProgress({
                      progress: attempts,
                      total: max_attempts,
                      message: `Polling for data (attempt `
                          +`${attempts + 1}/${max_attempts})`,
                  });
              }
              let snapshot_response = await axios({
                  url: `https://api.brightdata.com/datasets/v3`
                      +`/snapshot/${snapshot_id}`,
                  params: {format: 'json'},
                  method: 'GET',
                  headers: api_headers(),
              });
              if (['running', 'building'].includes(snapshot_response.data?.status))
              {
                  console.error(`[web_data_${id}] snapshot not ready, `
                      +`polling again (attempt `
                      +`${attempts + 1}/${max_attempts})`);
                  attempts++;
                  await new Promise(resolve=>setTimeout(resolve, 1000));
                  continue;
              }
              console.error(`[web_data_${id}] snapshot data received `
                  +`after ${attempts + 1} attempts`);
              let result_data = JSON.stringify(snapshot_response.data);
              return result_data;
          } catch(e){
              console.error(`[web_data_${id}] polling error: `
                  +`${e.message}`);
              attempts++;
              await new Promise(resolve=>setTimeout(resolve, 1000));
          }
      }
      throw new Error(`Timeout after ${max_attempts} seconds waiting `
          +`for data`);
  }),

• server.js:487-496 (schema)

  Dataset configuration defining the id 'facebook_company_reviews', associated dataset_id, tool description, and input parameters (url: string url, num_of_reviews: string) used to build the tool schema.

  {
      id: 'facebook_company_reviews',
      dataset_id: 'gd_m0dtqpiu1mbcyc2g86',
      description: [
          'Quickly read structured Facebook company reviews data.',
          'Requires a valid Facebook company URL and number of reviews.',
          'This can be a cache lookup, so it can be more reliable than scraping',
      ].join('\n'),
      inputs: ['url', 'num_of_reviews'],
  }, {

• server.js:674-745 (registration)

  Dynamic registration loop that iterates over datasets (including facebook_company_reviews), builds Zod schema from inputs, constructs tool name 'web_data_facebook_company_reviews', description, parameters, and registers the tool using server.addTool.

  for (let {dataset_id, id, description, inputs, defaults = {}} of datasets)
  {
      let parameters = {};
      for (let input of inputs)
      {
          let param_schema = input=='url' ? z.string().url() : z.string();
          parameters[input] = defaults[input] !== undefined ?
              param_schema.default(defaults[input]) : param_schema;
      }
      addTool({
          name: `web_data_${id}`,
          description,
          parameters: z.object(parameters),
          execute: tool_fn(`web_data_${id}`, async(data, ctx)=>{
              let trigger_response = await axios({
                  url: 'https://api.brightdata.com/datasets/v3/trigger',
                  params: {dataset_id, include_errors: true},
                  method: 'POST',
                  data: [data],
                  headers: api_headers(),
              });
              if (!trigger_response.data?.snapshot_id)
                  throw new Error('No snapshot ID returned from request');
              let snapshot_id = trigger_response.data.snapshot_id;
              console.error(`[web_data_${id}] triggered collection with `
                  +`snapshot ID: ${snapshot_id}`);
              let max_attempts = 600;
              let attempts = 0;
              while (attempts < max_attempts)
              {
                  try {
                      if (ctx && ctx.reportProgress)
                      {
                          await ctx.reportProgress({
                              progress: attempts,
                              total: max_attempts,
                              message: `Polling for data (attempt `
                                  +`${attempts + 1}/${max_attempts})`,
                          });
                      }
                      let snapshot_response = await axios({
                          url: `https://api.brightdata.com/datasets/v3`
                              +`/snapshot/${snapshot_id}`,
                          params: {format: 'json'},
                          method: 'GET',
                          headers: api_headers(),
                      });
                      if (['running', 'building'].includes(snapshot_response.data?.status))
                      {
                          console.error(`[web_data_${id}] snapshot not ready, `
                              +`polling again (attempt `
                              +`${attempts + 1}/${max_attempts})`);
                          attempts++;
                          await new Promise(resolve=>setTimeout(resolve, 1000));
                          continue;
                      }
                      console.error(`[web_data_${id}] snapshot data received `
                          +`after ${attempts + 1} attempts`);
                      let result_data = JSON.stringify(snapshot_response.data);
                      return result_data;
                  } catch(e){
                      console.error(`[web_data_${id}] polling error: `
                          +`${e.message}`);
                      attempts++;
                      await new Promise(resolve=>setTimeout(resolve, 1000));
                  }
              }
              throw new Error(`Timeout after ${max_attempts} seconds waiting `
                  +`for data`);
          }),
      });
  }

• server.js:752-778 (helper)

  Helper wrapper function applied to all tools, including web_data_facebook_company_reviews, that implements rate limiting, usage statistics tracking, request/response logging, error reporting with HTTP details, and execution timing.

  function tool_fn(name, fn){
      return async(data, ctx)=>{
          check_rate_limit();
          debug_stats.tool_calls[name] = debug_stats.tool_calls[name]||0;
          debug_stats.tool_calls[name]++;
          debug_stats.session_calls++;
          let ts = Date.now();
          console.error(`[%s] executing %s`, name, JSON.stringify(data));
          try { return await fn(data, ctx); }
          catch(e){
              if (e.response)
              {
                  console.error(`[%s] error %s %s: %s`, name, e.response.status,
                      e.response.statusText, e.response.data);
                  let message = e.response.data;
                  if (message?.length)
                      throw new Error(`HTTP ${e.response.status}: ${message}`);
              }
              else
                  console.error(`[%s] error %s`, name, e.stack);
              throw e;
          } finally {
              let dur = Date.now()-ts;
              console.error(`[%s] tool finished in %sms`, name, dur);
          }
      };
  }