Sweepy MCP टूल संदर्भ

server.py में MCP सर्वर बारह टूल देता है। MCP इंटीग्रेशन पेज पंजीकरण और आम वर्कफ़्लो कवर करता है। यह पेज हर signature सूचीबद्ध करता है, ताकि सहायक के चलाने से पहले आप अंदाज़ा लगा सकें कि कोई कॉल क्या करेगा।

प्रतिक्रिया payload

हर टूल टेक्स्ट content block के अंदर JSON स्ट्रिंग लौटाता है। सफल payload "status": "ok" से शुरू होते हैं। विफल payload "status": "error" से शुरू होते हैं और उनमें message होता है जो कारण बताता है। विफल स्वीप job_id और sweep_status: "failed" भी बताता है।

व्यवहार संकेत

Sweepy हर टूल पर चार MCP annotation घोषित करता है। संगत host टूल बुलाने से पहले ये संकेत पढ़ता है।

संकेत	अर्थ
readOnlyHint	कॉल बदलाव स्थायी नहीं करती।
destructiveHint	कॉल फ़ाइलें, प्रोफ़ाइल या इतिहास मिटा या बदल सकती है।
idempotentHint	वही कॉल दोहराने पर वही अंतिम स्थिति बनती है।
openWorldHint	कॉल स्थानीय मशीन से आगे पहुँचती है।

टूल	केवल-पढ़ने	विनाशकारी	idempotent	खुली दुनिया
create_profile	नहीं	हाँ	हाँ	नहीं
run_sweep	नहीं	हाँ	नहीं	हाँ
get_sweep_status	नहीं	नहीं	हाँ	नहीं
get_jobs	नहीं	नहीं	हाँ	नहीं
submit_judgments	नहीं	हाँ	हाँ	नहीं
import_jobs	नहीं	हाँ	हाँ	हाँ
render_report	नहीं	हाँ	हाँ	नहीं
get_results	हाँ	नहीं	हाँ	नहीं
export_report	नहीं	हाँ	हाँ	नहीं
clear_history	नहीं	हाँ	हाँ	नहीं
convert_document	नहीं	हाँ	हाँ	नहीं
convert_docx	नहीं	हाँ	हाँ	नहीं

प्रोफ़ाइल और स्वीप टूल

create_profile

हर चालू इंजन सत्यापित करता है, फिर प्रोफ़ाइल YAML फ़ाइल लिखता है।

पैरामीटर	प्रकार	डिफ़ॉल्ट	विवरण
name	string	आवश्यक	प्रोफ़ाइल में लिखा पूरा नाम।
titles	string array	आवश्यक	लक्ष्य पद नाम, जैसे ["Technical Writer", "UX Writer"]।
location	string	आवश्यक	लक्ष्य स्थान, जैसे "New York, NY"।
resume_path	string	आवश्यक	PDF या DOCX रिज़्यूमे का पथ।
remote_only	boolean	false	नतीजों को 100% रिमोट भूमिकाओं तक सीमित करता है।
include_hybrid	boolean	true	नतीजों में हाइब्रिड भूमिकाएँ रखता है।
min_salary	integer	0	न्यूनतम वार्षिक आधार वेतन। शून्य का मतलब कोई न्यूनतम नहीं।
must_have_skills	string array	null	वे कौशल शब्द जो मिलान बढ़ाते हैं।
synonyms	array of arrays	null	एक-दूसरे के बदले इस्तेमाल योग्य शब्द समूह, जैसे [["docs-as-code", "documentation as code"]]।
platforms	object	null	प्लेटफ़ॉर्म स्विच जो प्रोफ़ाइल के platforms खंड में मिल जाते हैं।
sources_config	object	null	इंजन चयन जो sources खंड में मिल जाता है। लिखने से पहले हर इंजन सत्यापित होता है।
cache_config	object	null	कैश सेटिंग: enabled और ttl_seconds।
orchestrator_config	object	null	टाइमआउट और circuit-breaker सेटिंग।
history_config	object	null	रन-के-बीच सेटिंग जो तय करती हैं कि स्वीप कौन सी पोस्टिंग छोड़े।
job_tracking	boolean	true	CSV में जॉब-ट्रैकिंग कॉलम जोड़ें और पिछले मान आगे ले जाएँ।
assessment	string	"agent"	रिपोर्ट गेट। agent तब रिपोर्ट रोक देता है जब किसी कार्ड पर केवल कीवर्ड मेल हो। keyword केवल-कीवर्ड रिपोर्ट की अनुमति देता है।
output_filename	string	null	कस्टम YAML पथ। डिफ़ॉल्ट profiles/{name}_{title}.yaml है। Sweepy दोनों हिस्सों को छोटे अक्षरों में लाता है और हर गैर-अल्फ़ान्यूमेरिक अक्षर को _ से बदल देता है।

orchestrator_config में timeout_per_source_seconds और एक circuit_breaker ऑब्जेक्ट आता है, जिसमें failure_threshold और cooldown_seconds होते हैं।

history_config में enabled, retention_days, match और path आते हैं। retention_days का डिफ़ॉल्ट 4 है, match url या url+role स्वीकार करता है, और path का डिफ़ॉल्ट ~/.sweepy/history.db है।

profile_path, enabled_engines और engines_not_enabled लौटाता है।

run_sweep

पाँच-चरणीय पाइपलाइन शुरू करता है और नियतात्मक कीवर्ड-मेल स्कोर लौटाता है। यह LLM मूल्यांकन नहीं बुलाता।

पैरामीटर	प्रकार	डिफ़ॉल्ट	विवरण
profile_path	string	null	प्रोफ़ाइल YAML का पथ। छोड़ने पर Sweepy अंतिम सहेजी प्रोफ़ाइल इस्तेमाल करता है, फिर डिस्क पर पहली पारंपरिक प्रोफ़ाइल: profiles/custom_profile.yaml, profiles/paralegal_nyc.yaml या config.sample.yaml।
deduplicate	boolean	true	इस रन के लिए दोहराए गए URL और अलग बोर्ड की मिलती पोस्टिंग मिला देता है।
include_seen	boolean	false	पिछले स्वीप की पोस्टिंग रिपोर्ट करता है और उनका इतिहास ताज़ा करता है।
wait_seconds	integer	45	कॉल के प्रगति लौटाने से पहले सबसे लंबी रुकने की प्रतीक्षा। 0 से 600 की सीमा में बँधी।

चलता स्वीप अक्सर क्लाइंट टाइमआउट से ज़्यादा समय लेता है। पाइपलाइन इस अंतर को पृष्ठभूमि thread पर चलकर संभालता है। जो कॉल sweep_status: "running" लौटाती है, उसमें job_id होता है। उसी id को get_sweep_status में दें, जब तक स्थिति completed न दिखे।

उसी प्रोफ़ाइल और फ़्लैग के साथ दूसरी कॉल नया जॉब शुरू करने के बजाय चल रहे जॉब से जुड़ जाती है। सर्वर प्रोसेस चलती रहनी चाहिए। स्वीप जॉब id मेमोरी में रहते हैं। पुनः आरंभ उन्हें मिटा देता है।

तीन में से एक payload लौटाता है:

• चल रहा: sweep_status, job_id, progress जिसमें step, total और label हैं, साथ में elapsed_seconds, debug_log और message।
• पूरा: 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 और message। top_roles में पहली पाँच भूमिकाएँ रहती हैं।
• विफल: status: "error", message, job_id और sweep_status: "failed"।

गुम या अपठनीय प्रोफ़ाइल पथ जॉब शुरू होने से पहले विफल हो जाता है। उस त्रुटि में job_id नहीं होता।

जब हर मिली पोस्टिंग दोहराई हुई हो, previously_seen_count कुल बताता है और active_count शून्य बताता है। उन्हें देखने के लिए run_sweep को include_seen के साथ true पर बुलाएँ।

get_sweep_status

run_sweep द्वारा शुरू किए स्वीप पर प्रतीक्षा करता है और उसकी प्रगति बताता है।

पैरामीटर	प्रकार	डिफ़ॉल्ट	विवरण
job_id	string	null	run_sweep से स्वीप id। डिफ़ॉल्ट सबसे हाल का जॉब है।
wait_seconds	integer	45	कॉल के प्रगति लौटाने से पहले सबसे लंबी रुकने की प्रतीक्षा। 0 से 600 की सीमा में बँधी।

हर प्रतिक्रिया वही फ़ील्ड लौटाती है जो मिलता run_sweep नतीजा देता है। गुम या अज्ञात job_id ऐसी त्रुटि लौटाता है जो run_sweep की ओर वापस भेजती है।

पूरा हुआ स्वीप अपने कार्ड लाइव सत्र में भी लोड करता है, इसलिए स्थिति completed दिखने के बाद get_jobs, submit_judgments और render_report काम करते हैं।

get_jobs

मौजूदा सत्र में रखे कार्ड रिकॉर्ड लौटाता है, कीवर्ड मेल या जमा किए मिलान स्कोर के क्रम में।

पैरामीटर	प्रकार	डिफ़ॉल्ट	विवरण
profile_stem	string	null	सहेजा सत्र लोड करने के लिए प्रोफ़ाइल पहचानकर्ता, जैसे pedro_writer।
results_dir	string	"results"	वह फ़ोल्डर जिसमें report_session.json है।
limit	integer	null	लौटाने वाले कार्ड की संख्या। हर कार्ड लौटाने के लिए इसे छोड़ दें। Sweepy कम से कम एक लागू करता है।

count और jobs लौटाता है। स्वीप चलते समय payload में sweep_status, running_job_id, progress और एक message जुड़ता है जो चेतावनी देता है कि कार्ड उस स्वीप से पुराने हैं।

submit_judgments

सहायक के मूल्यांकन को एक कार्ड या पूरे बैच में मिला देता है। केवल non-null फ़ील्ड बदलते हैं।

पैरामीटर	प्रकार	डिफ़ॉल्ट	विवरण
job_id	string	null	run_sweep या get_jobs से स्थिर कार्ड id। जब तक आप judgments न दें, यह आवश्यक है।
match_pct	integer	null	0 से 100 तक मिलान प्रतिशत। इसे देने पर कार्ड लेबल MATCH हो जाता है।
resume_track	string	null	कार्ड पर दिखाने वाला रिज़्यूमे ट्रैक।
resume_color	string	null	उस ट्रैक का बैज रंग।
domain	string	null	कार्ड पर दिखने वाला भूमिका डोमेन।
summary	string	null	कार्ड सारांश टेक्स्ट।
requirements	string	null	आवश्यकताओं का टेक्स्ट।
alignment	string	null	वह नोट जो रिज़्यूमे के साक्ष्य को भूमिका से जोड़ता है।
has_extended_response	boolean	null	ऐसी पोस्टिंग चिह्नित करता है जो लिखित उत्तर माँगती है।
app_format	string	null	ऐप फ़ॉर्मैट, जैसे कोई पोर्टल या ईमेल।
comp	string	null	वेतन पंक्ति।
benefits	string	null	लाभ पंक्ति।
page_theme	string	null	कार्ड थीम ओवरराइड।
judgments	array	null	मूल्यांकन ऑब्जेक्ट की सूची, हर एक में job_id और पहले बताए कोई भी फ़ील्ड। इसे job_id के साथ न मिलाएँ।

मिलाया कार्ड job के रूप में लौटाता है। बैच applied, jobs और rejected लौटाता है, जहाँ rejected उन प्रविष्टियों के नाम बताता है जिनकी id सत्र में नहीं है।

import_jobs

ऐसी भूमिकाएँ जोड़ता है जो स्वतंत्र शोध ने खोजी और सत्यापित कीं। Sweepy उन्हें डिफ़ॉल्ट रूप से पुष्ट नहीं करता।

पैरामीटर	प्रकार	डिफ़ॉल्ट	विवरण
jobs_json	string	आवश्यक	कार्ड रिकॉर्ड का JSON array।
validate	boolean	false	आयात से पहले हर URL को लिंक जाँचकर्ता से चलाता है।

imported और skipped लौटाता है। दर सीमा या बॉट-सुरक्षा वाली प्रतिक्रिया असत्यापित गिनी जाती है, इसलिए वह यह साबित नहीं करती कि पोस्टिंग मृत है।

render_report

मौजूदा सत्र से कार्ड PDF रेंडर करता है।

पैरामीटर	प्रकार	डिफ़ॉल्ट	विवरण
profile_stem	string	null	सहेजा सत्र लोड करने के लिए प्रोफ़ाइल पहचानकर्ता।
results_dir	string	"results"	डिफ़ॉल्ट आउटपुट और सहेजे सत्र का फ़ोल्डर।
output_filename	string	null	स्पष्ट PDF पथ। इसे वर्कस्पेस के अंदर रहना चाहिए।
playbook	string	""	सादा-टेक्स्ट रणनीति नोट। Sweepy & और angle bracket को escape करता है, और **bold** को बोल्ड रेंडर करता है। Newline लाइन ब्रेक बन जाते हैं। Sweepy टेक्स्ट सत्र के साथ सहेजता है, इसलिए बाद की कॉल बिना इसे दिए सहेजा टेक्स्ट दोबारा इस्तेमाल करती है। खाली मान और कोई सहेजा टेक्स्ट न होने पर नियतात्मक प्लेबुक बनता है।

pdf_report, pages, card_count और playbook_saved लौटाता है।

प्रोफ़ाइल डिफ़ॉल्ट रूप से report.assessment: "agent" पर रहती हैं, जो तब render रोक देता है जब किसी कार्ड पर केवल कीवर्ड मेल हो। त्रुटि unassessed_job_ids और unassessed_titles सूचीबद्ध करती है ताकि सहायक जान सके कि किसका मूल्यांकन करना है। मिश्रित रिपोर्ट की अनुमति के लिए report.assessment: "keyword" सेट करें, या हर प्रोफ़ाइल और export_report पर गेट लागू करने के लिए SWEEPY_REQUIRE_JUDGMENTS=1 सेट करें।

नतीजे और इतिहास टूल

get_results

डिस्क से नवीनतम स्वीप JSON पढ़ता है। यह कभी डिस्कवरी या स्कोरिंग दोबारा नहीं चलाता।

पैरामीटर	प्रकार	डिफ़ॉल्ट	विवरण
profile_stem	string	null	प्रोफ़ाइल पहचानकर्ता जो नतीजा फ़ाइलें छाँटता है। नवीनतम नतीजा फ़ाइल पढ़ने के लिए इसे छोड़ दें।
results_dir	string	"results"	वह फ़ोल्डर जिसमें नतीजा फ़ाइलें हैं।
limit	integer	10	लौटाने वाली शीर्ष भूमिकाओं की संख्या। 1 से 100 की सीमा में बँधी।

result_file, pdf_report, csv_report, total_roles और top_roles लौटाता है। हर भूमिका में title, company, location, match_score, match_kind, resume_track, domain, url और playbook होते हैं।

KEYWORD OVERLAP लेबल वाले स्कोर नियतात्मक पहले-दौर के मान हैं। उन्हें मिलान के रूप में पेश करने से पहले get_jobs और submit_judgments इस्तेमाल करें।

export_report

मौजूदा स्वीप JSON से रिपोर्ट फ़ाइलें दोबारा बनाता है।

पैरामीटर	प्रकार	डिफ़ॉल्ट	विवरण
json_source	string	null	स्वीप JSON का पथ। यह profile_stem पर भारी पड़ता है।
profile_stem	string	null	प्रोफ़ाइल पहचानकर्ता जो नवीनतम मिलती JSON खोजता है।
results_dir	string	"results"	वह फ़ोल्डर जिसमें नतीजा फ़ाइलें हैं।
formats	string array	["pdf"]	आउटपुट फ़ॉर्मैट: pdf, png, csv या json।
candidate_name	string	"Job Seeker"	PDF हेडर में नाम।
output_dir	string	null	आउटपुट फ़ोल्डर। डिफ़ॉल्ट वह फ़ोल्डर है जिसमें स्रोत JSON है।
job_tracking	boolean	null	CSV निर्यात में जॉब-ट्रैकिंग कॉलम जोड़ें। प्रोफ़ाइल की export.tracking सेटिंग अपनाने के लिए इसे अनसेट छोड़ें।

source_file, roles_exported, generated और errors लौटाता है। generated ऑब्जेक्ट में pdf, pdf_pages, png, csv, csv_rows और json तब होते हैं जब अनुरोध में वे फ़ॉर्मैट हों। PNG अनुरोध पहले PDF रेंडर करता है। JSON आउटपुट {stem}_export.json लिखता है, इसलिए वह उसे पोषण देने वाली स्वीप फ़ाइल कभी नहीं मिटाता।

clear_history

रिपोर्ट की गई पोस्टिंग भुला देता है ताकि अगला स्वीप उन्हें दोबारा रिपोर्ट कर सके।

पैरामीटर	प्रकार	डिफ़ॉल्ट	विवरण
profile_path	string	null	प्रोफ़ाइल YAML का पथ।
profile_stem	string	null	प्रोफ़ाइल पहचानकर्ता, जैसे pedro_writer।

scope, cleared और remaining लौटाता है। इतिहास प्रति प्रोफ़ाइल होते हैं। स्वीप के बाद टूल को बिना किसी पैरामीटर के बुलाएँ ताकि उस स्वीप की प्रोफ़ाइल साफ़ हो जाए। वह fallback चलते सर्वर से स्थिति पढ़ता है, इसलिए पुनः आरंभ के बाद profile_path या profile_stem दें।

दस्तावेज़ रूपांतरण टूल

convert_document

.docx, .doc, .txt, .md या .pdf को PDF में बदलता है। PDF स्रोत जैसा है वैसा ही आगे जाता है। पुरानी .doc फ़ाइलों के लिए Microsoft Word चाहिए।

पैरामीटर	प्रकार	डिफ़ॉल्ट	विवरण
document_path	string	आवश्यक	बदलने वाली फ़ाइल का पथ।
pdf_path	string	null	आउटपुट पथ। डिफ़ॉल्ट स्रोत फ़ोल्डर है।

pdf_path और source_path लौटाता है।

convert_docx

DOCX रिज़्यूमे को python-docx और reportlab से PDF में बदलता है। जब Microsoft Word उपलब्ध हो, यह docx2pdf पर लौट आता है।

पैरामीटर	प्रकार	डिफ़ॉल्ट	विवरण
docx_path	string	आवश्यक	.docx फ़ाइल का पथ।
pdf_path	string	null	आउटपुट पथ। डिफ़ॉल्ट DOCX फ़ोल्डर है।

pdf_path लौटाता है।

लिखने के पथ

जो टूल लिखते हैं, वे अपना आउटपुट Sweepy फ़ोल्डर के अंदर रखते हैं। उस फ़ोल्डर के बाहर का लक्ष्य तब तक विफल रहता है जब तक आप SWEEPY_ALLOW_EXTERNAL_WRITES को 1 पर सेट न करें। पढ़ने वाले टूल वह कोई भी पथ स्वीकार करते हैं जिसे प्रोसेस खोल सके।