دليل المبتدئين لاستخدام FastMCP

يتطور مشهد نماذج اللغة الكبيرة (LLMs) بسرعة، حيث ينتقل من توليد النصوص البسيطة إلى تفاعلات معقدة مع الأنظمة الخارجية ومصادر البيانات. يتطلب تسهيل هذا التفاعل اتباع نهج موحد، لغة مشتركة لطلب المعلومات وتنفيذ الإجراءات. هنا يأتي بروتوكول سياق النموذج (MCP)، المصمم كمعيار عالمي - غالبًا ما يُشبه بـ "منفذ USB-C للذكاء الاصطناعي" - مما يمكّن التواصل السلس بين LLMs والموارد التي تحتاجها.

بينما يوفر MCP المواصفات، فإن بناء الخوادم والعمليات التي تتوافق معه قد يتطلب الكثير من التعليمات البرمجية الإضافية وإدارة البروتوكولات. هنا يتألق FastMCP. FastMCP هو إطار عمل عالي المستوى وموجه بلغة بايثون، مصمم لتبسيط إنشاء خوادم وعمليات MCP بشكل كبير. إنه يتعامل مع التعقيدات الكامنة في البروتوكول، مما يتيح للمطورين التركيز على تعريف الأدوات القيمة وموارد البيانات وأنماط التفاعل التي يرغبون في عرضها لـ LLMs.

💡

تريد أداة اختبار واجهة برمجة التطبيقات رائعة تولد توثيقات واجهة برمجة تطبيقات جميلة؟

تريد منصة متكاملة، شاملة لكل شيء لفريق المطورين لديك للعمل معًا بأقصى إنتاجية؟

يوفر Apidog جميع احتياجاتك، ويستبدل Postman بسعر أكثر ملاءمة بكثير!

زر

ما هو بروتوكول سياق النموذج (MCP)؟

قبل التعمق أكثر في FastMCP، من الضروري فهم المفاهيم الأساسية لـ MCP نفسه. يحدد MCP طريقة موحدة لتطبيقات LLM (العمليات) للتفاعل مع الأنظمة الخارجية (الخوادم). يمكن لخادم MCP أن يكشف عن عدة مكونات رئيسية:

الأدوات: هذه هي في الأساس الوظائف التي يمكن لـ LLM أن يطلب من الخادم تنفيذها. فكر فيها كأبعاد POST في واجهة برمجة التطبيقات التقليدية. تقوم بتنفيذ إجراءات، ويمكن أن تتفاعل مع أنظمة أخرى (قواعد البيانات، واجهات برمجة التطبيقات، الأجهزة)، وإعادة النتائج. على سبيل المثال، يمكن أن ترسل أداة بريدًا إلكترونيًا، تستعلم عن قاعدة بيانات، أو تنفذ عملية حسابية.
الموارد: هذه تكشف عن البيانات التي يمكن لـ LLM قراءتها أو استرجاعها. تشبه نقاط GET، حيث تزود الموارد المعلومات لإثراء سياق LLM. قد تكون هذه أي شيء من ملفات التكوين وملفات تعريف المستخدمين إلى تدفقات بيانات حية.
التوجيهات: هذه هي القوالب القابلة لإعادة الاستخدام لهيكلة التفاعلات مع LLM. تساعد في توجيه المحادثة وتضمن نتائج متسقة لمهام معينة.
السياق: يمكن للخوادم تقديم معلومات سياقية، بما في ذلك التعليمات حول كيفية أفضل تفاعل مع الأدوات والموارد المتاحة.

يهدف MCP إلى إنشاء نظام بيئي قوي وآمن حيث يمكن لـ LLMs الوصول إلى القدرات الخارجية واستخدامها بشكل موثوق.

لماذا تختار FastMCP؟

بينما يمكنك تنفيذ مواصفات MCP مباشرة باستخدام حزم SDK منخفضة المستوى، تقدم FastMCP مزايا جذابة، خاصة لمطوري بايثون:

🚀 تطوير سريع: واجهته عالية المستوى تقلل بشكل كبير من كمية التعليمات البرمجية المطلوبة، مما يسرع عملية التطوير. في كثير من الأحيان، يكون تعريف أداة أو مورد بسيطًا مثل تزيين دالة بايثون قياسية.
🍀 البساطة: FastMCP يخفي التفاصيل المعقدة لإعداد الخادم، وإدارة البروتوكول، وأنواع المحتوى، وإدارة الأخطاء، مما يقلل التعليمات البرمجية الإضافية.
🐍 بايثوني: مصمم مع وضع أفضل ممارسات بايثون في الاعتبار، يشعر بالراحة والبديهة للمطورين المألوفين باللغة، مستفيدًا من ميزات مثل تلميحات الأنواع والمزخرفات.
🔍 كامل: تهدف FastMCP إلى توفير تنفيذ شامل لمواصفات MCP الأساسية، مما يضمن التوافق والوصول إلى الإمكانيات الكاملة للبروتوكول.

أثبتت النسخة 1 من FastMCP نجاحها الكبير وهي الآن مدمجة في مجموعة أدوات MCP بايثون الرسمية. تبني النسخة 2 على هذا الأساس، مقدمة ميزات متقدمة تركز على تبسيط تفاعلات الخادم، مثل العملاء المرنين، وإدارة خادم الوكيل، وأنماط التركيب.

كيفية تثبيت FastMCP

إعداد FastMCP في بيئة بايثون الخاصة بك سهل. الطريقة الموصى بها تستخدم uv، وهو مثبت حزم بايثون سريع ومحلل.

1. باستخدام uv (موصى به):

إذا كنت تدير الاعتماديات لمشروع، أضف FastMCP باستخدام:

uv add fastmcp

بدلاً من ذلك، يمكنك تثبيته مباشرة في بيئة العمل الخاصة بك:

uv pip install fastmcp

2. باستخدام pip:

إذا كنت تفضل استخدام pip، يمكنك تثبيت FastMCP مع:

pip install fastmcp

3. التحقق من التثبيت:

بعد التثبيت، يمكنك التحقق مما إذا كانت FastMCP مثبتة بشكل صحيح والتحقق من إصدارها، إلى جانب إصدار مجموعة أدوات MCP الأساسية وتفاصيل بيئة بايثون الخاصة بك، من خلال تشغيل:

fastmcp version

يجب أن ترى مخرجات مشابهة لما يلي:

$ fastmcp version

FastMCP version:   0.4.2.dev41+ga077727.d20250410
MCP version:                                1.6.0
Python version:                            3.12.2
Platform:            macOS-15.3.1-arm64-arm-64bit
FastMCP root path:            ~/Developer/fastmcp

4. التثبيت للتطوير:

إذا كنت تنوي المساهمة في مشروع FastMCP نفسه، سترغب في إعداد بيئة تطوير:

git clone https://github.com/jlowin/fastmcp.git
cd fastmcp
uv sync

هذا يستنسخ المستودع، وينتقل إلى الدليل، ويستخدم uv sync لتثبيت جميع الاعتماديات اللازمة، بما في ذلك أدوات التطوير، داخل بيئة افتراضية. يمكنك بعد ذلك تشغيل الاختبارات باستخدام pytest.

كيفية استخدام FastMCP: بناء أول خادم لك

الآن، دعنا نغوص في الجوانب العملية لاستخدام FastMCP.

1. إنشاء مثيل خادم أساسي:

جوهر أي تطبيق FastMCP هو فئة FastMCP. تبدأ بإنشاء مثيل لهذه الفئة.

أنشئ ملفًا باسم my_server.py:

# my_server.py
from fastmcp import FastMCP
import asyncio # سنحتاج هذا لاحقًا للعميل

# إنشاء خادم، معطى له اسم
mcp = FastMCP(name="My First MCP Server")

print("تم إنشاء كائن خادم FastMCP.")

يقبل المُنشئ FastMCP عدة معاملات مفيدة:

name (str، اختياري): اسم قابل للقراءة من قبل الإنسان لخادمك (افتراضي إلى "FastMCP"). مفيد للتعريف في سجلات الأحداث أو تطبيقات العميل.
instructions (str، اختياري): وصف يوجه العملاء حول كيفية التفاعل مع الخادم، موضحًا هدفه أو مسلطًا الضوء على الوظائف الرئيسية.
lifespan (callable، اختياري): مدير سياق غير متزامن للتعامل مع منطق بدء تشغيل الخادم وإيقاف التشغيل (مثل، تهيئة اتصالات قواعد البيانات).
tags (set[str]، اختياري): علامات لتصنيف الخادم نفسه.
**settings: يمكنك تمرير معاملات كلمات رئيسية تتوافق مع ServerSettings (مثل port، host، log_level) مباشرة إلى المُنشئ للتكوين.

2. إضافة المكونات:

الخادم الفارغ ليس مفيدًا جدًا. دعونا نضيف المكونات الأساسية لـ MCP.

إضافة أداة: الأدوات هي وظائف مكشوفة للعميل. استخدم المُزخرف @mcp.tool(). يستخدم FastMCP تلميحات الأنواع في بايثون لتعريف المعاملات المدخلة المتوقعة ونوع النتيجة للعميل.

# my_server.py (مستمر)
@mcp.tool()
def greet(name: str) -> str:
    """يعيد تحية بسيطة."""
    return f"مرحبًا، {name}!"

@mcp.tool()
def add(a: int, b: int) -> int:
    """يجمع بين عددين معًا."""
    return a + b

print("تمت إضافة الأداتين 'greet' و 'add'.")

إضافة مورد: تكشف الموارد عن البيانات عبر URI. استخدم المُزخرف @mcp.resource()، موفرًا سلسلة URI.

# my_server.py (مستمر)
APP_CONFIG = {"theme": "dark", "version": "1.1", "feature_flags": ["new_dashboard"]}

@mcp.resource("data://config")
def get_config() -> dict:
    """يوفر إعدادات التطبيق."""
    return APP_CONFIG

print("تمت إضافة المورد 'data://config'.")

إضافة قالب مورد: هذه تشبه الموارد الديناميكية حيث تعمل أجزاء من URI كمعاملات.

# my_server.py (مستمر)
USER_PROFILES = {
    101: {"name": "Alice", "status": "active"},
    102: {"name": "Bob", "status": "inactive"},
}

@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: int) -> dict:
    """يسترجع ملف تعريف المستخدم بواسطة معرفه."""
    # يتم تمرير {user_id} من URI كمعامل تلقائيًا
    return USER_PROFILES.get(user_id, {"error": "المستخدم غير موجود"})

print("تمت إضافة قالب المورد 'users://{user_id}/profile'.")

إضافة توجيه: التوجيهات تعرف أنماط التفاعل القابلة لإعادة الاستخدام.

# my_server.py (مستمر)
@mcp.prompt("summarize")
async def summarize_prompt(text: str) -> list[dict]:
    """ينشئ توجيهًا لتلخيص النص المقدم."""
    return [
        {"role": "system", "content": "أنت مساعد مفيد متمكن في التلخيص."},
        {"role": "user", "content": f"يرجى تلخيص النص التالي:\n\n{text}"}
    ]

print("تمت إضافة التوجيه 'summarize'.")

3. اختبار الخادم (داخل العملية):

قبل تشغيل الخادم خارجيًا، يمكنك اختبار مكوناته مباشرة في نفس برنامج بايثون باستخدام Client. هذا مفيد للاختبارات السريعة واختبارات الوحدة.

# my_server.py (مستمر)
from fastmcp import Client # استيراد العميل

async def test_server_locally():
    print("\n--- اختبار الخادم محليًا ---")
    # توجيه العميل مباشرة إلى كائن الخادم
    client = Client(mcp)

    # العميل متزامن، لذا استخدم مدير سياق غير متزامن
    async with client:
        # استدعاء الأداة 'greet'
        greet_result = await client.call_tool("greet", {"name": "مستخدم FastMCP"})
        print(f"نتيجة greet: {greet_result}")

        # استدعاء الأداة 'add'
        add_result = await client.call_tool("add", {"a": 5, "b": 7})
        print(f"نتيجة add: {add_result}")

        # قراءة المورد 'config'
        config_data = await client.read_resource("data://config")
        print(f"المورد config: {config_data}")

        # قراءة ملف تعريف مستخدم باستخدام القالب
        user_profile = await client.read_resource("users://101/profile")
        print(f"ملف تعريف المستخدم 101: {user_profile}")

        # الحصول على هيكل توجيه 'summarize' (لا ينفذ الاتصال بـ LLM هنا)
        prompt_messages = await client.get_prompt("summarize", {"text": "هذا نص."})
        print(f"هيكل توجيه التلخيص: {prompt_messages}")

# تشغيل وظيفة الاختبار المحلي
# asyncio.run(test_server_locally())
# معلّق الآن، سنركز على تشغيل الخادم لاحقًا

لاحظ استخدام async وawait. تعمل عملاء FastMCP بشكل غير متزامن، مما يتطلب وظيفة async واستخدام async with client: لإدارة دورة حياة العميل.

4. تشغيل الخادم:

لجعل خادم MCP الخاص بك قابلًا للوصول من العملاء الخارجيين (مثل تطبيق LLM)، تحتاج إلى تشغيله. هناك طريقتان رئيسيتان:

تنفيذ بايثون القياسي (موصى به للتوافق):
أضف كتلة if __name__ == "__main__": التالية إلى ملف my_server.py. هذه هي الممارسة القياسية لبايثون لجعل البرنامج النصي قابلًا للتنفيذ.

# my_server.py (في نهاية الملف)

if __name__ == "__main__":
    print("\n--- بدء خادم FastMCP عبر __main__ ---")
    # هذا يبدأ الخادم، وعادة ما يستخدم النقل stdio بشكل افتراضي
    mcp.run()

لتشغيل الخادم، نفذ البرنامج النصي من الطرفية:

python my_server.py

تبدأ هذه التعليمة تشغيل خادم MCP، في انتظار اتصالات العملاء باستخدام آلية النقل الافتراضية stdio (الإدخال/الإخراج القياسي). تضمن هذه الطريقة تشغيل خادمك باستمرار لمختلف العملاء الذين يتوقعون تنفيذ برنامج بايثون.

باستخدام واجهة سطر أوامر FastMCP:
يوفر FastMCP واجهة سطر أوامر لتشغيل الخوادم، مما يوفر المزيد من المرونة والتحكم، خاصة فيما يتعلق بخيارات النقل.

# تشغيل الخادم باستخدام stdio (افتراضي)
fastmcp run my_server.py:mcp

# تشغيل الخادم باستخدام أحداث من الخادم (SSE) على المنفذ 8080
fastmcp run my_server.py:mcp --transport sse --port 8080 --host 0.0.0.0

# التشغيل مع مستوى سجل مختلف
fastmcp run my_server.py:mcp --transport sse --log-level DEBUG

نقاط رئيسية حول واجهة سطر الأوامر:

my_server.py:mcp: يحدد الملف (my_server.py) وكائن خادم FastMCP داخل ذلك الملف (mcp). إذا كنت تتجاهل :mcp، سيحاول FastMCP العثور تلقائيًا على كائن يسمى mcp، app، أو server.
كتلة if __name__ == "__main__": غير مطلوبة عند استخدام fastmcp run; تجد واجهة سطر الأوامر مباشرة وتنفذ كائن الخادم المحدد.
--transport: يحدد بروتوكول الاتصال (stdio، sse). SSE شائع للتفاعلات المستندة إلى الويب.
--port، --host، --log-level: تكوين إعدادات النقل والسجلات.

5. التفاعل مع خادم قيد التشغيل (العميل):

بمجرد تشغيل الخادم لديك (سواء عبر python my_server.py أو fastmcp run)، يمكنك إنشاء برنامج عميل منفصل للتفاعل معه.

أنشئ ملفًا جديدًا، my_client.py:

# my_client.py
from fastmcp import Client
import asyncio

async def interact_with_server():
    print("--- إنشاء العميل ---")

    # الخيار 1: الاتصال بخادم يتم تشغيله عبر `python my_server.py` (يستخدم stdio)
    # client = Client("my_server.py")

    # الخيار 2: الاتصال بخادم يتم تشغيله عبر `fastmcp run ... --transport sse --port 8080`
    client = Client("http://localhost:8080") # استخدم عنوان URL/المنفذ الصحيح

    print(f"تم تكوين العميل للاتصال بـ: {client.target}")

    try:
        async with client:
            print("--- العميل متصل ---")
            # استدعاء الأداة 'greet'
            greet_result = await client.call_tool("greet", {"name": "العميل البعيد"})
            print(f"نتيجة greet: {greet_result}")

            # قراءة المورد 'config'
            config_data = await client.read_resource("data://config")
            print(f"المورد config: {config_data}")

            # قراءة ملف تعريف المستخدم 102
            profile_102 = await client.read_resource("users://102/profile")
            print(f"ملف تعريف المستخدم 102: {profile_102}")

    except Exception as e:
        print(f"حدث خطأ: {e}")
    finally:
        print("--- انتهى تفاعل العميل ---")

if __name__ == "__main__":
    asyncio.run(interact_with_server())

قم بتشغيل هذا البرنامج النصي للعميل بينما يعمل الخادم في طرفية أخرى:

python my_client.py

سيتصل العميل بالخادم المتشغل (تحقق من أن Client(...) يتوافق مع كيفية تشغيل الخادم - مسار الملف لـ stdio، عنوان URL لـ sse)، وينفذ مكالمات الأدوات وقراءات الموارد، ويطبع النتائج.

6. إعداد الخادم (ServerSettings):

يمكنك ضبط سلوك الخادم باستخدام ServerSettings. يمكن تطبيق الإعدادات وفقًا لترتيب الأولوية:

معاملات كلمات رئيسية أثناء تهيئة FastMCP (الأولوية الأعلى).
متغيرات البيئة (المقدمة بـ FASTMCP_SERVER_، مثل FASTMCP_SERVER_PORT=8888).
القيم المحملة من ملف .env في الدليل العامل.
القيم الافتراضية (الأولوية الأدنى).

مثال على التهيئة أثناء التهيئة:

from fastmcp import FastMCP

mcp_configured = FastMCP(
    name="ConfiguredServer",
    port=8080,  # تعيين المنفذ الافتراضي SSE
    host="127.0.0.1", # تعيين المضيف الافتراضي SSE
    log_level="DEBUG", # تعيين مستوى التسجيل
    on_duplicate_tools="warn" # تحذير إذا تم تسجيل أدوات بنفس الاسم (الخيارات: 'خطأ'، 'تحذير'، 'تجاهل')
)

# الوصول إلى الإعدادات عبر السمة .settings
print(f"المنفذ المكون: {mcp_configured.settings.port}") # الناتج: 8080
print(f"سياسة الأداة المكررة: {mcp_configured.settings.on_duplicate_tools}") # الناتج: تحذير

تشمل خيارات التهيئة الرئيسية host، port، log_level، وسياسات التعامل مع أسماء المكونات المكررة (on_duplicate_tools، on_duplicate_resources، on_duplicate_prompts).

ماذا يمكن أن تفعل أيضًا مع FastMCP؟

يدعم FastMCP أيضًا حالات الاستخدام الأكثر تقدمًا:

تركيب: دمج عدة خوادم FastMCP. main.mount("sub", sub_server) ينشئ رابطًا حيًا، بينما main.import_server(sub_server) ينسخ المكونات. هذا يعزز المرونة.
الوكالة: استخدم FastMCP.from_client(client) لإنشاء مثيل خادم FastMCP يعمل كوكيل لخادم MCP آخر (محلي أو بعيد). هذا مفيد لتمهيد وسائل النقل (مثل، كشف خادم SSE بعيد عبر stdio المحلي) أو إضافة واجهة أمامية موحدة.

الخاتمة

تقلل FastMCP بشكل كبير من عائق الدخول لبناء تطبيقات LLM قوية وواعية بالسياق من خلال تبسيط تنفيذ بروتوكول سياق النموذج. تصميمه القائم على بايثون، وتركيزه على تقليل التعليمات البرمجية الإضافية، ومجموعة الميزات الشاملة تجعل منه خيارًا ممتازًا للمطورين الذين يبحثون عن تجهيز LLMs بأدوات مخصصة والوصول إلى البيانات بشكل آمن وفعال.

من خلال اتباع الخطوات المذكورة أعلاه - تثبيت FastMCP، إنشاء مثيل خادم، إضافة أدوات وموارد باستخدام مُزخرفات بسيطة، وتشغيل الخادم - يمكنك بسرعة البدء في بناء تطبيقاتك الخاصة المعززة بـ MCP. سواء كنت تنشئ أدوات مساعدة بسيطة أو تكاملات معقدة تستند إلى البيانات، توفر FastMCP الأساس لتفاعلات LLM القوية والقابلة للتوسع.