job-mcp

{"type": "text"}# Servidor FastMCP universal de búsqueda de empleo de múltiples fuentes (job-mcp)

Un servidor FastMCP de nivel empresarial y centrado en la privacidad que ofrece agregación inteligente de empleos tecnológicos de múltiples fuentes, deduplicación inteligente, extracción dinámica de habilidades del CV, puntuación de cobertura de requisitos y flujos de trabajo autónomos de solicitud de empleo en HireMeTech, Comeet ATS y AllJobs Israel.

Descripción general de la arquitectura

graph TD
    Client([MCP Client: Claude / Cursor / Gemini Spark / Antigravity]) --> Tools[FastMCP Server Layer]
    Tools --> Aggregator[JobAggregator]
    Aggregator --> Registry[SourceRegistry]

    subgraph Parallel Pluggable Sources Layer
        Registry --> S1[HireMeTechSource<br/>Direct REST API + Session Fallback]
        Registry --> S2[ComeetSource<br/>Direct ATS API + Concurrency Semaphore]
        Registry --> S3[AllJobsSource<br/>Category Feeds + Anti-Blocking Headers]
    end

    subgraph Processing & Normalization Engine
        S1 --> Dedup[Deduplication & Entity Merger]
        S2 --> Dedup
        S3 --> Dedup
        
        Dedup --> NormKey["Key = slug(title) + '@' + slug(company)"]
        NormKey --> Merge[Metadata & Links Merger]
        Merge --> Scorer[Unified CV / Skill Matcher]
    end

    subgraph Dynamic Candidate Engine
        CV["Candidate CV (.pdf / .docx / .txt)"] --> Extractor[Dynamic CV & Profile Extractor]
        Extractor --> Skills["Extracted Skills (40+ tokens)"]
        Extractor --> Seniority["Inferred Seniority & Exclusions"]
        Extractor --> Roles["Target Job Roles"]
        Skills --> Scorer
        Seniority --> Scorer
    end

    Scorer --> Cache[Unified JobCache - 1h TTL]
    Cache --> Tools

Características principales

1. Extracción dinámica de CV y perfil del candidato:

   • Ingestión de múltiples formatos: admite archivos .pdf (a través de pypdf), .docx (a través de python-docx) y .txt.

   • Segmentación de habilidades NLP y léxico dinámico: descubre y extrae más de 40 habilidades técnicas sin codificación rígida, admitiendo tecnologías complejas de varias palabras (p. ej., FastAPI, LangGraph, PostgreSQL, Smart Contracts, GraphRAG).

   • Detección automática de antigüedad y exclusión: infiere con precisión la antigüedad del candidato (Junior, Mid, Senior, Lead, Principal, Director) y genera palabras clave negativas inteligentes para filtrar puestos no coincidentes.

   • Filtrado de palabras vacías y ruido: descarta rigurosamente artefactos estructurales del currículum, fechas, títulos educativos y metadatos no técnicos.

2. Puntuación inteligente de cobertura de requisitos (0–100):

   • Proporción de cobertura de requisitos del puesto: calcula la exhaustividad con la que las habilidades del candidato satisfacen la pila tecnológica específica del puesto (matched_job_skills / total_job_skills), evitando penalizaciones para candidatos con currículums amplios.

   • Puntuación ponderada por componentes:

     • Superposición y cobertura de la pila tecnológica: hasta 40 puntos

     • Relevancia de palabras clave del CV completo: hasta 25 puntos

     • Alineación de modalidad de trabajo y ubicación: hasta 20 puntos

     • Expectativas salariales: hasta 15 puntos

     • Penalización por exclusión: -100 puntos por descalificaciones duras de antigüedad/tecnología.

   • Categorización por niveles de coincidencia:

     • Coincidencia de primer nivel ($\ge 85$): candidatos a solicitud automática / prioritaria.

     • Buena coincidencia ($70 - 84$): listados de alto interés marcados para revisión/marcadores.

     • Descalificado ($< 50$): se oculta o elimina automáticamente.

3. Arquitectura conectable de múltiples fuentes:

   • HireMeTech: integración directa con la API REST (/api/jobs/search, /api/auth/me, /api/resume/profile) con respaldo DOM automatizado.

   • Comeet (ATS directo): integración directa con la API de carreras de Comeet (/careers-api/2.0/company/{id}/positions) con limitación de velocidad asyncio.Semaphore(5), indexación de directorio tecnológico y caché TTL por empresa.

   • AllJobs Israel: integración de fuentes de categorías con encabezados de navegador realistas y aislamiento de errores a nivel de fuente.

4. Deduplicación entre fuentes y fusión de entidades:

   • Elimina duplicados cuando los listados aparecen en múltiples bolsas de trabajo.

   • Fusiona listas de fuentes (sources: ["hiremetech", "comeet"]), une pilas tecnológicas, conserva la descripción más rica y prioriza enlaces de solicitud directa a ATS.

5. Modos de operación autónomo y supervisado:

   • Modo supervisado: confirmación MCP estándar para cada herramienta.

   • Modo autónomo: encadenamiento seguro de lectura/filtrado/marcadores sin avisos manuales; barrera de seguridad de dos etapas en el envío de solicitudes.

6. Observabilidad y resiliencia:

   • Registro estructurado JSON (structlog) que escribe en stderr con saneamiento de tokens/credenciales.

   • Seguimiento automático de ID de traza en todas las cargas útiles de ToolResponse.

Referencia de herramientas (9 herramientas)

Inicio rápido y configuración

1. Clonar e instalar dependencias

git clone https://github.com/zvieli/hireme_mcp.git
cd hireme_mcp

# Using uv (recommended)
uv venv .venv
uv pip install -e ".[dev]"
playwright install chromium

2. Configura tu perfil de candidato y CV

Coloca tu currículum (cv.pdf, cv.docx o cv.txt) en el directorio raíz:

cp /path/to/your/resume.pdf ./cv.pdf
cp .env.example .env

Edita .env para configurar la ruta predeterminada de tu CV y tus datos de contacto:

DEFAULT_CV_PATH=./cv.pdf
CANDIDATE_EMAIL=your.email@example.com
CANDIDATE_NAME="Your Name"

3. (Opcional) Configuración de autenticación por primera vez para HireMeTech

Comeet y AllJobs funcionan automáticamente sin iniciar sesión. Para autenticar tu cuenta de HireMeTech para acceso directo a la API y solicitud automática:

.venv/bin/python -m job_mcp.setup

1. Se abrirá una ventana del navegador Chromium.

2. Inicia sesión con tus credenciales.

3. Vuelve a la terminal y presiona [Enter] para guardar la sesión en ./browser_profile.

Ejecutar el servidor

Opción A: Usar Docker (recomendado)

# Build and run in background
docker compose up -d

# View live multi-source aggregation logs
docker compose logs -f hireme-mcp

Opción B: Ejecución local

# Streamable HTTP (Default for Web & Cloud Clients)
.venv/bin/python -m job_mcp --transport http --host 0.0.0.0 --port 8000

# Stdio (Default for Desktop Clients)
.venv/bin/python -m job_mcp --transport stdio

Ejecutor visual de canalizaciones CLI

Para ejecutar una prueba de descubrimiento, puntuación y solicitud autónoma completa directamente en tu terminal con salida visual enriquecida:

# Run with auto-extracted skills from your CV:
.venv/bin/python scripts/run_mock_llm_pipeline.py --cv ./cv.pdf

# Run with explicit stack override and remote filter:
.venv/bin/python scripts/run_mock_llm_pipeline.py --cv ./cv.pdf --stack "Python,FastAPI,LangGraph" --work-mode remote --location "Tel Aviv"

# Execute live application submissions (disabled by default in dry-run):
.venv/bin/python scripts/run_mock_llm_pipeline.py --cv ./cv.pdf --auto-apply

Configuración del cliente MCP

1. Claude Desktop (claude_desktop_config.json)

En Linux: ~/.config/Claude/claude_desktop_config.json
En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
En Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "job-search-mcp": {
      "command": "/absolute/path/to/hireme_mcp/.venv/bin/python",
      "args": ["-m", "job_mcp", "--transport", "stdio"],
      "env": {
        "BROWSER_HEADLESS": "true",
        "DEFAULT_CV_PATH": "/absolute/path/to/hireme_mcp/cv.pdf",
        "CANDIDATE_EMAIL": "candidate@example.com",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

2. Clientes MCP de Gemini Spark / Web

• URL del endpoint: https://<your-host-or-devtunnel-id>/mcp

• Transporte: Streamable HTTP

• Autenticación: Ninguna / Sin autenticación

Variables de entorno

Ejecutar pruebas

Ejecuta el conjunto completo de pruebas automatizadas (542 pruebas):

.venv/bin/pytest tests/ -v

Licencia

Este proyecto está licenciado bajo la Licencia MIT.