دوز مباشرة للمحتوى الرئيسي
دروس فالذكاء الاصطناعي

بني مولّد وثائق تعليمية متعدد البلدان باستعمال Yowes وMCP

تعلّم كيفاش تثبّت Yowes، تربط خادم MCP ديالو بلا واجهة تشغيل ببيئة تشغيل الوكيل، تكتاشف البلدان والمدارس المدعومة، وتولّد وثائق تعليمية بصيغة PNG باستعمال Python ولا باستدعاءات مباشرة للأدوات.

حوالي 19 دقايق ديال القراية
بني مولّد وثائق تعليمية متعدد البلدان باستعمال Yowes وMCP

Yowes هو تطبيق Python محمول كيولّد وثائق مرتبطة بالأساتذة على شكل ملفات PNG بدقّة عالية. خادم Model Context Protocol (MCP) ديالو، اللي كيخدم بلا واجهة، كيكشف توليد الوثائق عبر stdio، وهادشي كيخليه قابل للاستعمال من بيئات تشغيل الوكلاء بحال Claude Desktop وHermes وعملا MCP آخرين.

المشروع كيدعم 13 بلاد، وأنواع وثائق خاصة بكل بلاد، وخطوط وصور بروفايل مضمّنة، ومعطيات المدارس اللي فيها العناوين ومعلومات التواصل. هاد الدليل كيدوز على التثبيت، إعداد الخادم، استعمال أدوات MCP، الدمج مع Python، وإمكانيات التوسيع.

شنو كيدير Yowes

Yowes كينشئ وثائق محلية ديال الأساتذة انطلاقاً من بروفايل الأستاذ ومدرسة مختارة. على حساب البلاد، المخرجات المتاحة كتقدر تشمل رسائل التوظيف، بطاقات الأساتذة، رخص التدريس، كشوفات الأجرة، بطاقات المدارس، العقود، الشهادات، وصيغ وثائق أخرى.

الملفات اللي كتتولّد كيتحفظو كصور PNG. التطبيق فيه خطوط DejaVu Sans وصور بروفايل مضمّنة فالحزمة، وبالتالي ما كيعتمدش على خطوط النظام ولا على موارد صور خارجية وقت التشغيل.

البلدان المدعومة

رموز البلدان وأنواع الوثائق المتاحة كتشمل:

  • المملكة المتحدة: رسائل التوظيف، بطاقات الأساتذة، ورخص التدريس.
  • الولايات المتحدة: رسائل التوظيف، بطاقات الأساتذة، ورخص التدريس.
  • فرنسا: تصريحات الالتحاق، لقطات شاشة iProf، مقتطفات من الأنظمة الداخلية، وشهادات التدريس.
  • هولندا: عقود التوظيف، تسجيلات الأساتذة، تصريحات DUO، وبطاقات المدارس.
  • إندونيسيا: كشوفات الأجرة، رسائل تجربة التدريس، بطاقات NUPTK، ورسائل التعيين.
  • أستراليا: رسائل مدرسية موقّعة، بطاقات المدارس، ورخص التدريس.
  • كندا: بطاقات OCT، رخص التدريس، ورسائل مدرسية موقّعة.
  • إسبانيا: بطاقات التدريس، رسائل مدرسية موقّعة، وعقود التوظيف.
  • الأرجنتين: كشوفات الأجرة، شواهد التوظيف، ورسائل مدرسية موقّعة.
  • سلوفاكيا: كشوفات الأجرة، رسائل التوظيف، ورسائل مدرسية موقّعة.
  • المكسيك: بطاقات التدريس، رسائل مدرسية موقّعة، وشواهد التوظيف.
  • الفلبين: بطاقات التدريس، شواهد التوظيف، ورخص التدريس.
  • تايلاند: كشوفات الأجرة ورسائل التوظيف.

استعمل هاد الوثائق غير فالاختبارات المشروعة، والعروض التوضيحية، ولا المساطر الإدارية المأذون بها. ما خاصش الوثائق المولّدة تتقدّم على أساس أنها مؤهلات رسمية إلا إلا كانت صادرة ومصادق عليها من طرف المؤسسة المعنية.

المتطلبات

Yowes كيحتاج Python 3.10 ولا أحدث. الاعتماديات الرئيسية ديالو، Pillow وmcp، كتتثبت أوتوماتيكياً ملي كتثبت الحزمة.

المشروع كيدعم Windows وLinux وmacOS. وحيت الخطوط والصور مضمّنين، فالتطبيق المعبّأ مصمّم باش يكون محمول.

تثبيت Yowes

التثبيت من wheel

إلا كان عندك wheel مبني فالمجلد dist، ثبّتو بهاد الأمر:

بطاقة أستاذ من الولايات المتحدة

pip install dist/yowes_doc_generator-0.1.0-py3-none-any.whl

التثبيت من المصدر

للتطوير ولا التجارب المحلية، ثبّت المشروع فالوضع القابل للتعديل:

pip install -e .

التشغيل باستعمال uv

تقدر حتى تشغّل المشروع عبر uv:

uvx --from . yowes-mcp

التحقق من الموارد المضمّنة

من بعد التثبيت، تأكد باللي مساعدات الخط المضمّن وصورة البروفايل كيتحمّلو مزيان:

python -c "from countries.utils import load_font, get_profile_photo; print(load_font(30).getname()); print(get_profile_photo((280,340), person_id='x', gender='Male') is not None)"

التشغيل الناجح كيبيّن خط DejaVu Sans وكيرجع True لصورة البروفايل المضمّنة.

ربط خادم MCP

Yowes كيتواصل عبر MCP باستعمال stdio. شغّل الأمر المثبّت بهاد الشكل:

yowes-mcp

وبديل آخر، ملي كتخدم مباشرة من شجرة المصدر، هو:

رسالة من الولايات المتحدة

python mcp_server.py

العملية كتسنى طلبات MCP فالإدخال القياسي وكتكتب الردود فالإخراج القياسي. ما تصمّماتش باش تخدم بحال تطبيق تفاعلي فالطرفية.

تسجيل Yowes فعميل MCP

وجّه بيئة تشغيل الوكيل المتوافقة مع MCP للملف التنفيذي:

{
  "mcpServers": {
    "yowes": {
      "command": "yowes-mcp",
      "args": []
    }
  }
}

إلا ما كانش الأمر متاح فـPATH ديالك، استعمل المسار المطلق ديال Python واستدعِ وحدة الخادم:

{
  "mcpServers": {
    "yowes": {
      "command": "/path/to/python",
      "args": ["-m", "mcp_server"]
    }
  }
}

استكشاف أدوات MCP المتاحة

الخادم كيوفّر ثلاثة أدوات أساسية:

  • list_countries_tool كيعرض رموز البلدان، الأسماء اللي كتبان، وأنواع الوثائق.
  • list_schools(country) كيعرض المدارس ديال بلاد مختارة.
  • generate_documents(...) كيرسم وثيقة وحدة ولا أكثر وكيرجع المسارات ديال الملفات.

عرض البلدان

عيّط على list_countries_tool بلا معاملات. الرد فيه عنصر نتيجة واحد لكل بلاد، بقيم بحال code وname وdocument_types. وحيت اللائحة مقسّمة على عناصر محتوى متعددة ديال MCP، دُزّ على مجموعة content اللي كترجع باش تفحص كل بلاد.

عرض المدارس

مرّر رمز البلاد إلى list_schools:

{
  "country": "us"
}

بطاقة تعريف أستاذ بريطاني

كل نتيجة ديال المدرسة تقدر تتضمن السمية ديالها، العنوان، المدينة، الرمز البريدي، الولاية، رقم الهاتف، ومعلومات هيئة التعليم المحلية. استعمل السمية الكاملة ولا الجزئية ديال المدرسة اللي رجّعاتها هاد الأداة ملي كتولّد الوثائق.

توليد الوثائق

الأداة generate_documents كتحتاج للبلد، سميّة الأستاذ، المدرسة، المنصب، وتاريخ الازدياد. وتقدر اختيارياً تحدد الجنس، أنواع الوثائق، ومجلد الإخراج.

مثال ديال الطلب

{
  "country": "us",
  "first_name": "John",
  "last_name": "Smith",
  "school_name": "Valley High",
  "position": "Head of Science Department",
  "date_of_birth": "12/05/1988",
  "gender": "Male",
  "document_types": ["employment_letter", "teacher_id"],
  "output_dir": "output"
}

القيمة ديال gender تقدر تكون Random، أو Male، أو Female. وهي اللي كتتحكم فاختيار الصور من مجموعة صور البروفايلات المرفقة. إلا تحيدات document_types، Yowes كيولّد جميع أنواع الوثائق المتاحة للبلد المختار. مجلد الإخراج الافتراضي هو output/.

الاستجابة الناجحة كتتضمن البلد والمدرسة المختارين، أنواع الوثائق، المسارات ديال الملفات المولّدة، العدد، ومجلد الإخراج. مسارات PNG اللي كترجع هي مسارات مطلقة.

مثلاً، الوثائق المولّدة ديال الولايات المتحدة تقدر تشبه الأمثلة التالية:

بطاقة تعريف أستاذ أمريكيرسالة توظيف أمريكية

استعمال Yowes من Python

التطبيقات تقدر تشغّل خادم MCP وتستعمل الأدوات ديالو عبر عميل MCP ديال Python. ثبّت تبعية العميل إلا كانت ضرورية:

pip install mcp

المثال التالي كيهيّئ جلسة stdio، كيعرض البلدان، وكيولّد وثائق أمريكية:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command="yowes-mcp", args=[])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            countries = await session.call_tool(
                "list_countries_tool", {}
            )
            for item in countries.content:
                print(item.text)

            result = await session.call_tool(
                "generate_documents",
                {
                    "country": "us",
                    "first_name": "John",
                    "last_name": "Smith",
                    "school_name": "Valley High",
                    "position": "Head of Science Department",
                    "date_of_birth": "12/05/1988",
                    "gender": "Male"
                }
            )
            print(result.content[0].text)

asyncio.run(main())

حيت الردود ديال اللوائح مقسّمة لعناصر محتوى منفصلة، خاصك تفحص كل عنصر فـ countries.content وما تفترضش باللي اللائحة كاملة غتكون فـ قيمة وحدة ديال الرد.

سير عمل عملي للوكيل

رسالة بريطانية

  1. عيّط على list_countries_tool باش تكتاشف رموز البلدان وأنواع الوثائق الصالحة.
  2. عيّط على list_schools باستعمال رمز البلد المختار.
  3. اختار مدرسة من البيانات اللي رجعات.
  4. عيّط على generate_documents بمعلومات الأستاذ والمدرسة المصرّح باستعمالها.
  5. قرا مسارات PNG اللي رجعات وعالج الملفات فالتطبيق ديالك.

هاد التسلسل كيتفادى التخمين ديال رموز البلدان، أسامي المدارس، ولا معرّفات أنواع الوثائق.

نصائح متقدمة

اختار غير المخرجات المطلوبة

مرّر مصفوفة document_types ملي كتحتاج غير لجزء من الوثائق المتاحة فبلد معيّن. هاد الشي كينقص من التصيير غير الضروري وكيخلي مجلد الإخراج مركز على الملفات المطلوبة.

اختار صورة بروفايل مستقرة

Yowes كيستعمل اختيار مبني على الهاش باش يخلي صور البروفايل متناسقة لنفس الشخص. تزويد النظام بهوية مستقرة للشخص وبجنس محدد كيساعد يعطي نتائج متوقعة مع الاختيار من مجموعة الصور المناسبة المرفقة.

استعمل مجلد إخراج مخصص

عيّن output_dir باش تنظم الصور المولّدة حسب المشروع، تشغيل الاختبار، ولا البلد. المسارات النسبية كيتحلّو انطلاقاً من مجلد العمل ديال خادم MCP.

شغّل الواجهة الرسومية القديمة عند الحاجة

المشروع فيه حتى واجهة اختيارية بـ CustomTkinter كتشارك منطق التوليد الأساسي:

python main_gui.py

فـ Windows، المستودع كيوفّر حتى run.bat، اللي كيضبط TCL_LIBRARY. خادم MCP باقي هو الواجهة الأساسية اللي خدامة بلا واجهة رسومية وما معتمدش عليها.

وسّع Yowes ببلد جديد

باش تزيد بلد، صايب countries/<code>/__init__.py وعرّف كلاس كيورث من countries.base.CountryGenerator. طبّق الميثودات المطلوبة:

  • get_country_name
  • get_country_code
  • get_schools_data
  • get_first_names
  • get_last_names
  • get_positions
  • get_document_types
  • generate_document

سجّل المولّد فـ countries/__init__.py باستعمال register_country("<code>", <Name>Generator). من بعد التسجيل، أدوات MCP ديال البلدان والمدارس تقدر تكتاشفو أوتوماتيكياً. إلا بغيتي الواجهة الرسومية تعرض تسمية مخصصة، حدّث منطق لائحة البلدان وتغيير البلد فـ main_gui.py.

الخلاصة

Yowes كيجمع مولّدات ديال الوثائق الخاصة بكل بلاد، والموارد المجمّعة، وسيرفر MCP stdio فمسار عمل قابل للنقل. ركّبو ببايثون، واكتاشف البلدان والمدارس المتاحة عبر MCP، وولّد مخرجات PNG اللي اخترتي، ودمج هاد العملية فوكيل ولا فواحد تطبيق ديال بايثون. ولأغراض التطوير والاختبار المشروعة، كيوفّر حتى نمط تسجيل البلدان طريق واضح باش تزيد مولّدات جديدة.