Ejecutar Sweepy desde un asistente de IA con MCP

Un asistente de IA puede ejecutar Sweepy por ti. Describes el puesto que quieres y el asistente llama a Sweepy en tu nombre en lugar de pedirte que escribas comandos en el terminal.

Esa conexión usa el Model Context Protocol (MCP). MCP es un lenguaje compartido que permite a un asistente de IA usar herramientas instaladas en tu ordenador. Sweepy incluye un servidor MCP integrado en server.py. Se ejecuta sobre el transporte stdio, así que habla con tu cliente de forma local y no abre ningún puerto de red.

nota

MCP es opcional. Sweepy funciona por completo con comandos de terminal, sin ningún asistente de IA. El servidor añade una capa conversacional sobre el mismo motor. También aporta el criterio y la inteligencia del modelo a la puntuación y el filtrado deterministas que Sweepy ya realiza.

Antes de conectar

• Completa la instalación para que Python y las dependencias de Sweepy estén listas. Los paquetes mcp y anyio llegan con requirements.txt.
• Anota la ruta absoluta a server.py. Pegarás esa ruta en la configuración de tu cliente.
• Reinicia tu cliente de IA después de cambiar su configuración MCP.

Herramientas disponibles

Sweepy expone doce herramientas a tu asistente. Cada una devuelve una carga útil JSON y declara indicadores de solo lectura, destructiva, idempotente y de mundo abierto.

Herramienta	Qué hace
create_profile	Crea, valida y guarda un perfil YAML a partir de un currículum en PDF o DOCX.
run_sweep	Ejecuta el proceso de cinco etapas en segundo plano y almacena fichas deterministas.
get_sweep_status	Espera a un barrido en curso e informa de su progreso.
get_jobs	Devuelve las fichas de la sesión actual, ordenadas por puntuación.
submit_judgments	Sustituye los campos deterministas de una ficha por el criterio de tu asistente.
import_jobs	Añade ofertas que tu asistente verificó en otro lugar.
render_report	Genera el PDF de fichas a partir de la sesión actual.
get_results	Lee del disco el resultado del barrido más reciente.
export_report	Reconstruye archivos PDF, PNG, CSV o JSON de un barrido existente.
clear_history	Olvida las ofertas informadas de un perfil.
convert_document	Convierte un documento compatible a PDF.
convert_docx	Convierte un currículum DOCX a PDF.

La referencia de herramientas MCP entra en más detalle. Enumera cada parámetro, valor predeterminado, carga útil e indicador de comportamiento.

Elegir motores de búsqueda de empleo

Cuando omites sources_config, create_profile activa los motores integrados JobSpy y ATS. También activa los motores opcionales que tienen una instalación operativa y valores predeterminados válidos. La herramienta devuelve enabled_engines y engines_not_enabled, así que puedes ver qué motores se ejecutan y cuáles aún necesitan configuración.

OpenRoles busca solo en las plataformas de empresa que indiques. Añade slugs de empresa antes de activarlo. Apify puede generar cargos. Actívalo si quieres. Sweepy no instala paquetes opcionales automáticamente. No necesitas seleccionar motores para cada búsqueda. Elígelos explícitamente solo cuando un motor necesite configuración, consentimiento de pago o una restricción de búsqueda.

Pasa sources_config cuando elijas motores explícitamente. Sweepy mantiene esa selección en lugar de añadir otros motores. Este JSON selecciona dos motores:

{
  "enabled": ["jobspy", "openroles"],
  "openroles": {"companies": ["figma", "stripe"]}
}

Flujos de herramientas en un solo paso y en modo híbrido

Sweepy funciona con dos patrones. Elige el que se ajuste a cuánto quieres que decida el asistente.

Flujo en un solo paso. Tu asistente lo configura y lo ejecuta todo, y el motor puntúa cada puesto por solapamiento de palabras clave con el currículum.

create_profile -> run_sweep -> get_results -> export_report (optional)

Flujo híbrido con estado. Tu asistente revisa cada ficha y aporta su propio criterio antes de que se genere el informe.

run_sweep -> get_jobs -> submit_judgments -> render_report

Un barrido en curso puede seguir ejecutándose después de que el cliente agote el tiempo de espera. Cuando run_sweep devuelve sweep_status: "running", llama a get_sweep_status con el job_id devuelto hasta que informe de completed. Después, continúa con get_jobs.

consejo

No necesitas un LLM para obtener un informe funcional. La herramienta run_sweep por sí sola genera el PDF completo de fichas a partir de los campos deterministas, igual que un barrido en el terminal.

Cada ficha muestra una de estas dos etiquetas de puntuación:

• NN% KEYWORD OVERLAP procede del motor determinista. Compara el texto de tu currículum con cada oferta.
• NN% MATCH procede de tu asistente. Aparece cuando llamas a submit_judgments con un valor match_pct.

Verificar y completar los resultados del barrido

Trata cada resultado de barrido como un conjunto inicial y verifica cada coincidencia con la oferta. Después de run_sweep, revisa skipped_sources e informa de los fallos de las fuentes. Revisa los puestos con get_jobs y luego compara cada oferta con tu currículum y tus preferencias declaradas antes de que tu asistente envíe un juicio del LLM.

Cuando tu asistente tenga herramientas web o de búsqueda, pídele que verifique los puestos prometedores en las páginas de empleo del empleador o en su ATS. También puede buscar puestos relevantes que Sweepy no encontró, añadir ofertas verificadas y no duplicadas con import_jobs e incluir esos puestos en el informe con render_report. Tu asistente no debe inventar ofertas ni rellenar detalles que faltan con suposiciones.

El verificador de URL de Sweepy deja algunas URL como no verificadas cuando un host bloquea el acceso, limita las peticiones o agota el tiempo de espera. Un 403 o un 429 no demuestran que una oferta haya caducado. Confirma el anuncio en una fuente accesible del empleador cuando sea posible, o trátalo como no verificado. Si tu asistente no tiene herramienta de búsqueda, o las fuentes siguen inaccesibles, indica que los resultados pueden estar incompletos. Evita repetir un barrido con la misma configuración después de un error.

Conectar con Antigravity o Claude Desktop

Añade Sweepy al archivo de configuración MCP de tu cliente, llamado mcp_config.json o claude_desktop_config.json según el cliente:

mcp_config.json

{
  "mcpServers": {
    "sweepy": {
      "command": "python",
      "args": [
        "/path/to/sweepy/server.py"
      ]
    }
  }
}

Sustituye /path/to/sweepy por la ruta absoluta a tu carpeta de Sweepy y reinicia el cliente. Una vez registrado, puedes pedir tareas como estas:

• «Crea un perfil de Sweepy para Alex, que busca puestos de redactor técnico en remoto en Nueva York. El currículum está en path/to/resume.pdf.»
• «Ejecuta un barrido con el perfil de redactor y muestra las 5 mejores coincidencias.»
• «Regenera el PDF del último barrido de pedro_writer y guárdalo en el escritorio.»
• «Convierte path/to/notes.md a PDF junto al archivo original.»

Escribir fuera de la carpeta de Sweepy

Cada herramienta de escritura permanece dentro de tu carpeta de Sweepy por defecto. Una petición para guardar en el escritorio falla hasta que configures la variable de entorno SWEEPY_ALLOW_EXTERNAL_WRITES en 1.

Conectar con VS Code

VS Code se conecta a servidores MCP sin extensiones adicionales:

1. Abre la paleta de comandos y ejecuta MCP: Add Server.
2. Elige Command (stdio) y luego escribe python como comando. Añade la ruta absoluta a server.py como argumento.
3. Ponle al servidor el nombre sweepy y elige el destino de la configuración.
4. Confirma que las herramientas de Sweepy aparecen en el panel de chat y llámalas desde ahí.

Para un archivo limitado al espacio de trabajo, añade .vscode/mcp.json a tu proyecto. El formato de VS Code usa un objeto servers de nivel superior:

.vscode/mcp.json

{
  "servers": {
    "sweepy": {
      "type": "stdio",
      "command": "python",
      "args": [
        "/path/to/sweepy/server.py"
      ]
    }
  }
}

Instalar la skill /sweepy

Sweepy incluye una skill /sweepy para Copilot CLI, Claude Code, Antigravity y otras herramientas de línea de comandos que leen skills. Copia la carpeta incluida en el directorio de skills de tu herramienta:

Terminal

cp -r skills/sweepy ~/.claude/skills/sweepy   # adjust to your tool's skills path

Registra el servidor MCP de la sección anterior y reinicia tu herramienta. La skill documenta tres flujos principales:

• Iniciar un nuevo scraping llamando a create_profile y después a run_sweep.
• Ver los resultados de un scraping llamando a get_results para las mejores coincidencias y los playbooks, o a get_jobs para el conjunto completo de fichas.
• Exportar los resultados a un archivo CSV llamando a export_report con formats=["csv"].

La skill también cubre la alternativa para herramientas de línea de comandos sin soporte MCP:

Terminal

sweepy --setup                         # interactive profile wizard
sweepy --profile profiles/your_profile.yaml
sweepy --docx resume.docx              # convert a DOCX resume to PDF
sweepy --convert notes.md              # convert any supported document to PDF

Configurarlo todo con un solo mensaje

Copia este mensaje y pégalo en cualquier sesión de línea de comandos de IA o en el chat de tu IDE:

Configura Sweepy en esta máquina. Sigue estos pasos en orden:

1. Clona o descarga el repositorio de Sweepy.
2. Ejecuta `pip install -r requirements.txt` en la raíz del repositorio.
3. Registra `server.py` en la configuración MCP como servidor stdio. Usa el comando `python` y argumentos que apunten a `server.py`.
4. Copia la carpeta `skills/sweepy` en el directorio de skills de la CLI.

Aprender más patrones de prompting

El archivo AGENTS.md del repositorio documenta la secuencia de herramientas, recomendaciones por herramienta y patrones de prompting. Léelo si quieres una automatización más profunda que la de los flujos de esta página.