إنشاء خادم MCP بلغة Python لعرض أدلة التشغيل (runbooks)

إنشاء خادم MCP بلغة Python بالـ SDK الرسمي: اعرض أدلة التشغيل (runbooks) للقراءة فقط، مع موارد وأداة بحث وقالب prompt لتحقيق منظَّم.
Créer un serveur MCP Python pour exposer vos runbooks d'exploitation

إنشاء خادم MCP بلغة Python من أسرع الطرق اليوم لجعل معرفة داخلية في متناول مساعد ذكاء اصطناعي. وأدلة التشغيل (runbooks) تناسب ذلك تمامًا: فهي مكتوبة ومنظمة، وكثيرًا ما تتناثر في ويكي أو مستودع Git، وتكون ثمينة في اللحظة التي لا يجد فيها أحد وقتًا للبحث عنها.

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

نستخدم SDK الرسمي لبروتوكول سياق النموذج بلغة Python. تغيّرت واجهته البرمجية مع الإصدار 2 (فصنف FastMCP من الإصدار 1 يُسمّى الآن MCPServer): إن اتبعت درسًا أقدم فعدّل عمليات الاستيراد.

لماذا تنشئ خادم MCP بلغة Python لأدلة التشغيل؟

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

  • كل دليل تشغيل يصبح موردًا (resource) يُعنوَن بمعرّف URI مثل runbook://redemarrage-api؛
  • البحث بالكلمات المفتاحية يصبح أداة يستدعيها النموذج عندما يبحث عن إجراء؛
  • منهج التحقيق يصبح قالبًا (prompt) يطلقه المستخدم صراحةً.

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

تجهيز البيئة

يتطلب SDK لغة Python بإصدار 3.10 أو أحدث. ويُثبَّت من PyPI باسم mcp؛ والإضافة cli تضيف الأمر mcp المفيد للاختبار:

python3 -m venv .venv
. .venv/bin/activate
pip install "mcp[cli]"

ويوصي المشروع أيضًا بأداة uv لإدارة البيئة. ارجع إلى وثائق SDK لـ Python للطريقة المحدَّثة.

أما المحتوى فلنفترض دليلًا من ملفات Markdown، ملف لكل دليل تشغيل:

/opt/runbooks/
  redemarrage-api.md
  saturation-disque.md
  certificat-expire.md

عمليًا

الخطوة 1: عرّف الخادم والموارد

يتسع الخادم لملف واحد. نبدأ بكائن الخادم ومورد ذي معامل يقرأ دليل تشغيل باسمه. ولا تُستدعى الدالة إلا عندما يقرأ عميل المورد فعلًا.

import logging
import os
import re
from pathlib import Path

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ResourceNotFoundError, ToolError
from mcp.types import ToolAnnotations

RUNBOOKS_DIR = Path(os.environ.get("RUNBOOKS_DIR", "/opt/runbooks")).resolve()
NOM_VALIDE = re.compile(r"^[a-z0-9-]{1,64}$")

log = logging.getLogger("runbooks")
mcp = MCPServer("runbooks-ops")


def chemin_runbook(nom: str) -> Path:
    """Valide le nom et empêche toute sortie du répertoire."""
    if not NOM_VALIDE.match(nom):
        raise ResourceNotFoundError("Nom de runbook invalide.")
    chemin = (RUNBOOKS_DIR / f"{nom}.md").resolve()
    if chemin.parent != RUNBOOKS_DIR or not chemin.is_file():
        raise ResourceNotFoundError(f"Runbook introuvable : {nom}")
    return chemin


@mcp.resource("runbook://{nom}")
def lire_runbook(nom: str) -> str:
    """Contenu complet d'un runbook d'exploitation."""
    return chemin_runbook(nom).read_text(encoding="utf-8")

تفصيلان مهمان. التحقق من الاسم بتعبير نمطي ثم فحص المسار المحلول يمنعان محاولات من نوع ../../etc/passwd. ورسائل الخطأ تبقى مقتضبة: فلا تكشف بنية مجلدات الخادم.

الخطوة 2: أضف أداة بحث

لا يعرف النموذج أسماء ملفاتك. وأداة البحث تتيح له العثور على دليل التشغيل المناسب انطلاقًا من عَرَض:

@mcp.tool(annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False))
def chercher_runbooks(mots_cles: str) -> list[str]:
    """Cherche les runbooks dont le contenu contient tous les mots-clés.
    Renvoie au plus 10 noms, à lire ensuite via runbook://{nom}."""
    termes = [t.lower() for t in mots_cles.split()][:5]
    if not termes:
        raise ToolError("Indiquez au moins un mot-clé.")
    resultats = []
    for fichier in sorted(RUNBOOKS_DIR.glob("*.md")):
        texte = fichier.read_text(encoding="utf-8").lower()
        if all(t in texte for t in termes):
            resultats.append(fichier.stem)
    log.info("recherche %s : %d résultat(s)", termes, len(resultats))
    return resultats[:10]

التوثيق النصي (docstring) ليس للزينة: هو الوصف الذي يقرؤه النموذج ليقرر متى يستدعي الأداة. وتُعلم التعليقات التوضيحية العميل بأن الأداة لا تعدّل شيئًا، لكنها مجرد إشارات؛ والأمان قائم على الشيفرة نفسها.

الخطوة 3: اقترح قالب تحقيق

يوجّه القالب المستخدم نحو منهج متماسك:

@mcp.prompt()
def investiguer(symptome: str) -> str:
    """Démarrer une investigation à partir d'un symptôme."""
    return (
        f"Symptôme observé : {symptome}\n"
        "1. Cherche les runbooks pertinents avec chercher_runbooks.\n"
        "2. Lis le plus adapté et résume les vérifications à faire.\n"
        "3. Ne propose aucune action destructive sans validation explicite."
    )


if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)
    mcp.run()

من دون وسيط، يستخدم mcp.run() قناة النقل stdio. وعندئذٍ يخدم الخرج القياسي البروتوكول: استخدم الوحدة logging، التي تكتب على مجرى الأخطاء، بدل print().

الخطوة 4: اختبر باستخدام Inspector

يشغّل الأمر الذي توفره الإضافة cli الخادم تحت MCP Inspector، وهي واجهة ويب للاختبار (تتطلب Node.js):

mcp dev serveur_runbooks.py

اختبر البحث بكلمات مفتاحية حقيقية، واقرأ موردًا، ثم جرّب عمدًا أسماء غير صالحة للتحقق من حالات الرفض.

الخطوة 5: صرّح عن الخادم في مساعدك

تقبل معظم المضيفات أمر تشغيل في إعداداتها. استخدم Python الخاص بالبيئة الافتراضية لتضمن توفر الاعتماديات الصحيحة:

{
  "mcpServers": {
    "runbooks": {
      "command": "/opt/runbooks-mcp/.venv/bin/python",
      "args": ["/opt/runbooks-mcp/serveur_runbooks.py"],
      "env": { "RUNBOOKS_DIR": "/opt/runbooks" }
    }
  }
}

ولخادم يشترك فيه الفريق، يستطيع SDK أيضًا الخدمة عبر HTTP بالأمر mcp.run(transport="streamable-http")، الذي يستمع افتراضيًا على الواجهة المحلية. قبل فتحه على الشبكة أضف مصادقة وراجع دليلنا عن تأمين خادم MCP.

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

  • ابدأ بالقراءة فقط؛ وأضف أدوات الإجراءات بموافقة بشرية فقط.
  • تحقق من كل وسيط في جانب الخادم: قوائم مسموحة وأطوال وصيغ.
  • اكتب docstrings دقيقة: فهي توجّه اختيار النموذج.
  • أطلق خطأ أداة صريحًا بدل إعادة نص خطأ كأنه نتيجة.
  • سجّل على مجرى الأخطاء، لا على الخرج القياسي مع stdio.
  • أدرج أدلة التشغيل في Git وراجعها كما تراجع الشيفرة: فقد أصبحت تعليمات يقرؤها وكيل.

الأسئلة الشائعة

هل أستخدم FastMCP أم MCPServer؟

في SDK الرسمي بإصداره 2 أُعيدت تسمية FastMCP إلى MCPServer. ويفصّل دليل الترحيل في SDK مطابقة عمليات الاستيراد.

هل خادمي قابل للمراقبة؟

يصدر SDK بإصداره 2 spans من OpenTelemetry لكل رسالة تُعالَج؛ ويكفي تثبيت SDK ومصدِّر. انظر مراقبة وكلاء MCP باستخدام OpenTelemetry.

هل أستطيع ربط هذا الخادم بحوادثي؟

نعم، بجمع أدلة التشغيل فيه مع خادم لقابلية الملاحظة في المساعد نفسه. ومقالاتنا مثل الحوادث الشائعة في عنقود Managed مرشحة جيدة للتحويل إلى أدلة تشغيل.

الخلاصة

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

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC ولا للمشاريع المذكورة. العلامات التجارية المذكورة ملك لأصحابها. الأدوات تتطور بسرعة، لذا تحقق دائمًا من الأوامر والخيارات في وثائقها الرسمية.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Sécuriser serveur MCP : tokens, moindre privilège, injection de prompt et validation humaine

تأمين خادم MCP: الرموز المميّزة وأقل الصلاحيات وحقن التعليمات والموافقة البشرية

Next Post
Observer les agents MCP avec OpenTelemetry : spans d'appels d'outils, attributs, latence et erreurs

مراقبة وكلاء MCP باستخدام OpenTelemetry: spans الأدوات والسمات وزمن الاستجابة والأخطاء

Related Posts