مرجع أدوات MCP في Sweepy

يعرض خادم MCP في server.py اثنتي عشرة أداة. وتغطي صفحة دمج MCP التسجيل وسير العمل الشائع. وتسرد هذه الصفحة كل توقيع، لتتوقع ما يفعله الاستدعاء قبل أن يشغّله مساعد.

حمولة الاستجابة

تعيد كل أداة سلسلة JSON داخل كتلة محتوى نصية. وتبدأ حمولات النجاح بـ "status": "ok". وتبدأ حمولات الفشل بـ "status": "error" وتتضمن message يشرح السبب. ويبلّغ المسح الفاشل أيضًا عن job_id وsweep_status: "failed".

تلميحات السلوك

يعلن Sweepy أربع تعليقات MCP على كل أداة. ويقرأ المضيف المتوافق هذه التلميحات قبل أن يستدعي الأداة.

التلميح	المعنى
readOnlyHint	لا يحفظ الاستدعاء أي تغييرات.
destructiveHint	قد يكتب الاستدعاء فوق ملفات أو ملفات تعريفية أو سجل، أو يحذفها.
idempotentHint	تكرار الاستدعاء نفسه يصل إلى الحالة النهائية نفسها.
openWorldHint	يتجاوز الاستدعاء الجهاز المحلي.

الأداة	قراءة فقط	تدميرية	تكرارية	عالم مفتوح
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	إعدادات المهلة وقاطع الدائرة.
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	يدمج الروابط المكررة والإعلانات المطابقة من منصات مختلفة لهذا التشغيل.
include_seen	boolean	false	يبلّغ عن إعلانات من عمليات مسح سابقة ويحدّث سجلها.
wait_seconds	integer	45	أطول انتظار حاجز قبل أن يعيد الاستدعاء تقدمًا. ويُقيَّد في النطاق من 0 إلى 600.

غالبًا يعمل المسح الحي أطول من مهلة العميل. ويتعامل خط المعالجة مع تلك الفجوة بالعمل في خيط خلفي. والاستدعاء الذي يعيد sweep_status: "running" يتضمن job_id. ومرّر ذلك المعرّف إلى get_sweep_status إلى أن تصبح الحالة completed.

وينضم استدعاء ثانٍ بالملف التعريفي والمفاتيح نفسها إلى المهمة الجارية بدلًا من بدء أخرى. ويجب أن تبقى عملية الخادم قيد التشغيل. فمعرّفات مهام المسح تعيش في الذاكرة. وتزيلها إعادة التشغيل.

ويعيد واحدة من ثلاث حمولات:

• قيد التشغيل: 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. والقيمة الافتراضية أحدث مهمة.
wait_seconds	integer	45	أطول انتظار حاجز قبل أن يعيد الاستدعاء تقدمًا. ويُقيَّد في النطاق من 0 إلى 600.

تعيد كل استجابة الحقول نفسها التي تعيدها نتيجة run_sweep المطابقة. ويعيد job_id مفقود أو غير معروف خطأً يوجهك مرة أخرى إلى run_sweep.

ويحمّل المسح المنتهي بطاقاته أيضًا في الجلسة الحية، فتعمل get_jobs وsubmit_judgments وrender_report بمجرد أن تصبح الحالة completed.

get_jobs

يعيد سجلات البطاقات المحفوظة في الجلسة الحالية، مرتبة حسب تداخل الكلمات المفتاحية أو درجة التطابق المرسلة.

المعامل	النوع	الافتراضي	الوصف
profile_stem	string	null	معرّف الملف التعريفي المستخدم لتحميل جلسة محفوظة، مثل pedro_writer.
results_dir	string	"results"	المجلد الذي يحتوي report_session.json.
limit	integer	null	عدد البطاقات المعادة. احذفه لإعادة كل بطاقة. ويفرض Sweepy حدًا أدنى قدره واحد.

ويعيد count وjobs. وأثناء تشغيل مسح، تضيف الحمولة sweep_status وrunning_job_id وprogress وmessage يحذر من أن البطاقات تسبق ذلك المسح.

submit_judgments

يدمج تقييم المساعد في بطاقة واحدة أو دفعة كاملة. ولا تتغير إلا الحقول غير الفارغة.

المعامل	النوع	الافتراضي	الوصف
job_id	string	null	معرّف البطاقة الثابت من run_sweep أو get_jobs. مطلوب إلا إذا مرّرت 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 أي إدخال معرّفه مفقود من الجلسة.

import_jobs

يضيف وظائف وجدها بحث مستقل وتحقّق منها. ولا يؤكدها Sweepy افتراضيًا.

المعامل	النوع	الافتراضي	الوصف
jobs_json	string	مطلوب	مصفوفة JSON من سجلات البطاقات.
validate	boolean	false	يمرّر كل رابط عبر مدقق الروابط قبل الاستيراد.

ويعيد imported وskipped. وتُحتسب استجابة حد الطلبات أو حجب الروبوت كغير متحققة، فلا تثبت أن إعلانًا ميت.

render_report

يعرض تقرير البطاقات بصيغة PDF من الجلسة الحالية.

المعامل	النوع	الافتراضي	الوصف
profile_stem	string	null	معرّف الملف التعريفي المستخدم لتحميل جلسة محفوظة.
results_dir	string	"results"	مجلد الإخراج الافتراضي والجلسة المحفوظة.
output_filename	string	null	مسار PDF صريح. ويجب أن يبقى داخل مساحة العمل.
playbook	string	""	ملاحظة استراتيجية بنص عادي. ويهرّب Sweepy الرمز & والأقواس الزاوية، ويعرض **bold** غامقًا. وتتحول الأسطر الجديدة إلى فواصل أسطر. ويحفظ Sweepy النص مع الجلسة، فيعيد استدعاء لاحق دون نص استخدام النص المحفوظ. والقيمة الفارغة دون نص محفوظ تولّد دليل استراتيجية حتميًا.

ويعيد pdf_report وpages وcard_count وplaybook_saved.

تأخذ الملفات التعريفية القيمة report.assessment: "agent" افتراضيًا، وهي تمنع العرض ما دامت أي بطاقة تحمل تداخل كلمات مفتاحية وحده. ويسرد الخطأ unassessed_job_ids وunassessed_titles ليعرف المساعد ما يجب تقييمه. اضبط report.assessment: "keyword" للسماح بتقارير مختلطة، أو SWEEPY_REQUIRE_JUDGMENTS=1 لتطبيق البوابة على كل ملف تعريفي وعلى export_report.

أدوات النتائج والسجل

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. والسجلات لكل ملف تعريفي. واستدعِ الأداة دون أي معامل بعد مسح لمسح سجل الملف التعريفي الذي استخدمه ذلك المسح. ويقرأ ذلك البديل حالة الخادم الجاري، فمرّر 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 إلى PDF بـ python-docx وreportlab. وعندما يتوفر Microsoft Word، يعود إلى docx2pdf.

المعامل	النوع	الافتراضي	الوصف
docx_path	string	مطلوب	مسار ملف .docx.
pdf_path	string	null	مسار الإخراج. والقيمة الافتراضية مجلد DOCX.

ويعيد pdf_path.

مسارات الكتابة

تُبقي الأدوات التي تكتب مخرجاتها داخل مجلد Sweepy. ويفشل أي هدف خارج ذلك المجلد إلى أن تضبط SWEEPY_ALLOW_EXTERNAL_WRITES على 1. وتقبل القراءات أي مسار تستطيع العملية فتحه.