Referencia de herramientas MCP de Sweepy

El servidor MCP de server.py expone doce herramientas. La página de integración con MCP cubre el registro y los flujos de trabajo habituales. Esta página enumera cada firma, para que sepas qué hace una llamada antes de que un asistente la ejecute.

Carga útil de respuesta

Cada herramienta devuelve una cadena JSON dentro de un bloque de contenido de texto. Las cargas útiles correctas empiezan por "status": "ok". Las de error empiezan por "status": "error" e incluyen un message que explica la causa. Un barrido fallido también informa de job_id y sweep_status: "failed".

Indicadores de comportamiento

Sweepy declara cuatro anotaciones MCP en cada herramienta. Un host compatible lee estos indicadores antes de invocar la herramienta.

Indicador	Significado
readOnlyHint	La llamada no guarda cambios.
destructiveHint	La llamada puede sobrescribir o eliminar archivos, perfiles o historial.
idempotentHint	Repetir la misma llamada llega al mismo estado final.
openWorldHint	La llamada sale del equipo local.

Herramienta	Solo lectura	Destructiva	Idempotente	Mundo abierto
create_profile	No	Sí	Sí	No
run_sweep	No	Sí	No	Sí
get_sweep_status	No	No	Sí	No
get_jobs	No	No	Sí	No
submit_judgments	No	Sí	Sí	No
import_jobs	No	Sí	Sí	Sí
render_report	No	Sí	Sí	No
get_results	Sí	No	Sí	No
export_report	No	Sí	Sí	No
clear_history	No	Sí	Sí	No
convert_document	No	Sí	Sí	No
convert_docx	No	Sí	Sí	No

Herramientas de perfil y barrido

create_profile

Valida cada motor activo y después escribe el archivo YAML del perfil.

Parámetro	Tipo	Predeterminado	Descripción
name	string	Obligatorio	Nombre completo que se escribe en el perfil.
titles	string array	Obligatorio	Puestos objetivo, como ["Technical Writer", "UX Writer"].
location	string	Obligatorio	Ubicación objetivo, como "New York, NY".
resume_path	string	Obligatorio	Ruta a un currículum en PDF o DOCX.
remote_only	boolean	false	Restringe los resultados a puestos 100 % remotos.
include_hybrid	boolean	true	Mantiene los puestos híbridos en los resultados.
min_salary	integer	0	Salario base anual mínimo. Cero significa sin mínimo.
must_have_skills	string array	null	Términos de habilidades que aumentan la coincidencia.
synonyms	array of arrays	null	Grupos de términos intercambiables, como [["docs-as-code", "documentation as code"]].
platforms	object	null	Interruptores de plataforma que se combinan con el bloque platforms del perfil.
sources_config	object	null	Selección de motores que se combina con el bloque sources. Cada motor se valida antes de escribir.
cache_config	object	null	Ajustes de caché: enabled y ttl_seconds.
orchestrator_config	object	null	Ajustes de tiempo de espera y cortacircuitos.
history_config	object	null	Ajustes entre ejecuciones que controlan qué ofertas omite el barrido.
job_tracking	boolean	true	Añade las columnas de seguimiento de candidaturas al CSV y conserva los valores anteriores.
assessment	string	"agent"	Control del informe. agent bloquea un informe mientras alguna ficha solo tenga solapamiento de palabras clave. keyword permite informes solo con palabras clave.
output_filename	string	null	Ruta YAML personalizada. Por defecto es profiles/{name}_{title}.yaml. Sweepy pasa ambas partes a minúsculas y sustituye cada carácter no alfanumérico por _.

orchestrator_config acepta timeout_per_source_seconds y un objeto circuit_breaker con failure_threshold y cooldown_seconds.

history_config acepta enabled, retention_days, match y path. retention_days vale 4 por defecto, match acepta url o url+role, y path vale ~/.sweepy/history.db por defecto.

Devuelve profile_path, enabled_engines y engines_not_enabled.

run_sweep

Inicia el proceso de cinco etapas y devuelve puntuaciones deterministas de solapamiento de palabras clave. No invoca el criterio de un LLM.

Parámetro	Tipo	Predeterminado	Descripción
profile_path	string	null	Ruta al perfil YAML. Si se omite, Sweepy usa el último perfil guardado y luego el primer perfil convencional del disco: profiles/custom_profile.yaml, profiles/paralegal_nyc.yaml o config.sample.yaml.
deduplicate	boolean	true	Fusiona URL repetidas y ofertas coincidentes de distintas plataformas en esta ejecución.
include_seen	boolean	false	Informa de ofertas de barridos anteriores y actualiza su historial.
wait_seconds	integer	45	Espera máxima antes de que la llamada devuelva el progreso. Limitada al rango de 0 a 600.

Un barrido en vivo suele durar más que el tiempo de espera de un cliente. El proceso cubre esa diferencia ejecutándose en un hilo en segundo plano. Una llamada que devuelve sweep_status: "running" incluye un job_id. Pasa ese id a get_sweep_status hasta que el estado indique completed.

Una segunda llamada con el mismo perfil y las mismas banderas se une al trabajo en curso en lugar de iniciar otro. El proceso del servidor debe seguir en ejecución. Los id de los trabajos de barrido viven en memoria. Un reinicio los borra.

Devuelve una de estas tres cargas útiles:

• En ejecución: sweep_status, job_id, progress con step, total y label, además de elapsed_seconds, debug_log y message.
• Completado: sweep_status, job_id, discovered_count, new_count, previously_seen_count, active_count, top_match, top_roles, reports, job_ids, card_count, assessed_count, assessment_mode, assessment_required, skipped_sources, elapsed_seconds, debug_log y message. top_roles contiene los cinco primeros puestos.
• Fallido: status: "error", message, job_id y sweep_status: "failed".

Una ruta de perfil ausente o ilegible falla antes de que empiece el trabajo. Ese error no tiene job_id.

Cuando todas las ofertas descubiertas son repetidas, previously_seen_count informa del total y active_count informa de cero. Llama a run_sweep con include_seen en true para revisarlas.

get_sweep_status

Espera a un barrido iniciado por run_sweep e informa de su progreso.

Parámetro	Tipo	Predeterminado	Descripción
job_id	string	null	Id del barrido devuelto por run_sweep. Por defecto usa el trabajo más reciente.
wait_seconds	integer	45	Espera máxima antes de que la llamada devuelva el progreso. Limitada al rango de 0 a 600.

Cada respuesta devuelve los mismos campos que el resultado correspondiente de run_sweep. Un job_id ausente o desconocido devuelve un error que remite a run_sweep.

Un barrido terminado también carga sus fichas en la sesión activa, así que get_jobs, submit_judgments y render_report funcionan cuando el estado indica completed.

get_jobs

Devuelve los registros de fichas de la sesión actual, ordenados por solapamiento de palabras clave o por la puntuación de coincidencia enviada.

Parámetro	Tipo	Predeterminado	Descripción
profile_stem	string	null	Identificador del perfil usado para cargar una sesión guardada, como pedro_writer.
results_dir	string	"results"	Carpeta que contiene report_session.json.
limit	integer	null	Número de fichas que se devuelven. Omítelo para devolverlas todas. Sweepy aplica un mínimo de uno.

Devuelve count y jobs. Mientras se ejecuta un barrido, la carga útil añade sweep_status, running_job_id, progress y un message que avisa de que las fichas son anteriores a ese barrido.

submit_judgments

Combina la evaluación de un asistente en una ficha o en un lote completo. Solo cambian los campos que no son nulos.

Parámetro	Tipo	Predeterminado	Descripción
job_id	string	null	Id estable de la ficha, devuelto por run_sweep o get_jobs. Es obligatorio a menos que pases judgments.
match_pct	integer	null	Porcentaje de coincidencia de 0 a 100. Si lo indicas, la etiqueta de la ficha cambia a MATCH.
resume_track	string	null	Canal de currículum que se muestra en la ficha.
resume_color	string	null	Color de la insignia de ese canal.
domain	string	null	Ámbito del puesto que se muestra en la ficha.
summary	string	null	Texto del resumen de la ficha.
requirements	string	null	Texto de los requisitos.
alignment	string	null	Nota que conecta la evidencia del currículum con el puesto.
has_extended_response	boolean	null	Marca una oferta que exige respuestas escritas.
app_format	string	null	Formato de candidatura, como un portal o un correo electrónico.
comp	string	null	Línea de remuneración.
benefits	string	null	Línea de prestaciones.
page_theme	string	null	Tema de la ficha que sustituye al predeterminado.
judgments	array	null	Lista de objetos de evaluación, cada uno con un job_id y cualquiera de los campos anteriores. No lo combines con job_id.

Devuelve la ficha combinada como job. Un lote devuelve applied, jobs y rejected, donde rejected nombra cualquier entrada cuyo id falte en la sesión.

import_jobs

Añade puestos que una investigación independiente encontró y verificó. Sweepy no los confirma por defecto.

Parámetro	Tipo	Predeterminado	Descripción
jobs_json	string	Obligatorio	Array JSON de registros de fichas.
validate	boolean	false	Pasa cada URL por el verificador de enlaces antes de importar.

Devuelve imported y skipped. Una respuesta de límite de tasa o de protección anti-bots cuenta como no verificada, así que no demuestra que una oferta haya caducado.

render_report

Genera el PDF de fichas a partir de la sesión actual.

Parámetro	Tipo	Predeterminado	Descripción
profile_stem	string	null	Identificador del perfil usado para cargar una sesión guardada.
results_dir	string	"results"	Carpeta de la salida predeterminada y de la sesión guardada.
output_filename	string	null	Ruta explícita del PDF. Debe permanecer dentro del espacio de trabajo.
playbook	string	""	Nota de estrategia en texto sin formato. Sweepy escapa & y los signos de menor y mayor, y muestra **negrita** en negrita. Los saltos de línea se convierten en saltos de párrafo. Sweepy guarda el texto con la sesión, así que una llamada posterior sin él reutiliza el texto guardado. Un valor vacío sin texto guardado genera un playbook determinista.

Devuelve pdf_report, pages, card_count y playbook_saved.

Los perfiles usan report.assessment: "agent" por defecto, lo que bloquea la generación mientras alguna ficha solo tenga solapamiento de palabras clave. El error enumera unassessed_job_ids y unassessed_titles para que el asistente sepa qué evaluar. Define report.assessment: "keyword" para permitir informes mixtos, o SWEEPY_REQUIRE_JUDGMENTS=1 para aplicar el control a todos los perfiles y a export_report.

Herramientas de resultados e historial

get_results

Lee del disco el JSON del último barrido. Nunca vuelve a ejecutar el descubrimiento ni la puntuación.

Parámetro	Tipo	Predeterminado	Descripción
profile_stem	string	null	Identificador de perfil que filtra los archivos de resultado. Omítelo para leer el archivo de resultado más reciente.
results_dir	string	"results"	Carpeta que contiene los archivos de resultado.
limit	integer	10	Número de puestos principales que se devuelven. Limitado al rango de 1 a 100.

Devuelve result_file, pdf_report, csv_report, total_roles y top_roles. Cada puesto contiene title, company, location, match_score, match_kind, resume_track, domain, url y playbook.

Las puntuaciones etiquetadas como KEYWORD OVERLAP son valores deterministas de primera pasada. Usa get_jobs y submit_judgments antes de presentarlas como coincidencias.

export_report

Reconstruye los archivos de informe a partir de un JSON de barrido existente.

Parámetro	Tipo	Predeterminado	Descripción
json_source	string	null	Ruta al JSON del barrido. Tiene prioridad sobre profile_stem.
profile_stem	string	null	Identificador de perfil usado para encontrar el JSON más reciente que coincida.
results_dir	string	"results"	Carpeta que contiene los archivos de resultado.
formats	string array	["pdf"]	Formatos de salida: pdf, png, csv o json.
candidate_name	string	"Job Seeker"	Nombre que aparece en la cabecera del PDF.
output_dir	string	null	Carpeta de salida. Por defecto es la carpeta que contiene el JSON de origen.
job_tracking	boolean	null	Añade las columnas de seguimiento de candidaturas a una exportación CSV. Déjalo sin definir para seguir el ajuste export.tracking del perfil.

Devuelve source_file, roles_exported, generated y errors. El objeto generated contiene pdf, pdf_pages, png, csv, csv_rows y json cuando la petición incluye esos formatos. Una petición PNG genera primero el PDF. La salida JSON escribe {stem}_export.json, así que nunca sobrescribe el archivo de barrido que la alimenta.

clear_history

Olvida las ofertas informadas para que el siguiente barrido pueda informarlas de nuevo.

Parámetro	Tipo	Predeterminado	Descripción
profile_path	string	null	Ruta al perfil YAML.
profile_stem	string	null	Identificador del perfil, como pedro_writer.

Devuelve scope, cleared y remaining. Los historiales son por perfil. Llama a la herramienta sin ningún parámetro después de un barrido para borrar el perfil que ese barrido usó. Esa alternativa lee el estado del servidor en ejecución, así que pasa profile_path o profile_stem después de un reinicio.

Herramientas de conversión de documentos

convert_document

Convierte .docx, .doc, .txt, .md o .pdf a PDF. Un origen PDF pasa sin cambios. Los archivos .doc heredados necesitan Microsoft Word.

Parámetro	Tipo	Predeterminado	Descripción
document_path	string	Obligatorio	Ruta del archivo que se va a convertir.
pdf_path	string	null	Ruta de salida. Por defecto es la carpeta de origen.

Devuelve pdf_path y source_path.

convert_docx

Convierte un currículum DOCX a PDF con python-docx y reportlab. Cuando Microsoft Word está disponible, recurre a docx2pdf.

Parámetro	Tipo	Predeterminado	Descripción
docx_path	string	Obligatorio	Ruta del archivo .docx.
pdf_path	string	null	Ruta de salida. Por defecto es la carpeta del DOCX.

Devuelve pdf_path.

Rutas de escritura

Las herramientas que escriben mantienen su salida dentro de la carpeta de Sweepy. Un destino fuera de esa carpeta falla hasta que configures SWEEPY_ALLOW_EXTERNAL_WRITES en 1. Las lecturas aceptan cualquier ruta que el proceso pueda abrir.