Référence des outils MCP de Sweepy

Le serveur MCP dans server.py expose douze outils. La page Intégration MCP couvre l’enregistrement et les flux de travail courants. Cette page liste chaque signature, pour que vous puissiez prévoir l’effet d’un appel avant qu’un assistant l’exécute.

Charge utile de réponse

Chaque outil renvoie une chaîne JSON dans un bloc de contenu texte. Les charges utiles de succès commencent par "status": "ok". Les charges utiles d’échec commencent par "status": "error" et contiennent un message qui explique la cause. Un balayage échoué indique aussi job_id et sweep_status: "failed".

Indications de comportement

Sweepy déclare quatre annotations MCP sur chaque outil. Un hôte compatible lit ces indications avant d’appeler l’outil.

Indication	Signification
readOnlyHint	L’appel ne conserve aucune modification.
destructiveHint	L’appel peut écraser ou supprimer des fichiers, des profils ou l’historique.
idempotentHint	Répéter le même appel mène au même état final.
openWorldHint	L’appel dépasse la machine locale.

Outil	Lecture seule	Destructif	Idempotent	Monde ouvert
create_profile	Non	Oui	Oui	Non
run_sweep	Non	Oui	Non	Oui
get_sweep_status	Non	Non	Oui	Non
get_jobs	Non	Non	Oui	Non
submit_judgments	Non	Oui	Oui	Non
import_jobs	Non	Oui	Oui	Oui
render_report	Non	Oui	Oui	Non
get_results	Oui	Non	Oui	Non
export_report	Non	Oui	Oui	Non
clear_history	Non	Oui	Oui	Non
convert_document	Non	Oui	Oui	Non
convert_docx	Non	Oui	Oui	Non

Outils de profil et de balayage

create_profile

Valide chaque moteur activé, puis écrit le fichier de profil YAML.

Paramètre	Type	Valeur par défaut	Description
name	string	Obligatoire	Nom complet écrit dans le profil.
titles	tableau de chaînes	Obligatoire	Intitulés de poste ciblés, comme ["Technical Writer", "UX Writer"].
location	string	Obligatoire	Lieu ciblé, comme "New York, NY".
resume_path	string	Obligatoire	Chemin vers un CV PDF ou DOCX.
remote_only	boolean	false	Limite les résultats aux postes 100 % en télétravail.
include_hybrid	boolean	true	Conserve les postes hybrides dans les résultats.
min_salary	integer	0	Salaire de base annuel minimal. Zéro signifie aucun minimum.
must_have_skills	tableau de chaînes	null	Termes de compétences qui renforcent la correspondance.
synonyms	tableau de tableaux	null	Groupes de termes interchangeables, comme [["docs-as-code", "documentation as code"]].
platforms	objet	null	Interrupteurs de plateformes fusionnés dans le bloc platforms du profil.
sources_config	objet	null	Sélection de moteurs fusionnée dans le bloc sources. Chaque moteur est validé avant l’écriture.
cache_config	objet	null	Paramètres de cache : enabled et ttl_seconds.
orchestrator_config	objet	null	Paramètres de délai d’attente et de coupe-circuit.
history_config	objet	null	Paramètres inter-exécutions qui décident quelles offres le balayage ignore.
job_tracking	boolean	true	Ajoute les colonnes de suivi au CSV et reporte les valeurs antérieures.
assessment	string	"agent"	Verrou du rapport. agent bloque un rapport tant qu’une fiche repose sur le seul chevauchement de mots-clés. keyword autorise les rapports basés uniquement sur les mots-clés.
output_filename	string	null	Chemin YAML personnalisé. Par défaut profiles/{name}_{title}.yaml. Sweepy passe les deux parties en minuscules et remplace chaque caractère non alphanumérique par _.

orchestrator_config prend timeout_per_source_seconds et un objet circuit_breaker avec failure_threshold et cooldown_seconds.

history_config prend enabled, retention_days, match et path. retention_days vaut 4 par défaut, match accepte url ou url+role, et path vaut ~/.sweepy/history.db par défaut.

Renvoie profile_path, enabled_engines et engines_not_enabled.

run_sweep

Démarre le pipeline en cinq étapes et renvoie des scores déterministes de chevauchement de mots-clés. Il n’appelle aucune évaluation LLM.

Paramètre	Type	Valeur par défaut	Description
profile_path	string	null	Chemin du profil YAML. Quand il est omis, Sweepy utilise le dernier profil enregistré, puis le premier profil conventionnel sur le disque : profiles/custom_profile.yaml, profiles/paralegal_nyc.yaml ou config.sample.yaml.
deduplicate	boolean	true	Fusionne les URL répétées et les offres identiques venant de sites différents pour cette exécution.
include_seen	boolean	false	Rapporte les offres des balayages antérieurs et rafraîchit leur historique.
wait_seconds	integer	45	Attente bloquante maximale avant que l’appel renvoie la progression. Bornée entre 0 et 600.

Un balayage en cours dure souvent plus longtemps que le délai d’un client. Le pipeline comble cet écart en tournant sur un thread d’arrière-plan. Un appel qui renvoie sweep_status: "running" contient un job_id. Passez cet identifiant à get_sweep_status jusqu’à ce que le statut indique completed.

Un second appel avec le même profil et les mêmes options se rattache à la tâche en cours au lieu d’en démarrer une autre. Le processus serveur doit rester actif. Les identifiants de tâche vivent en mémoire. Un redémarrage les efface.

Renvoie l’une de trois charges utiles :

• En cours : sweep_status, job_id, progress avec step, total et label, plus elapsed_seconds, debug_log et message.
• Terminé : 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 et message. top_roles contient les cinq premiers postes.
• Échoué : status: "error", message, job_id et sweep_status: "failed".

Un chemin de profil manquant ou illisible échoue avant le démarrage d’une tâche. Cette erreur n’a pas de job_id.

Quand chaque offre découverte est une répétition, previously_seen_count indique le total et active_count indique zéro. Appelez run_sweep avec include_seen défini à true pour les examiner.

get_sweep_status

Attend un balayage démarré par run_sweep et rapporte sa progression.

Paramètre	Type	Valeur par défaut	Description
job_id	string	null	Identifiant de balayage renvoyé par run_sweep. Par défaut la tâche la plus récente.
wait_seconds	integer	45	Attente bloquante maximale avant que l’appel renvoie la progression. Bornée entre 0 et 600.

Chaque réponse renvoie les mêmes champs que le résultat run_sweep correspondant. Un job_id manquant ou inconnu renvoie une erreur qui renvoie vers run_sweep.

Un balayage terminé charge aussi ses fiches dans la session active, donc get_jobs, submit_judgments et render_report fonctionnent dès que le statut indique completed.

get_jobs

Renvoie les fiches de la session courante, classées par chevauchement de mots-clés ou par score de correspondance soumis.

Paramètre	Type	Valeur par défaut	Description
profile_stem	string	null	Identifiant de profil utilisé pour charger une session enregistrée, comme pedro_writer.
results_dir	string	"results"	Dossier qui contient report_session.json.
limit	integer	null	Nombre de fiches à renvoyer. Omettez-le pour renvoyer toutes les fiches. Sweepy impose un minimum de un.

Renvoie count et jobs. Pendant un balayage, la charge utile ajoute sweep_status, running_job_id, progress et un message qui avertit que les fiches précèdent ce balayage.

submit_judgments

Fusionne l’évaluation d’un assistant dans une fiche ou dans tout un lot. Seuls les champs non nuls changent.

Paramètre	Type	Valeur par défaut	Description
job_id	string	null	Identifiant stable de fiche renvoyé par run_sweep ou get_jobs. Obligatoire sauf si vous passez judgments.
match_pct	integer	null	Pourcentage de compatibilité de 0 à 100. Le fournir change l’étiquette de la fiche en MATCH.
resume_track	string	null	Parcours de CV à afficher sur la fiche.
resume_color	string	null	Couleur du badge de ce parcours.
domain	string	null	Domaine du poste affiché sur la fiche.
summary	string	null	Texte du résumé de la fiche.
requirements	string	null	Texte des exigences.
alignment	string	null	Note qui relie les éléments du CV au poste.
has_extended_response	boolean	null	Signale une offre qui exige des réponses rédigées.
app_format	string	null	Format de candidature, comme un portail ou un courriel.
comp	string	null	Ligne de rémunération.
benefits	string	null	Ligne des avantages.
page_theme	string	null	Remplacement du thème de la fiche.
judgments	tableau	null	Liste d’objets d’évaluation, chacun avec un job_id plus n’importe quel champ précédent. Ne la combinez pas avec job_id.

Renvoie la fiche fusionnée sous job. Un lot renvoie applied, jobs et rejected, où rejected nomme toute entrée dont l’identifiant manque dans la session.

import_jobs

Ajoute des postes qu’une recherche indépendante a trouvés et vérifiés. Sweepy ne les confirme pas par défaut.

Paramètre	Type	Valeur par défaut	Description
jobs_json	string	Obligatoire	Tableau JSON d’enregistrements de fiches.
validate	boolean	false	Fait passer chaque URL par le vérificateur de liens avant l’import.

Renvoie imported et skipped. Une réponse de limite de débit ou de protection anti-bot compte comme non vérifiée, donc elle ne prouve pas qu’une offre est morte.

render_report

Effectue le rendu du PDF de fiches depuis la session courante.

Paramètre	Type	Valeur par défaut	Description
profile_stem	string	null	Identifiant de profil utilisé pour charger une session enregistrée.
results_dir	string	"results"	Dossier de la sortie par défaut et de la session enregistrée.
output_filename	string	null	Chemin PDF explicite. Il doit rester dans l’espace de travail.
playbook	string	""	Note de stratégie en texte brut. Sweepy échappe & et les chevrons, et il rend **bold** en gras. Les sauts de ligne deviennent des retours à la ligne. Sweepy enregistre le texte avec la session, donc un appel ultérieur sans ce texte réutilise le texte enregistré. Une valeur vide sans texte enregistré génère un playbook déterministe.

Renvoie pdf_report, pages, card_count et playbook_saved.

Les profils utilisent report.assessment: "agent" par défaut, ce qui bloque le rendu tant qu’une fiche ne contient que le chevauchement de mots-clés. L’erreur liste unassessed_job_ids et unassessed_titles pour que l’assistant sache quoi évaluer. Définissez report.assessment: "keyword" pour autoriser les rapports mixtes, ou SWEEPY_REQUIRE_JUDGMENTS=1 pour appliquer le verrou à tous les profils et à export_report.

Outils de résultats et d’historique

get_results

Lit le dernier JSON de balayage sur le disque. Il ne relance jamais la découverte ni la notation.

Paramètre	Type	Valeur par défaut	Description
profile_stem	string	null	Identifiant de profil qui filtre les fichiers de résultat. Omettez-le pour lire le fichier de résultat le plus récent.
results_dir	string	"results"	Dossier qui contient les fichiers de résultat.
limit	integer	10	Nombre de meilleurs postes à renvoyer. Borné entre 1 et 100.

Renvoie result_file, pdf_report, csv_report, total_roles et top_roles. Chaque poste contient title, company, location, match_score, match_kind, resume_track, domain, url et playbook.

Les scores étiquetés KEYWORD OVERLAP sont des valeurs déterministes de premier passage. Utilisez get_jobs et submit_judgments avant de les présenter comme des correspondances.

export_report

Reconstruit des fichiers de rapport depuis un JSON de balayage existant.

Paramètre	Type	Valeur par défaut	Description
json_source	string	null	Chemin du JSON de balayage. Il prend le pas sur profile_stem.
profile_stem	string	null	Identifiant de profil utilisé pour trouver le dernier JSON correspondant.
results_dir	string	"results"	Dossier qui contient les fichiers de résultat.
formats	tableau de chaînes	["pdf"]	Formats de sortie : pdf, png, csv ou json.
candidate_name	string	"Job Seeker"	Nom dans l’en-tête du PDF.
output_dir	string	null	Dossier de sortie. Par défaut le dossier qui contient le JSON source.
job_tracking	boolean	null	Ajoute les colonnes de suivi à un export CSV. Laissez vide pour suivre le paramètre export.tracking du profil.

Renvoie source_file, roles_exported, generated et errors. L’objet generated contient pdf, pdf_pages, png, csv, csv_rows et json quand la requête inclut ces formats. Une demande PNG effectue d’abord le rendu du PDF. La sortie JSON écrit {stem}_export.json, donc elle n’écrase jamais le fichier de balayage qui l’alimente.

clear_history

Oublie les offres rapportées pour que le balayage suivant puisse les rapporter à nouveau.

Paramètre	Type	Valeur par défaut	Description
profile_path	string	null	Chemin du profil YAML.
profile_stem	string	null	Identifiant de profil, comme pedro_writer.

Renvoie scope, cleared et remaining. Les historiques sont propres à chaque profil. Appelez l’outil sans aucun paramètre après un balayage pour vider le profil utilisé par ce balayage. Ce repli lit l’état du serveur en cours, donc passez profile_path ou profile_stem après un redémarrage.

Outils de conversion de documents

convert_document

Convertit .docx, .doc, .txt, .md ou .pdf en PDF. Un fichier source PDF passe sans modification. Les fichiers .doc hérités exigent Microsoft Word.

Paramètre	Type	Valeur par défaut	Description
document_path	string	Obligatoire	Chemin du fichier à convertir.
pdf_path	string	null	Chemin de sortie. Par défaut le dossier source.

Renvoie pdf_path et source_path.

convert_docx

Convertit un CV DOCX en PDF avec python-docx et reportlab. Quand Microsoft Word est disponible, il se rabat sur docx2pdf.

Paramètre	Type	Valeur par défaut	Description
docx_path	string	Obligatoire	Chemin du fichier .docx.
pdf_path	string	null	Chemin de sortie. Par défaut le dossier du DOCX.

Renvoie pdf_path.

Chemins d’écriture

Les outils qui écrivent gardent leur sortie dans le dossier Sweepy. Une cible hors de ce dossier échoue tant que vous ne définissez pas SWEEPY_ALLOW_EXTERNAL_WRITES à 1. Les lectures acceptent tout chemin que le processus peut ouvrir.