MCP استدعاءات الأداة والأمثلة

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

بعد ترخيص OAuth، استخدم عميل MCP مع HTTP القابل للتدفق لتهيئة الاتصال والحصول على الأدوات من خلال tools/list. أدوات الاتصال من خلال tools/call. اقرأ كل مخطط إدخال تم إرجاعه بدلاً من اشتقاق المعلمات من عناوين URL REST. عادةً ما تكون المعرفات المأخوذة من القراءات عبارة عن سلاسل عشرية لوسيطات المسار؛ يظل الحقل الرقمي داخل الجسم رقميًا حيث يتطلب المخطط ذلك.

الأمثلة أدناه هي رسائل الأداة JSON-RPC بعد التهيئة، وليست طلبات HTTP المستقلة الكاملة. يوفر العميل رمز الوصول ورؤوس البروتوكول. استبدل المعرفات التوضيحية بالسجلات التي تم إرجاعها للمستأجر الخاص بك.

قراءة الفئات

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "knowledge_get_categories",
    "arguments": {}
  }
}

قم بإنشاء مسودة

اختر فئة موجودة من نتيجة القراءة. الفئة مطلوبة. لا تقم بتعيين حالة النشر إلا إذا كنت تنوي نشر وإكمال أي تأكيد مطلوب.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "knowledge_create_article",
    "arguments": {
      "requestId": "support-demo-create-001",
      "body": {
        "title": "Withdrawal guide draft",
        "content": "Reviewed withdrawal instructions go here.",
        "categoryId": 12,
        "status": "draft"
      }
    }
  }
}

معاينة التحديث أو الحذف

إقرأ المقال أولا. قم بمعاينة الكتابة المقصودة بالضبط، بما في ذلك معرف الطلب الجديد. المعاينة لا تنفذها.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "mcp_preview",
    "arguments": {
      "tool": "knowledge_delete_article",
      "arguments": {
        "id": "123",
        "requestId": "support-demo-delete-001"
      }
    }
  }
}

انسخ version الذي تم إرجاعه إلى expectedVersion دون تغيير الهدف أو المعلمات المقصودة:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "knowledge_delete_article",
    "arguments": {
      "id": "123",
      "requestId": "support-demo-delete-001",
      "expectedVersion": "REPLACE_WITH_THE_64_CHARACTER_VERSION_FROM_PREVIEW"
    }
  }
}

العنصر النائب ليس إصدارًا صالحًا. استخدم القيمة الفعلية المكونة من 64 حرفًا التي أرجعتها المعاينة.

تأكيد والتحقق من النتيجة

إذا كانت النتيجة تشير إلى awaiting_approval، فافتح approvalUrl، وقم بتسجيل الدخول كحساب التفويض وراجع الإجراء. فقط الموافقة عليه يؤدي إلى تشغيل العملية المعلقة. تنتهي صلاحية التأكيد حاليًا بعد 15 دقيقة. الرفض أو انتهاء الصلاحية لا يؤدي إلى تنفيذ الكتابة.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "mcp_operation",
    "arguments": {
      "operationId": "REPLACE_WITH_RETURNED_OPERATION_ID"
    }
  }
}

يتم تنفيذ إخراج الأداة في محتوى نصي يحتوي على JSON؛ قم بفحصها وأي علامة isError. إن الرد HTTP أو رابط الموافقة وحده لا يثبت النجاح. اقرأ حالة العملية، وعندما يكون ذلك مفيدًا، قم بالاستعلام عن السجل المتأثر.

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

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

عادةً ما يقوم عميل الذكاء الاصطناعي بتنفيذ هذا البروتوكول للمستخدم. هذه التفاصيل مخصصة لمطوري العملاء ولتشخيص سير عمل الأداة.