JobGPT MCP Server

Instructions

Implementation Reference

• src/tools/job-hunts.ts:42-86 (registration)

  The registration and handler implementation for the `create_job_hunt` MCP tool.

  server.tool(
    'create_job_hunt',
    'Create a new job hunt to start tracking and applying to jobs. A job hunt defines what jobs you want to find based on titles, locations, skills, salary, etc. You need at least one job hunt to use match_jobs or add_job_to_applications.',
    {
      name: z.string().describe('A name for this job hunt (e.g., "Senior Engineer roles in SF")'),
      config: z.object({
        titles: z.array(z.string()).describe('Job titles to match (required)'),
        locations: z.array(z.string()).optional().describe('Locations to match. Use plain city names without state abbreviations (e.g., "San Francisco" not "San Francisco, CA"). For states, use the full state name (e.g., "Texas"). Use "Remote" to match remote jobs worldwide without country restrictions.'),
        countries: z.array(z.string()).optional().describe('Country codes (e.g., ["US", "CA"])'),
        companies: z.array(z.string()).optional().describe('Companies to include'),
        excludedCompanies: z.array(z.string()).optional().describe('Companies to exclude'),
        skills: z.array(z.string()).optional().describe('Required skills'),
        remote: z.boolean().optional().describe('When true, only return remote jobs. When false or omitted, return all jobs (both remote and non-remote).'),
        baseSalaryMin: z.number().optional().describe('Minimum salary'),
        baseSalaryMax: z.number().optional().describe('Maximum salary'),
        expLevels: z.array(z.string()).optional().describe('Experience levels (e.g., ["SE" for Senior, "MI" for Mid-level, "EN" for Entry])'),
        industries: z.array(z.string()).optional().describe('Industries (use get_industries to see valid values)'),
        companySize: z.array(z.string()).optional().describe('Company sizes (e.g., ["xs" for 1-50, "s" for 50-200, "m" for 200-1K, "l" for 1K-5K, "xl" for 5K+])'),
        h1bSponsorship: z.boolean().optional().describe('H1B sponsorship required'),
        relevancy: z.enum(['HIGH', 'MEDIUM']).nullable().optional().describe('Search relevancy mode - HIGH for strict title/skills matching (recommended), MEDIUM for broader keyword-based results. Default is null (MEDIUM behavior).'),
        dateOffset: z.enum(['24H', '1D', '2D', '7D', '14D', '1M', '3M', '6M', '9M', '1Y']).nullable().optional().describe('Only match jobs posted within this time window (e.g., "7D" for last 7 days). Default is "7D".'),
        workArrangement: z.array(z.string()).optional().describe('Work arrangement filter (e.g., ["Full Time", "Part Time", "Contract", "Internship", "Freelance", "Temporary"]). Defaults to ["Full Time"] if not set.'),
        excludedKeywords: z.array(z.string()).optional().describe('Keywords to exclude from job results'),
        excludedTitles: z.array(z.string()).optional().describe('Job titles to exclude from results'),
      }).describe('Search filters configuration'),
      autoMode: z.boolean().optional().describe('Enable full autopilot mode (default: false). When enabled, jobs are automatically matched, scored against your resume using AI, and applied to if they meet your minMatchScore threshold. Resume customization (if enabled) is applied before each application. Each auto-apply consumes a credit.'),
      dailyLimit: z.number().optional().describe('Maximum jobs to auto-apply per day (default: 5, max: 100)'),
      minMatchScore: z.number().optional().describe('Minimum match score for auto-apply (0-1). Jobs below this score will not be auto-applied. Default is 0.70 (70%) when not explicitly set.'),
      customizeResume: z.boolean().optional().describe('Enable AI resume customization for applications (default: false)'),
    },
    async (args) => {
      if (!args.config || !args.config.titles) {
        throw new Error('config.titles is required');
      }
      const jobHunt = await client.createJobHunt({
        name: args.name,
        config: args.config as JobSearchFilters,
        autoMode: args.autoMode,
        dailyLimit: args.dailyLimit,
        minMatchScore: args.minMatchScore,
        customizeResume: args.customizeResume,
      });
      return { content: [{ type: 'text' as const, text: JSON.stringify({ message: 'Job hunt created successfully', jobHunt: formatJobHunt(jobHunt) }, null, 2) }] };
    }
  );