Job Search MCP

Сервер Model Context Protocol (MCP) с конфигурацией на основе данных для поиска вакансий непосредственно на сайтах карьеры компаний.

Позволяет ИИ-ассистентам (Claude, ChatGPT) искать и извлекать списки вакансий 5 фармацевтических компаний с расширяемой архитектурой для добавления неограниченного числа компаний.

Текущее покрытие: Amgen, Bayer, GSK, Novartis, Pfizer
Расширяемость: 250+ компаний (секторы здравоохранения, технологий, финансов)

Возможности

• ✅ MCP-совместимый инструмент поиска вакансий для ИИ-ассистентов

• ✅ Поддержка компаний на основе конфигурации (на основе JSON, без изменения кода)

• ✅ Извлечение подробной информации о вакансиях: должность, описание, требования, дата окончания, ссылки для отклика

• ✅ Интеллектуальное отслеживание ошибок: классификация 404, таймаутов, сетевых ошибок, ошибок парсинга

• ✅ Генерация CSV-отчетов для пакетной обработки

• ✅ Ноль внешних зависимостей для парсинга (извлечение на основе чистых регулярных выражений)

• ✅ Строгий режим TypeScript с полной типобезопасностью

• ✅ Специфичные для компаний HTML-парсеры (платформы Workday, Eightfold AI, Drupal)

• ✅ Опциональная веб-демонстрация по адресу /demo для ручного поиска вакансий

• ✅ Комплексный набор тестов (4 профессиональных теста)

Related MCP server: trackly-cli

Технологический стек

• Протокол: Model Context Protocol (MCP) SDK (TypeScript)

• Среда выполнения: Node.js v18+ (рекомендуется LTS: v18, v20, v22)

• Язык: TypeScript 5.3+ (строгий режим)

• Парсинг: Извлечение HTML на основе регулярных выражений (без Puppeteer, jsdom или Cheerio)

• Сборка: Компилятор TypeScript (tsc)

• Опциональный веб-интерфейс: React + Next.js + Tailwind CSS (для ручного поиска)

• Тестирование: Нативный Node.js (без jest/mocha)

Быстрый старт

Как MCP-сервер (для интеграции с ИИ)

1. Установка и сборка:

npm install
npm run build

2. Запуск MCP-сервера:

npm start
# Server runs on stdio (ready for Claude Desktop, Cursor, or other MCP clients)

3. Настройка в Claude Desktop (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "job-search": {
      "command": "node",
      "args": ["path/to/dist/server.js"]
    }
  }
}

4. Использование в Claude:

User: "Find me senior manager jobs at Amgen and Pfizer"
Claude: (uses MCP search tool)
Claude: "I found 12 senior manager positions with details..."

Как локальный CLI-инструмент

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run job search tests
npm run test
node dist/test/test-manager-jobs.js

Опционально: веб-демонстрация для ручного просмотра

Разверните включенную React-демонстрацию на Vercel (опционально):

# Deploy demo at https://[your-app].vercel.app/
vercel deploy

Архитектура проекта

Как MCP-сервер (основной режим)

Claude / AI Assistant
        ↓
    MCP Client Protocol (stdio)
        ↓
   MCP Server (src/server.ts)
        ↓
  Search Tool Handler
        ↓
┌──────────────────────────────────────┐
│  SearchExecutor (src/search-executor.ts)
│  - Orchestrates job searches
│  - Fetches from career site URLs
│  - Parses HTML for job listings
└──────────────────────────────────────┘
        ↓
┌──────────┬──────────┬──────────┬──────────┬──────────┐
│          │          │          │          │          │
Amgen    Bayer      GSK     Novartis    Pfizer
│          │          │          │          │
└──────────┴──────────┴──────────┴──────────┴──────────┘
        ↓
ExtractorRegistry (src/extractors/)
- 5 Company-specific parsers
- Extract: jobTitle, description, requirements, applyLink
- Track errors with classification
        ↓
Return JSON to AI Assistant

Опционально: веб-демонстрация

User → Web Browser
        ↓
  React Component (app/demo/page.tsx)
        ↓
  Next.js API Route (app/api/search-jobs/route.ts)
        ↓
  SearchExecutor (same as MCP uses)
        ↓
  Results + CSV reports

Конфигурация

src/config.json является источником истины для компаний, поддерживаемых проектом.

Текущие: 5 компаний (Amgen, Bayer, GSK, Novartis, Pfizer)
Расширяемость: добавление неограниченного числа компаний через JSON-конфигурацию (без изменения кода)

Пример:

{
  "projectname": "Job Search MCP",
  "sites": [
    {
      "name": "Amgen",
      "search_url": "https://amgen.wd1.myworkdayjobs.com/Careers?q={SEARCH_TERM}"
    },
    {
      "name": "Bayer",
      "search_url": "https://bayer.eightfold.ai/careers?query={SEARCH_TERM}"
    }
  ]
}

Добавление новых компаний

Чтобы добавить новую компанию:

1. Создайте запись в конфигурации: добавьте в src/config.json название компании и URL поиска

2. Создайте определение сайта: добавьте sites/company-name.json с параметрами поиска

3. Создайте экстрактор: добавьте src/extractors/company-name.ts с правилами парсинга HTML (только если используется новая платформа)

4. Зарегистрируйте экстрактор: добавьте в src/extractors/index.ts

Пересборка не требуется — конфигурация загружается во время выполнения.

Поддержка платформ компаний

Расширяемость: добавление 50+ компаний требует только JSON-конфигурации и переиспользуемых экстракторов платформ "name": "Pfizer", "search_url": "..." } ] }

Only the company name and a usable search URL need to be supplied when adding a new company.

## Site Definitions

Each company is represented by a separate file under `sites/`.

For example:

```text
sites/amgen.json

Структура должна соответствовать test/sample.json.

Определение сайта содержит:

• название компании

• URL карьеры

• URL поиска

• поддерживаемые параметры поиска

• метки параметров

• типы параметров

• доступные значения параметров

Структура параметров намеренно представляет собой массив, а не фиксированные JSON-ключи, поскольку разные сайты карьеры предоставляют разные параметры поиска.

Например, один сайт может предоставлять:

location
country
jobType

в то время как другой может предоставлять:

location
timeType
LocationCountry
jobFamilyGroup
workerSubType

MCP не должен предполагать, что каждая компания поддерживает одинаковые параметры.

Экстракторы вакансий

Проект включает специфичные для сайтов экстракторы вакансий, которые анализируют URL отдельных вакансий и извлекают подробную информацию.

Извлекаемые данные

Каждый экстрактор получает:

• Название должности — наименование позиции

• Описание вакансии — полное описание должности/обязанностей (исключая верхние и нижние колонтитулы)

• Соответствие требованиям — требования, квалификация и навыки

• Дата окончания — дата закрытия приема заявок (формат ГГГГ-ММ-ДД, пусто, если недоступно)

• Ссылка для отклика — прямой URL для подачи заявки (может отличаться от URL вакансии)

Доступные экстракторы

src/extractors/
├── types.ts                  # JobExtractor interface & types
├── amgen.ts                  # Amgen (Workday-based)
├── pfizer.ts                 # Pfizer (Workday-based)
├── bayer.ts                  # Bayer (Eightfold AI)
├── gsk.ts                    # GSK (Workday-based)
├── novartis.ts               # Novartis (Drupal)
└── index.ts                  # ExtractorRegistry

Пример использования

import { ExtractorRegistry } from './src/extractors/index.js';

const registry = new ExtractorRegistry();
const amgenExtractor = registry.getExtractor('amgen');

const result = await amgenExtractor?.extract(
  'https://amgen.wd1.myworkdayjobs.com/job/India---Hyderabad/Assoc-Director---Data-Product-Mgmt_R-219150'
);

if (result?.success && result.data) {
  console.log(result.data.jobTitle);
  console.log(result.data.jobDescription);
  console.log(result.data.eligibility);
}

Тестирование

Проект включает комплексный набор тестов для проверки функциональности поиска и извлечения.

Обзор набора тестов

Все тесты представляют собой автономные файлы TypeScript, которые можно запускать независимо:

npm run build
node dist/test/[test-name].js

Доступные тесты

1. test-config.ts — тест загрузки конфигурации

Проверяет, что конфигурации компаний корректно загружаются из src/config.json.

node dist/test/test-config.js

Назначение: проверяет структуру конфигурации и обнаружение компаний Вывод: список доступных компаний и их URL поиска

2. test-search.ts — тест поиска вакансий

Проверяет функциональность поиска по всем компаниям.

node dist/test/test-search.js

Назначение: проверяет, что поиск возвращает корректные URL вакансий Вывод: результаты поиска вакансий "Manager" для каждой компании Примечание: требуется подключение к интернету для доступа к реальным сайтам карьеры

3. test-extractors.ts — тест извлечения вакансий

Проверяет, что извлечение деталей вакансий работает для URL вакансий каждой компании.

node dist/test/test-extractors.js

Назначение: проверяет извлечение названия должности, описания и соответствия требованиям Вывод: процент успешного извлечения и детали полей Примечание: требуются реальные URL вакансий из вывода test-search.ts

4. test-manager-jobs.ts — сквозной интеграционный тест

Полный тест конвейера: поиск вакансий → извлечение деталей → генерация отчетов

node dist/test/test-manager-jobs.js

Назначение: полный интеграционный тест с отслеживанием ошибок и генерацией CSV-отчетов Вывод:

• test/manager-jobs-success.csv — успешно извлеченные данные о вакансиях

• test/manager-jobs-errors.csv — ошибки извлечения (404, таймауты и т. д.)

• Сводка в консоли с процентом успеха и разбивкой ошибок

Запуск всех тестов

npm run build
node dist/test/test-config.js
node dist/test/test-search.js
node dist/test/test-extractors.js
node dist/test/test-manager-jobs.js

Файлы вывода тестов

Сгенерированные CSV-отчеты сохраняются в папке test/:

• manager-jobs-success.csv — успешные извлечения вакансий

• manager-jobs-errors.csv — неудачные попытки извлечения с кодами ошибок

• Примеры HTML-файлов для отладки

Эти файлы создаются во время выполнения тестов и могут быть безопасно удалены. Они находятся в .gitignore.

test/sample.json

test/sample.json определяет ожидаемую структуру для отдельных файлов компаний.

Это схема-пример/шаблон, а не реестр компаний.

Текущий пример использует такие параметры, как location, timeType, LocationCountry, jobFamilyGroup и workerSubType.

BUILD.md

BUILD.md содержит инструкции для процесса ИИ/разработки, который создает MCP на основе конфигураций компаний.

Процесс сборки должен:

1. Прочитать src/config.json.

2. Обработать каждую компанию, указанную в sites.

3. Посетить/проанализировать предоставленный URL поиска.

4. Определить фактическую структуру карьеры/поиска компании.

5. Обнаружить доступные параметры поиска и их значения.

6. Сгенерировать или обновить соответствующий sites/<company>.json.

7. Убедиться, что сгенерированный файл соответствует структуре, определенной в test/sample.json.

8. Собрать/обновить общую реализацию MCP.

9. Проверить, что все настроенные сайты можно искать.

UPDATE.md

См. ai/UPDATE.md для инструкций по пересборке проекта при создании нового релиза.

Когда src/config.json изменяется, ИИ должен пересобрать все определения компаний, а не только вновь добавленные.

Это сделано намеренно.

Существующие сайты карьеры могут изменять:

• URL поиска

• параметры запроса

• названия фильтров

• значения фильтров

• структуру сайта карьеры

• реализацию ATS

Поэтому каждый релиз должен повторно проверять существующие файлы sites/*.json на соответствие текущим живым сайтам карьеры.

src/config.json updated
       │
       ▼
Rebuild ALL sites
       │
       ├── New company → create site JSON
       │
       └── Existing company → re-analyze and update
       │
       ▼
Rebuild common MCP
       │
       ▼
Validate

Структура проекта

JobSearchMCP/
├── src/                      # Source code & configs
│   ├── server.ts             # MCP server entry point
│   ├── search-executor.ts    # Search execution & parsing
│   ├── config-loader.ts      # Configuration loader
│   ├── types.ts              # TypeScript types
│   ├── config.json           # Company registry
│   ├── site_configurations.json
│   └── site_analysis.json
├── sites/                    # Company-specific configs
│   ├── amgen.json
│   ├── pfizer.json
│   ├── novartis.json
│   ├── bayer.json
│   └── gsk.json
├── test/                     # Tests & test data
│   ├── test-*.js             # Test scripts
│   ├── sample.json           # Configuration template
│   └── *.html                # Sample HTML files
├── ai/                       # AI development notes (Gitignored)
│   ├── AI.md
│   └── UPDATE.md
├── reports/                  # Documentation
│   ├── IMPLEMENTATION.md
│   ├── ANALYSIS_GUIDE.md
│   ├── MCP_USAGE.md
│   └── MIGRATION.md
├── dist/                     # Compiled JavaScript
├── package.json              # Dependencies & scripts
├── tsconfig.json             # TypeScript config
└── README.md                 # This file

Технологии

Среда выполнения: Node.js Язык: TypeScript MCP SDK: официальный TypeScript SDK Model Context Protocol Конфигурация: JSON

Принцип проектирования

Проект разделяет специфичные для сайтов знания и общую логику MCP.

sites/*.json
    = How a particular company career site works

MCP implementation
    = How to search any configured company

AI
    = Understand the user's request and select/use the appropriate
      company search configuration

MCP не должен содержать жестко заданных предположений о таких параметрах, как location, remote, full_time или job_type.

Параметр существует для компании только в том случае, если сайт карьеры этой компании фактически поддерживает его или предоставляет информацию, требуемую конфигурацией.

Цель

Цель — создать переиспользуемый MCP для поиска вакансий, где добавление компаний в первую очередь сводится к добавлению их URL поиска в config.json, что позволяет процессу сборки ИИ автоматически обнаруживать и поддерживать специфичные для сайтов конфигурации.