search_jobs

Instructions

Implementation Reference

• src/index.ts:130-224 (schema)

  Defines the tool metadata, description, and detailed input schema with parameters, types, descriptions, and defaults for the search_jobs tool.

  const SEARCH_JOBS_TOOL = {
    name: "search_jobs",
    description: `Google Jobs API search tool.
  
  Supported search parameters:
  1. Basic Search: Job title or keywords
  2. Location: City or region
  3. Time Filter: Recently posted jobs
  4. Job Type: Full-time, part-time, contract, internship
  5. Salary Range: Filter by compensation
  6. Geographic Range: Set search radius
  7. Language: Multi-language support
  
  All parameters except 'query' are optional and can be freely combined.`,
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Search keywords (Required, e.g., 'software engineer', 'data analyst', 'product manager')"
        },
        location: {
          type: "string",
          description: "Job location (Optional, e.g., 'New York', 'London', 'Tokyo')",
          default: ""
        },
        posted_age: {
          type: "string",
          description: `Posting date filter (Optional)
  Options:
  - "today": Posted today
  - "3days": Last 3 days
  - "week": Last week
  - "month": Last month`,
          default: ""
        },
        employment_type: {
          type: "string",
          description: `Job type (Optional)
  Options:
  - "FULLTIME": Full-time
  - "PARTTIME": Part-time
  - "CONTRACTOR": Contractor
  - "INTERN": Internship
  - "TEMPORARY": Temporary`,
          default: ""
        },
        salary: {
          type: "string",
          description: `Salary range (Optional)
  Format examples:
  - "$50K+": Above $50,000
  - "$100K+": Above $100,000
  - "$150K+": Above $150,000`,
          default: ""
        },
        radius: {
          type: "string",
          description: `Search radius (Optional)
  Format examples:
  - "10mi": Within 10 miles
  - "20mi": Within 20 miles
  - "50mi": Within 50 miles`,
          default: ""
        },
        hl: {
          type: "string",
          description: `Result language (Optional)
  Options:
  - "en": English
  - "zh-CN": Chinese
  - "ja": Japanese
  - "ko": Korean`,
          default: "en"
        },
        page: {
          type: "number",
          description: `Page number (Optional, default: 1)
  - 10 results per page
  - Supports pagination`,
          default: 1
        },
        sort_by: {
          type: "string",
          description: `Sort order (Optional)
  Options:
  - "date": Sort by date
  - "relevance": Sort by relevance
  - "salary": Sort by salary`,
          default: "relevance"
        }
      },
      required: ["query"]
    }
  };

• src/index.ts:448-450 (registration)

  Registers the search_jobs tool object in the MCP server's ListTools request handler.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [SEARCH_JOBS_TOOL]
  }));

• src/index.ts:452-493 (handler)

  MCP CallToolRequestSchema handler that validates the tool name and arguments, calls performJobSearch for search_jobs, handles success/error responses with localized error messages.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    try {
      const { name, arguments: args } = request.params;
      
      if (name !== "search_jobs") {
        throw new Error("Unknown tool");
      }
  
      if (!args || typeof args.query !== "string") {
        throw new Error("Invalid arguments for search_jobs");
      }
  
      const results = await performJobSearch(
        args.query,
        args.location as string | undefined,
        args.posted_age as string | undefined,
        args.employment_type as string | undefined,
        args.salary as string | undefined,
        args.radius as string | undefined,
        args.hl as SupportedLanguage | undefined
      );
  
      return {
        content: [{ type: "text", text: results }],
        isError: false
      };
    } catch (error) {
      const args = request.params.arguments as { query?: string; hl?: SupportedLanguage } | undefined;
      const query = args?.query || "";
      const lang = args?.hl || "en";
      const t = getLocalizedText(lang);
      const suggestions = getSearchSuggestions(error, query, lang);
      
      return {
        content: [{ 
          type: "text", 
          text: `❌ ${t.error}:\n${error instanceof Error ? error.message : String(error)}\n${suggestions}` 
        }],
        isError: true
      };
    }
  });

• src/index.ts:372-445 (handler)

  Core handler function for search_jobs: validates params, constructs SerpAPI Google Jobs URL with filters, fetches and parses JSON response, formats output using helper functions.

  async function performJobSearch(
    query: string, 
    location?: string, 
    posted_age?: string,
    employment_type?: string,
    salary?: string,
    radius?: string,
    hl?: SupportedLanguage
  ) {
    // Parameter validation
    const warnings = validateSearchParams({
      query,
      location,
      salary,
      radius
    }, hl);
    
    let output = "";
    if (warnings.length > 0) {
      const t = getLocalizedText(hl);
      output += `⚠️ ${t.warning}:\n`;
      warnings.forEach(warning => {
        output += `• ${warning}\n`;
      });
      output += `\n`;
    }
  
    // Build search URL
    const url = new URL('https://serpapi.com/search');
    url.searchParams.set('engine', 'google_jobs');
    url.searchParams.set('q', query);
    url.searchParams.set('api_key', SERP_API_KEY as string);
    
    // Add basic parameters
    if (location) {
      url.searchParams.set('location', location);
    }
    
    if (posted_age) {
      url.searchParams.set('chips', `date_posted:${posted_age}`);
    }
  
    // Add additional parameters
    if (employment_type) {
      url.searchParams.append('chips', `employment_type:${employment_type}`);
    }
  
    if (salary) {
      url.searchParams.append('chips', `salary:${salary}`);
    }
  
    if (radius) {
      url.searchParams.set('location_distance', radius);
    }
  
    if (hl) {
      url.searchParams.set('hl', hl);
    }
  
    // Make API request
    const response = await fetch(url.toString());
    if (!response.ok) {
      throw new Error(`Serp API error: ${response.status} ${response.statusText}`);
    }
  
    // Process response
    const data = await response.json() as JobSearchResponse;
    return output + formatJobResults(
      data.jobs_results || [], 
      data.search_metadata || {}, 
      data.page || 1,
      hl
    );
  }