Job Search MCP

Un servidor de Model Context Protocol (MCP) basado en configuración para buscar empleos directamente en los sitios web de carreras de las empresas.

Permite que los asistentes de IA (Claude, ChatGPT) busquen y extraigan ofertas de empleo de 5 empresas farmacéuticas con una arquitectura extensible para añadir un número ilimitado de empresas.

Cobertura actual: Amgen, Bayer, GSK, Novartis, Pfizer
Ampliable a: más de 250 empresas (sectores sanitario, tecnológico y financiero)

Características

• ✅ Herramienta de búsqueda de empleo compatible con MCP para asistentes de IA

• ✅ Soporte de empresas basado en configuración (basado en JSON, sin necesidad de cambios de código)

• ✅ Extracción de información detallada del empleo: título, descripción, requisitos, fecha de caducidad, enlaces de solicitud

• ✅ Seguimiento inteligente de errores: clasificación de 404, tiempos de espera, errores de red, errores de análisis

• ✅ Generación de informes CSV para procesamiento por lotes

• ✅ Cero dependencias externas de análisis (extracción basada en expresiones regulares pura)

• ✅ Modo estricto de TypeScript con seguridad de tipos completa

• ✅ Analizadores HTML específicos por empresa (plataformas Workday, Eightfold AI, Drupal)

• ✅ Demostración web opcional en /demo para búsqueda manual de empleos

• ✅ Suite de pruebas completa (4 pruebas profesionales)

Related MCP server: trackly-cli

Pila Tecnológica

• Protocolo: SDK de Model Context Protocol (MCP) (TypeScript)

• Tiempo de ejecución: Node.js v18+ (LTS recomendado: v18, v20, v22)

• Lenguaje: TypeScript 5.3+ (modo estricto)

• Análisis: Extracción HTML basada en expresiones regulares (sin Puppeteer, jsdom ni Cheerio)

• Compilación: Compilador de TypeScript (tsc)

• Interfaz web opcional: React + Next.js + Tailwind CSS (para búsqueda manual)

• Pruebas: Node.js nativo (no se requiere jest ni mocha)

Inicio Rápido

Como Servidor MCP (para integración con IA)

1. Instalar y compilar:

npm install
npm run build

2. Iniciar el servidor MCP:

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

3. Configurar en Claude Desktop (~/.claude/claude_desktop_config.json):

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

4. Usar en 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..."

Como Herramienta CLI Local

# Install dependencies
npm install

# Build TypeScript
npm run build

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

Opcional: Demostración Web para Navegación Manual

Implemente la demostración React incluida en Vercel (opcional):

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

Arquitectura del Proyecto

Como Servidor MCP (principal)

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

Opcional: Demostración Web

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

Configuración

src/config.json es la fuente de verdad para las empresas que admite el proyecto.

Actual: 5 empresas (Amgen, Bayer, GSK, Novartis, Pfizer)
Ampliable: añada un número ilimitado de empresas mediante configuración JSON (sin necesidad de cambios de código)

Ejemplo:

{
  "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}"
    }
  ]
}

Añadir Nuevas Empresas

Para añadir una nueva empresa:

1. Crear entrada de configuración: añádala a src/config.json con el nombre de la empresa y la URL de búsqueda

2. Crear definición de sitio: añada sites/company-name.json con los parámetros de búsqueda

3. Crear extractor: añada src/extractors/company-name.ts con las reglas de análisis HTML (solo si se utiliza una plataforma nueva)

4. Registrar extractor: añádalo a src/extractors/index.ts

No es necesario recompilar — la configuración se carga en tiempo de ejecución.

Soporte de Plataformas por Empresa

Extensibilidad: añadir más de 50 empresas solo requiere configuración JSON y extractores de plataforma reutilizables "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

La estructura debe seguir test/sample.json.

Una definición de sitio contiene:

• nombre de la empresa

• URL de carreras

• URL de búsqueda

• parámetros de búsqueda admitidos

• etiquetas de los parámetros

• tipos de los parámetros

• valores disponibles de los parámetros

La estructura de parámetros es intencionadamente una matriz en lugar de claves JSON fijas porque los diferentes sitios web de carreras exponen diferentes parámetros de búsqueda.

Por ejemplo, un sitio puede exponer:

location
country
jobType

mientras que otro puede exponer:

location
timeType
LocationCountry
jobFamilyGroup
workerSubType

El MCP no debe asumir que todas las empresas admiten los mismos parámetros.

Extractores de Empleo

El proyecto incluye extractores de empleo específicos por sitio que analizan las URL individuales de las ofertas de empleo y extraen información detallada.

Datos Extraídos

Cada extractor recupera:

• Título del empleo — nombre del puesto

• Descripción del empleo — descripción/responsabilidades completas (excluye encabezados y pies de página)

• Elegibilidad — requisitos, cualificaciones y habilidades

• Fecha de caducidad — fecha límite de solicitud (formato AAAA-MM-DD, en blanco si no está disponible)

• Enlace de solicitud — URL directa para solicitar (puede diferir de la URL de la oferta)

Extractores Disponibles

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

Ejemplo de Uso

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);
}

Pruebas

El proyecto incluye una suite de pruebas completa para validar la funcionalidad de búsqueda y extracción.

Resumen de la Suite de Pruebas

Todas las pruebas son archivos TypeScript autocontenidos que se pueden ejecutar de forma independiente:

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

Pruebas Disponibles

1. test-config.ts — prueba de carga de la configuración

Comprueba que las configuraciones de las empresas se cargan correctamente desde src/config.json.

node dist/test/test-config.js

Propósito: valida la estructura de la configuración y el descubrimiento de empresas Salida: lista las empresas disponibles y sus URL de búsqueda

2. test-search.ts — prueba de búsqueda de empleo

Comprueba la funcionalidad de búsqueda en todas las empresas.

node dist/test/test-search.js

Propósito: verifica que las búsquedas devuelven URL de empleo válidas Salida: resultados de búsqueda para empleos de "Manager" en cada empresa Nota: requiere conectividad a internet para acceder a los sitios de carreras reales

3. test-extractors.ts — prueba de extracción de empleo

Comprueba que la extracción de detalles del empleo funciona para las URL de empleo de cada empresa.

node dist/test/test-extractors.js

Propósito: valida la extracción del título del empleo, la descripción y la elegibilidad Salida: tasa de éxito de la extracción y detalles de los campos Nota: requiere URL de empleo reales de la salida de test-search.ts

4. test-manager-jobs.ts — prueba de integración de extremo a extremo

Prueba completa del flujo: busca empleos → extrae detalles → genera informes

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

Propósito: prueba de integración completa con seguimiento de errores y generación de informes CSV Salida:

• test/manager-jobs-success.csv — datos de empleo extraídos correctamente

• test/manager-jobs-errors.csv — errores de extracción (404, tiempos de espera, etc.)

• Resumen en consola que muestra la tasa de éxito y el desglose de errores

Ejecución de Todas las Pruebas

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

Archivos de Salida de las Pruebas

Los informes CSV generados se almacenan en la carpeta test/:

• manager-jobs-success.csv — extracciones de empleo exitosas

• manager-jobs-errors.csv — intentos de extracción fallidos con códigos de error

• Archivos HTML de muestra para depuración

Estos archivos se generan durante la ejecución de las pruebas y se pueden eliminar de forma segura. Están en .gitignore.

test/sample.json

test/sample.json define la estructura esperada para los archivos de cada empresa.

Es un esquema mediante ejemplo/plantilla más que un registro de empresas.

El ejemplo actual utiliza parámetros como location, timeType, LocationCountry, jobFamilyGroup y workerSubType.

BUILD.md

BUILD.md contiene las instrucciones para el proceso de IA/desarrollo que construye el MCP a partir de las configuraciones de las empresas.

El proceso de compilación debe:

1. Leer src/config.json.

2. Procesar todas las empresas enumeradas en sites.

3. Visitar/analizar la URL de búsqueda proporcionada.

4. Determinar la estructura real de carreras/búsqueda de la empresa.

5. Descubrir los parámetros de búsqueda disponibles y sus valores.

6. Generar o actualizar el correspondiente sites/<company>.json.

7. Asegurarse de que el archivo generado sigue la estructura definida por test/sample.json.

8. Compilar/actualizar la implementación común del MCP.

9. Validar que todos los sitios configurados se pueden buscar.

UPDATE.md

Consulte ai/UPDATE.md para obtener instrucciones sobre cómo reconstruir el proyecto cuando se crea una nueva versión.

Cuando src/config.json cambia, la IA debe reconstruir todas las definiciones de empresas, y no solo las empresas recién añadidas.

Esto es intencionado.

Los sitios de carreras existentes pueden cambiar:

• sus URL de búsqueda

• sus parámetros de consulta

• los nombres de los filtros

• los valores de los filtros

• la estructura del sitio de carreras

• la implementación del ATS

Por lo tanto, cada versión debe volver a comprobar los archivos sites/*.json existentes frente a los sitios de carreras en línea actuales.

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

Estructura del Proyecto

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

Tecnología

Tiempo de ejecución: Node.js Lenguaje: TypeScript SDK de MCP: SDK oficial de Model Context Protocol en TypeScript Configuración: JSON

Principio de Diseño

El proyecto separa el conocimiento específico del sitio de la lógica común del 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

El MCP no debe contener suposiciones codificadas sobre parámetros como location, remote, full_time o job_type.

Un parámetro solo existe para una empresa si el sitio de carreras de esa empresa realmente lo admite o expone la información requerida por la configuración.

Objetivo

El objetivo es crear un MCP de búsqueda de empleo reutilizable en el que añadir empresas sea principalmente una cuestión de agregar sus URL de búsqueda a config.json, lo que permite que el proceso de compilación de la IA descubra y mantenga automáticamente las configuraciones específicas del sitio.