DataForSEO MCP Server

Instructions

Implementation Reference

• src/core/modules/backlinks/tools/backlinks-filters.tool.ts:103-120 (handler)

  The main handler function that fetches cached or fresh available filters from DataForSEO Backlinks API and returns them, either all or specific to the provided tool name.

  async handle(params: any): Promise<any> {
    try {
      const filters = await this.fetchAndCacheFilters();
      
      if (!params.tool) {
        return this.formatResponse(filters);
      }
  
      const toolFilters = filters[params.tool];
      if (!toolFilters) {
        throw new Error(`No filters found for tool: ${params.tool}`);
      }
  
      return this.formatResponse(toolFilters);
    } catch (error) {
      return this.formatErrorResponse(error);
    }
  }

• src/core/modules/backlinks/tools/backlinks-filters.tool.ts:52-56 (schema)

  Defines the input schema using Zod: optional 'tool' parameter as string.

  getParams(): z.ZodRawShape {
    return {
      tool: z.string().optional().describe('The name of the tool to get filters for')
    };

• src/core/modules/backlinks/backlinks-api.module.ts:29-62 (registration)

  Instantiates BacklinksFiltersTool and registers it along with other tools into a dictionary keyed by tool name, exposing description, params, and handler function.

  getTools(): Record<string, ToolDefinition> {
    const tools = [
      new BacklinksTool(this.dataForSEOClient),
      new BacklinksAnchorTool(this.dataForSEOClient),
      new BacklinksBulkBacklinksTool(this.dataForSEOClient),
      new BacklinksBulkNewLostReferringDomainsTool(this.dataForSEOClient),
      new BacklinksBulkNewLostBacklinksTool(this.dataForSEOClient),
      new BacklinksBulkRanksTool(this.dataForSEOClient),
      new BacklinksBulkReferringDomainsTool(this.dataForSEOClient),
      new BacklinksBulkSpamScoreTool(this.dataForSEOClient),
      new BacklinksCompetitorsTool(this.dataForSEOClient),
      new BacklinksDomainIntersectionTool(this.dataForSEOClient),
      new BacklinksDomainPagesSummaryTool(this.dataForSEOClient),
      new BacklinksDomainPagesTool(this.dataForSEOClient),
      new BacklinksPageIntersectionTool(this.dataForSEOClient),
      new BacklinksReferringDomainsTool(this.dataForSEOClient),
      new BacklinksReferringNetworksTool(this.dataForSEOClient),
      new BacklinksSummaryTool(this.dataForSEOClient),
      new BacklinksTimeseriesNewLostSummaryTool(this.dataForSEOClient),
      new BacklinksTimeseriesSummaryTool(this.dataForSEOClient),
      new BacklinksBulkPagesSummaryTool(this.dataForSEOClient),
      new BacklinksFiltersTool(this.dataForSEOClient)
      // Add more tools here
    ];
  
    return tools.reduce((acc, tool) => ({
      ...acc,
      [tool.getName()]: {
        description: tool.getDescription(),
        params: tool.getParams(),
        handler: (params: any) => tool.handle(params),
      },
    }), {});
  }

• src/core/modules/backlinks/tools/backlinks-filters.tool.ts:59-101 (helper)

  Fetches available filters from DataForSEO API if cache expired, parses response using TOOL_TO_FILTER_MAP to extract filters for each backlinks tool, and caches the result for 24 hours.

  private async fetchAndCacheFilters(): Promise<ToolFilters> {
    const now = Date.now();
    
    // Return cached data if it's still valid
    if (BacklinksFiltersTool.cache && 
        (now - BacklinksFiltersTool.lastFetchTime) < BacklinksFiltersTool.CACHE_TTL) {
      return BacklinksFiltersTool.cache;
    }
  
    // Fetch fresh data
    const response = await this.client.makeRequest('/v3/backlinks/available_filters', 'GET', null, true) as DataForSEOFullResponse;
    this.validateResponseFull(response);
  
    // Transform the response into our cache format
    const filters: ToolFilters = {};
    const result = response.tasks[0].result[0];
  
    // Process each tool's filters
    for (const [toolName, filterPath] of Object.entries(BacklinksFiltersTool.TOOL_TO_FILTER_MAP)) {
      const pathParts = filterPath.split('.');
      let current = result;
      
      // Navigate to the correct filter object
      for (const part of pathParts) {
        if (current && current[part]) {
          current = current[part];
        } else {
          current = null;
          break;
        }
      }
  
      if (current) {
        filters[toolName] = current;
      }
    }
  
    // Update cache
    BacklinksFiltersTool.cache = filters;
    BacklinksFiltersTool.lastFetchTime = now;
  
    return filters;
  }