كيفية استخدام خادم FastAPI MCP: دليل شامل

خادم FastAPI MCP هو أداة ثورية تسد الفجوة بين تطبيقات FastAPI الخاصة بك وعوامل الذكاء الاصطناعي باستخدام بروتوكول نموذج السياق (MCP). في عصر يتزايد فيه دمج الذكاء الاصطناعي أهمية، تتيح لك هذه الحلول ذات التهيئة الصفرية عرض نقاط النهاية الموجودة في FastAPI كأدوات يمكن اكتشافها واستخدامها بواسطة نماذج وعوامل الذكاء الاصطناعي مع الحد الأدنى من الجهد.

💡

قبل أن تبدأ في تكوين خادم Kubernetes MCP، فكر في استكشاف Apidog—أداة قوية لتصميم واختبار وتوثيق واجهات برمجة التطبيقات. يعمل Apidog على تبسيط دمج واجهات برمجة التطبيقات مع نماذج منظمة وتعاون سلس. عند دمجه مع Zapier MCP، فإنه يعزز الأتمتة وإدارة واجهات برمجة التطبيقات.

زر

مقدمة إلى FastAPI MCP

بروتوكول نموذج السياق (MCP) هو معيار ناشئ يمكّن نماذج الذكاء الاصطناعي من التفاعل مع أدوات وموارد خارجية. يعمل خادم FastAPI MCP كجسر بين تطبيقات FastAPI الموجودة لديك وعوامل الذكاء الاصطناعي المتوافقة مع MCP مثل Claude من Anthropic، Cursor IDE، وغيرها، دون الحاجة إلى إعادة كتابة واجهة برمجة التطبيقات الخاصة بك أو تعلم أطر جديدة معقدة.

ما يجعل FastAPI MCP مميزًا حقًا هو نهجه ذو التهيئة الصفرية. يقوم تلقائيًا بتحويل نقاط النهاية الموجودة لديك في FastAPI إلى أدوات متوافقة مع MCP، مع الحفاظ على مخططات نقاط النهاية والتوثيق والوظائف. يعني هذا أن عوامل الذكاء الاصطناعي يمكنها اكتشاف والتفاعل مع واجهات برمجة التطبيقات الخاصة بك مع الحد الأدنى من الإعداد المطلوب منك.

يمكنك العثور على مستودع خادم FastAPI MCP على: https://github.com/tadata-org/fastapi_mcp

البدء باستخدام FastAPI MCP

التثبيت

قبل أن تتمكن من استخدام FastAPI MCP، ستحتاج إلى تثبيته. يوصي المطورون باستخدام uv، وهو مثبت حزم بايثون سريع، لكن يمكنك أيضًا استخدام طريقة pip التقليدية:

باستخدام uv:

uv add fastapi-mcp

باستخدام pip:

pip install fastapi-mcp

تنفيذ أساسي

إدماج FastAPI MCP مع تطبيق FastAPI الخاص بك لا يمكن أن يكون أبسط من ذلك. إليك أبسط تنفيذ:

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

# تطبيق FastAPI الموجود لديك
app = FastAPI()

# إنشاء خادم MCP
mcp = FastApiMCP(
    app,
    name="My API MCP",
    description="وصف واجهة برمجة التطبيقات الخاصة بي",
    base_url="http://localhost:8000"  # هام لتوجيه الطلبات
)

# تركيب خادم MCP على تطبيق FastAPI الخاص بك
mcp.mount()

هذا كل شيء! مع هذا الكود البسيط، أصبح خادم MCP الخاص بك متاحًا الآن على https://app.base.url/mcp. عندما يتصل عميل متوافق مع MCP بهذه النقطة النهائية، سيكتشف تلقائيًا جميع مسارات FastAPI الخاصة بك كأدوات متاحة.

فهم أسماء أدوات MCP ومعرفات العمليات

عند عرض FastAPI MCP لنقاط النهاية الخاصة بك كأدوات، يستخدم operation_id من مسارات FastAPI الخاصة بك كأسماء أدوات MCP. تقوم FastAPI بإنشاء هذه المعرفات تلقائيًا عندما لا يتم تقديمها صراحة، لكن يمكن أن تكون غامضة وأقل سهولة في الاستخدام.

قارن بين هذين الاقتراحين:

# operation_id الذي تم إنشاؤه تلقائيًا (أقل سهولة في الاستخدام)
@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

# operation_id صريح (أكثر سهولة في الاستخدام)
@app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
    return {"user_id": user_id}

في المثال الأول، قد تُسمى الأداة شيئًا مثل "read_user_users__user_id__get"، بينما سيكون المثال الثاني ببساطة "get_user_info". من أجل تحسين الاستخدام، خصوصًا عندما تتفاعل عوامل الذكاء الاصطناعي مع أدواتك، يوصى بتحديد معرفات العمليات صراحةً تكون واضحة ووصفية.

خيارات التهيئة المتقدمة

يوفر FastAPI MCP عدة خيارات تخصيص لتكييف كيفية عرض واجهتك لعملاء MCP.

تخصيص وصف المخطط

يمكنك التحكم في كمية المعلومات المتضمنة في أوصاف الأدوات:

mcp = FastApiMCP(
    app,
    name="My API MCP",
    base_url="http://localhost:8000",
    describe_all_responses=True,  # تضمين جميع مخططات الاستجابة الممكنة
    describe_full_response_schema=True  # تضمين تفاصيل مخطط JSON الكامل
)

تصفية نقاط النهاية

قد ترغب في التحكم في أي نقاط النهاية تُعرض كأدوات MCP. يقدم FastAPI MCP عدة آليات تصفية:

# تضمين عمليات محددة فقط حسب معرف العملية
mcp = FastApiMCP(
    app,
    include_operations=["get_user", "create_user"]
)

# استبعاد عمليات معينة
mcp = FastApiMCP(
    app,
    exclude_operations=["delete_user"]
)

# تصفية بواسطة العلامات
mcp = FastApiMCP(
    app,
    include_tags=["users", "public"]
)

# استبعاد بواسطة العلامات
mcp = FastApiMCP(
    app,
    exclude_tags=["admin", "internal"]
)

# دمج استراتيجيات التصفية
mcp = FastApiMCP(
    app,
    include_operations=["user_login"],
    include_tags=["public"]
)

لاحظ أنه لا يمكنك دمج عوامل التصفية للإدراج والاستبعاد من نفس النوع (عمليات أو علامات)، لكن يمكنك استخدام عوامل تصفية العمليات مع عوامل تصفية العلامات.

استراتيجيات النشر

يوفر FastAPI MCP مرونة في كيفية نشر خادم MCP الخاص بك.

التركيب على التطبيق الأصلي

أبسط طريقة هي تركيب خادم MCP مباشرةً على تطبيق FastAPI الأصلي لديك كما هو موضح في المثال الأساسي. هذا ينشئ نقطة النهاية عند /mcp في التطبيق الحالي لديك.

النشر كخدمة منفصلة

يمكنك أيضًا إنشاء خادم MCP من تطبيق FastAPI واحد وتركيبه على تطبيق مختلف، مما يتيح لك نشر واجهتك وواجهة MCP الخاصة بها بشكل منفصل:

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

# تطبيق واجهة برمجة التطبيقات الأصلي لديك
api_app = FastAPI()
# قم بتعريف نقاط النهاية الخاصة بك هنا...

# تطبيق منفصل لخادم MCP
mcp_app = FastAPI()

# إنشاء خادم MCP من تطبيق واجهة برمجة التطبيقات
mcp = FastApiMCP(
    api_app,
    base_url="http://api-host:8001"  # عنوان URL حيث سيعمل تطبيق واجهة برمجة التطبيقات
)

# تركيب خادم MCP على التطبيق المنفصل
mcp.mount(mcp_app)

# الآن قم بتشغيل كلا التطبيقين بشكل منفصل:
# uvicorn main:api_app --host api-host --port 8001
# uvicorn main:mcp_app --host mcp-host --port 8000

يمكن أن تكون هذه الفائدة مفيدة لإدارة الموارد، والأمان، والتوسع.

تحديث MCP بعد إضافة نقاط نهاية جديدة

إذا قمت بإضافة نقاط نهاية إلى تطبيق FastAPI الخاص بك بعد إنشاء خادم MCP، ستحتاج إلى تحديث الخادم لتضمينها:

# الإعداد الأولي
app = FastAPI()
mcp = FastApiMCP(app)
mcp.mount()

# لاحقًا، أضف نقطة نهاية جديدة
@app.get("/new/endpoint/", operation_id="new_endpoint")
async def new_endpoint():
    return {"message": "مرحبًا، العالم!"}

# تحديث خادم MCP لتضمين نقطة النهاية الجديدة
mcp.setup_server()

الاتصال بخادم MCP الخاص بك

بمجرد تشغيل تطبيق FastAPI الخاص بك مع دمج MCP، يمكن للعملاء الاتصال به بطرق متنوعة.

استخدام أحداث الخادم المرسلة (SSE)

العديد من عملاء MCP، مثل Cursor IDE، يدعمون اتصالات SSE:

قم بتشغيل تطبيقك
في Cursor → الإعدادات → MCP، استخدم عنوان URL الخاص بنقطة ختم خادم MCP الخاصة بك (مثل http://localhost:8000/mcp) كعنوان URL لـ SSE
سيكتشف Cursor تلقائيًا جميع الأدوات والموارد المتاحة

استخدام وكيل MCP للعملاء الذين لا يدعمون SSE

بالنسبة للعملاء الذين لا يدعمون SSE مباشرة (مثل Claude Desktop):

قم بتشغيل تطبيقك
قم بتثبيت أداة وكيل MCP: uv tool install mcp-proxy
قم بتكوين عميلك لاستخدام وكيل mcp

لـ Claude Desktop على نظام Windows، أنشئ ملف تكوين (claude_desktop_config.json):

{
  "mcpServers": {
    "my-api-mcp-proxy": {
      "command": "mcp-proxy",
      "args": ["http://127.0.0.1:8000/mcp"]
    }
  }
}

لنظام macOS، ستحتاج إلى تحديد المسار الكامل التنفيذي لوكيل mcp، والذي يمكنك العثور عليه باستخدام which mcp-proxy.

حالات استخدام في العالم الحقيقي

يفتح FastAPI MCP العديد من الإمكانيات للتطبيقات المدعومة بالذكاء الاصطناعي:

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

أفضل الممارسات

للحصول على أقصى استفادة من FastAPI MCP، اعتبر هذه الممارسات الجيدة:

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

الخاتمة

يمثل خادم FastAPI MCP خطوة هامة إلى الأمام في جعل الخدمات الخلفية متاحة لوكلاء الذكاء الاصطناعي. من خلال تحويل نقاط النهاية الموجودة لديك في FastAPI تلقائيًا إلى أدوات متوافقة مع MCP دون تكوين، فإنه يلغي الحاجة إلى عمليات تكامل مخصصة أو تعديلات معقدة على تصميم واجهة برمجة التطبيقات الخاصة بك.

مع استمرار نمو نظام MCP البيئي واعتماد نماذج الذكاء الاصطناعي لهذا المعيار، فإن عرض واجهات برمجة التطبيقات الخاصة بك من خلال FastAPI MCP سيوضع خدماتك لتكون بعيدة المنال لعوامل وأدوات الذكاء الاصطناعي. سواء كنت تقوم بإنشاء أدوات داخلية، خدمات للمطورين، أو واجهات برمجة التطبيقات العامة، تقدم FastAPI MCP طريقًا مباشرًا لجعل خدماتك متاحة للذكاء الاصطناعي.

باتباع الإرشادات في هذه المقالة، يمكنك بسرعة دمج FastAPI MCP في تطبيقات FastAPI الحالية لديك وبدء استكشاف إمكانيات الأتمتة والتفاعل المدعومين بالذكاء الاصطناعي مع خدماتك.