AlsoAsked MCP Server

Instructions

Implementation Reference

• src/index.ts:227-231 (handler)

  Handler for 'search_single_term' tool: validates arguments using validateSingleTermArgs, wraps the single term into a terms array, and delegates execution to the shared handleSearch method.

  case 'search_single_term':
    const singleTermArgs = this.validateSingleTermArgs(args);
    const { term, ...otherArgs } = singleTermArgs;
    return await this.handleSearch({ terms: [term], ...otherArgs });

• src/index.ts:176-210 (schema)

  Input schema definition for the 'search_single_term' tool, specifying parameters like term (required), language, region, geo coordinates, and depth.

  inputSchema: {
    type: 'object',
    properties: {
      term: {
        type: 'string',
        description: 'Single search term',
      },
      language: {
        type: 'string',
        description: 'Language code',
        default: 'en',
      },
      region: {
        type: 'string',
        description: 'Region code', 
        default: 'us',
      },
      latitude: {
        type: 'number',
        description: 'Latitude for geographic targeting',
      },
      longitude: {
        type: 'number',
        description: 'Longitude for geographic targeting',
      },
      depth: {
        type: 'integer',
        description: 'Depth of question hierarchy',
        default: 2,
        minimum: 1,
        maximum: 3,
      },
    },
    required: ['term'],
  },

• src/index.ts:173-211 (registration)

  Registration of the 'search_single_term' tool in the ListTools response array, including name, description, and input schema.

  {
    name: 'search_single_term',
    description: 'Search for PAA questions for a single term (convenience method)',
    inputSchema: {
      type: 'object',
      properties: {
        term: {
          type: 'string',
          description: 'Single search term',
        },
        language: {
          type: 'string',
          description: 'Language code',
          default: 'en',
        },
        region: {
          type: 'string',
          description: 'Region code', 
          default: 'us',
        },
        latitude: {
          type: 'number',
          description: 'Latitude for geographic targeting',
        },
        longitude: {
          type: 'number',
          description: 'Longitude for geographic targeting',
        },
        depth: {
          type: 'integer',
          description: 'Depth of question hierarchy',
          default: 2,
          minimum: 1,
          maximum: 3,
        },
      },
      required: ['term'],
    },
  },

• src/index.ts:267-287 (helper)

  validateSingleTermArgs helper function: input validation and normalization specific to search_single_term tool arguments.

  private validateSingleTermArgs(args: Record<string, unknown> | undefined): { term: string } & Partial<SearchRequestOptions> {
    if (!args || typeof args !== 'object') {
      throw new Error('Invalid arguments provided');
    }
  
    if (!args.term || typeof args.term !== 'string') {
      throw new Error('term parameter is required and must be a string');
    }
  
    return {
      term: args.term,
      language: typeof args.language === 'string' ? args.language : undefined,
      region: typeof args.region === 'string' ? args.region : undefined,
      latitude: typeof args.latitude === 'number' ? args.latitude : undefined,
      longitude: typeof args.longitude === 'number' ? args.longitude : undefined,
      depth: typeof args.depth === 'number' ? args.depth : undefined,
      fresh: typeof args.fresh === 'boolean' ? args.fresh : undefined,
      async: typeof args.async === 'boolean' ? args.async : undefined,
      notifyWebhooks: typeof args.notifyWebhooks === 'boolean' ? args.notifyWebhooks : undefined,
    };
  }

• src/index.ts:289-341 (helper)

  handleSearch core helper: executes the API request to AlsoAsked /search endpoint, processes and formats the response into structured JSON output. Shared with search_people_also_ask tool.

  private async handleSearch(options: SearchRequestOptions) {
    const searchData: SearchRequestOptions = {
      terms: options.terms,
      language: options.language || 'en',
      region: options.region || 'us', 
      latitude: options.latitude,
      longitude: options.longitude,
      depth: options.depth || 2,
      fresh: options.fresh || false,
      async: options.async || false,
      notifyWebhooks: options.notifyWebhooks || false,
    };
  
    // Remove undefined values to avoid sending them to the API
    Object.keys(searchData).forEach(key => {
      if (searchData[key as keyof SearchRequestOptions] === undefined) {
        delete searchData[key as keyof SearchRequestOptions];
      }
    });
  
    const response: SearchResponse = await this.makeApiRequest('/search', {
      method: 'POST',
      body: JSON.stringify(searchData),
    });
  
    if (response.status !== 'success') {
      throw new Error(`Search failed: ${response.message || 'Unknown error'}`);
    }
  
    // Format results for better readability
    const formattedResults = response.queries.map(query => ({
      searchTerm: query.term,
      totalQuestions: this.countTotalQuestions(query.results),
      questions: this.formatQuestionHierarchy(query.results),
    }));
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            status: response.status,
            searchId: response.id,
            results: formattedResults,
            summary: {
              totalSearchTerms: response.queries.length,
              totalQuestions: formattedResults.reduce((sum, result) => sum + result.totalQuestions, 0),
            }
          }, null, 2),
        },
      ],
    };
  }