FetchSERP MCP Server

Instructions

Implementation Reference

• index.js:641-642 (handler)

  Handler case for the 'get_domain_ranking' tool. It calls the shared makeRequest method with the specific API endpoint '/api/v1/ranking' to execute the tool logic.

  case 'get_domain_ranking':
    return await this.makeRequest('/api/v1/ranking', 'GET', args, null, token);

• index.js:218-248 (schema)

  Input schema validation for the get_domain_ranking tool, defining parameters: keyword (required), domain (required), search_engine, country, pages_number.

  inputSchema: {
    type: 'object',
    properties: {
      keyword: {
        type: 'string',
        description: 'The keyword to search',
      },
      domain: {
        type: 'string',
        description: 'The domain to search',
      },
      search_engine: {
        type: 'string',
        description: 'The search engine to use (google, bing, yahoo, duckduckgo). Default: google',
        default: 'google',
      },
      country: {
        type: 'string',
        description: 'The country to search from. Default: us',
        default: 'us',
      },
      pages_number: {
        type: 'integer',
        description: 'The number of pages to search (1-30). Default: 10',
        default: 10,
        minimum: 1,
        maximum: 30,
      },
    },
    required: ['keyword', 'domain'],
  },

• index.js:215-249 (registration)

  Registration of the 'get_domain_ranking' tool in the listTools handler response, providing name, description, and input schema.

  {
    name: 'get_domain_ranking',
    description: 'Get domain ranking for a given keyword',
    inputSchema: {
      type: 'object',
      properties: {
        keyword: {
          type: 'string',
          description: 'The keyword to search',
        },
        domain: {
          type: 'string',
          description: 'The domain to search',
        },
        search_engine: {
          type: 'string',
          description: 'The search engine to use (google, bing, yahoo, duckduckgo). Default: google',
          default: 'google',
        },
        country: {
          type: 'string',
          description: 'The country to search from. Default: us',
          default: 'us',
        },
        pages_number: {
          type: 'integer',
          description: 'The number of pages to search (1-30). Default: 10',
          default: 10,
          minimum: 1,
          maximum: 30,
        },
      },
      required: ['keyword', 'domain'],
    },
  },

• index.js:565-613 (helper)

  Shared helper method makeRequest used by the get_domain_ranking handler (and others) to perform authenticated HTTP requests to the FetchSERP API.

  async makeRequest(endpoint, method = 'GET', params = {}, body = null, token = null) {
    const fetchserpToken = token || process.env.FETCHSERP_API_TOKEN;
    
    if (!fetchserpToken) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        'FETCHSERP_API_TOKEN is required'
      );
    }
  
    const url = new URL(`${API_BASE_URL}${endpoint}`);
    
    // Add query parameters for GET requests
    if (method === 'GET' && Object.keys(params).length > 0) {
      Object.entries(params).forEach(([key, value]) => {
        if (value !== undefined && value !== null) {
          if (Array.isArray(value)) {
            value.forEach(v => url.searchParams.append(`${key}[]`, v));
          } else {
            url.searchParams.append(key, value.toString());
          }
        }
      });
    }
  
    const fetchOptions = {
      method,
      headers: {
        'Authorization': `Bearer ${fetchserpToken}`,
        'Content-Type': 'application/json',
      },
    };
  
    if (body && method !== 'GET') {
      fetchOptions.body = JSON.stringify(body);
    }
  
    const response = await fetch(url.toString(), fetchOptions);
    
    if (!response.ok) {
      const errorText = await response.text();
      throw new McpError(
        ErrorCode.InternalError,
        `API request failed: ${response.status} ${response.statusText} - ${errorText}`
      );
    }
  
    return await response.json();
  }