خادم MCP

مقدمة

Model Context Protocol معيار مفتوح لكيفية وصول وكيل الذكاء الاصطناعي إلى الأدوات والبيانات الخارجية. وبدلًا من برمجة واجهة، تضيف الخادم مرة واحدة إلى إعدادات الوكيل. ومن ذلك الحين يعرف النموذج الأدوات الموجودة ويستدعيها بنفسه عندما تحتاج المحادثة إليها.

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

العنوان هو https://germanyinsolvencies.com/api/mcp. ويستخدم المفاتيح نفسها المستخدمة في واجهة REST. شغّل الاثنين جنبًا إلى جنب وسترى قائمة المراقبة نفسها في العالمين.

الوصول

الطريق هو نفسه كما في واجهة REST: تُصدر المفاتيح يدويًا. استخدم نموذج الاتصال أو راسل [email protected] واذكر باختصار أي وكيل تريد ربطه وما الذي ينبغي أن يفعله.

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

الاتصال والنقل

يتحدث الخادم بروتوكول MCP عبر Streamable HTTP، وهو وسيلة النقل التي تستخدمها العملاء الحالية افتراضيًا. لا حاجة إلى عملية محلية، ولا شيء يُثبَّت.

تستخدم المصادقة الترويسة نفسها المستخدمة في واجهة REST: X-API-Key، أو بديلًا عنها Authorization: Bearer. أما العملاء الذين يتحدثون stdio فقط فيصلون إلى الخادم عبر mcp-remote جسرًا، انظر إعداد Claude Desktop أدناه.

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

curl https://germanyinsolvencies.com/api/mcp/health

الإعداد

في Claude Code يكفي أمر واحد. ينبغي أن يأتي المفتاح من متغير بيئة لا من الحافظة.

claude mcp add --transport http insolvency \
  https://germanyinsolvencies.com/api/mcp \
  --header "X-API-Key: $INSOLVENCY_API_KEY"

Claude Desktop

يقرأ Claude Desktop قائمة خوادمه من claude_desktop_config.json. ويصل الإدخال إلى وسيلة نقل HTTP عبر mcp-remote جسرًا.

{
  "mcpServers": {
    "insolvency": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://germanyinsolvencies.com/api/mcp",
        "--header", "X-API-Key:${INSOLVENCY_API_KEY}"
      ],
      "env": { "INSOLVENCY_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Cursor وعملاء آخرون

يأخذ Cursor وWindsurf وZed ومعظم العملاء الآخرين عنوان الخادم مباشرة ويسمحون بترويسات خاصة بهم، فلا حاجة إلى جسر.

{
  "mcpServers": {
    "insolvency": {
      "url": "https://germanyinsolvencies.com/api/mcp",
      "headers": { "X-API-Key": "${env:INSOLVENCY_API_KEY}" }
    }
  }
}

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

الأدوات

يوفر الخادم إحدى عشرة أداة. الأدوات الكاتبة موسومة بذلك، ليتمكن العملاء من طلب التأكيد حيث يريدون.

جميع أدوات القراءة متساوية الأثر (idempotent) ويمكن استدعاؤها دون استئذان. أما watch_company وunwatch_company فتغيران حسابك وتعلنان للعميل أنهما أداتا كتابة.

check_counterparty بالتفصيل

الأداة التي تهم هي check_counterparty. مخططها ضيق عن قصد: اسم أو رقم سجل، وربما المدينة وتاريخ بداية. وكلما قلّت القرارات التي على النموذج اتخاذها قلّ اختلاقه للقيم.

{
  "name": "check_counterparty",
  "description": "Check whether a German company appears in official insolvency announcements. Use before extending credit, signing a supplier or chasing an overdue invoice. Prefer register number over name when you have it. Never guess a register number.",
  "annotations": { "readOnlyHint": true },
  "inputSchema": {
    "type": "object",
    "properties": {
      "name":           { "type": "string", "description": "Company name as written on the invoice or contract." },
      "city":           { "type": "string", "description": "Registered seat, narrows ambiguous names." },
      "register":       { "type": "string", "description": "e.g. HRB 123456 B" },
      "register_court": { "type": "string", "description": "e.g. Charlottenburg (Berlin)" },
      "since":          { "type": "string", "format": "date", "description": "Only filings on or after this date. Default: 3 years ago." }
    },
    "anyOf": [ { "required": ["name"] }, { "required": ["register"] } ]
  }
}

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

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

بدون since تنظر الأداة ثلاث سنوات إلى الوراء. الإجراءات الأقدم تكون عادةً مغلقة ولم تعد ذات صلة بالقرارات الحالية؛ وإن كانت ذات صلة فمرّر تاريخًا أبكر.

صيغة الاستجابة

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

{
  "content": [
    {
      "type": "text",
      "text": "Musterbau GmbH (HRB 123456 B, Berlin): insolvency proceedings OPENED on 2026-09-28 by Amtsgericht Charlottenburg, case 36a IN 4711/26. Earlier: protective measures on 2026-08-14. Source: official announcement."
    },
    {
      "type": "resource_link",
      "uri": "insolvency://filing/fil_8Kq2Zp4RwT",
      "name": "Announcement 36a IN 4711/26",
      "mimeType": "application/json"
    }
  ],
  "structuredContent": {
    "match": "exact",
    "company_id": "cmp_3n8Kd2ZpQv",
    "status": "opened",
    "filings": [
      { "id": "fil_8Kq2Zp4RwT", "date": "2026-09-28", "type_code": "2" },
      { "id": "fil_2Hd7Vb1Xe", "date": "2026-08-14", "type_code": "0" }
    ]
  },
  "isError": false
}

تعود النصوص الكاملة للإعلانات في صورة روابط موارد لا مضمّنة. العميل الذي يريد عرض النص يحلّ الرابط؛ والذي لا يريد يُبقي نافذة سياقه صغيرة. وقد يبلغ طول الإعلان الواحد عدة آلاف من الأحرف.

الموارد

إضافة إلى الأدوات يوفر الخادم موارد تحت المخطط insolvency://. يمكن للعملاء الذين يدعمون الموارد عرضها أو إرفاقها بالنموذج دون استدعاء أداة.

insolvency://filing/{id}             one announcement incl. full text
insolvency://company/{id}            company profile and status
insolvency://company/{id}/filings    all announcements of a company
insolvency://company/{id}/financials published balance sheet figures
insolvency://watchlist               your watched companies
insolvency://types                   filing types with codes and aliases

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

القوالب الجاهزة (Prompts)

للمهام المتكررة توجد قوالب جاهزة. تجمع ما تحتاجه المهمة ثم تستدعي الأدوات المناسبة. وتظهر في العملاء التي تدعم القوالب بوصفها أوامر سريعة.

{
  "name": "counterparty_check",
  "description": "Check a list of customers or suppliers for insolvency filings and summarise the risk.",
  "arguments": [
    { "name": "companies", "description": "One company per line: name, city or register number.", "required": true },
    { "name": "since",     "description": "Look-back start date, default 3 years.", "required": false }
  ]
}

المتاح حاليًا هو counterparty_check (فحص قائمة شركات) وweekly_briefing (إعلانات الأسبوع الجديدة لولايات اتحادية أو قطاعات مختارة) وproceeding_timeline (تاريخ إجراء مشروح بلغة بسيطة). وإن كنت تفضل مسارك الخاص فتجاهل القوالب واستدع الأدوات مباشرة.

محادثة نموذجية

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

المستخدم: هل يمكنك فحص أكبر ثلاث فواتير مفتوحة لدينا؟ Musterbau GmbH
          في برلين، وNordlicht Handels GmbH، وBeispiel Logistik في هامبورغ.

الوكيل:   [check_counterparty name="Musterbau GmbH" city="Berlin"]
          [check_counterparty name="Nordlicht Handels GmbH"]
          [check_counterparty name="Beispiel Logistik" city="Hamburg"]

الوكيل:   Musterbau GmbH: افتُتح الإجراء في 28 سبتمبر 2026
          (AG Charlottenburg، 36a IN 4711/26). يجب الآن تقديم المطالبات
          إلى مدير الإعسار، والدفع المباشر مستبعد.
          Beispiel Logistik UG: تدابير تحفظية منذ 22 سبتمبر 2026، وقد عُيّن
          مدير مؤقت.
          Nordlicht Handels GmbH: توجد شركتان بهذا الاسم، ولا إعلان لأي منهما.
          أي مدينة هي مدينتكم؟

المستخدم: هامبورغ. ومن فضلك راقب الثلاث جميعًا من الآن فصاعدًا.

الوكيل:   [watch_company name="Nordlicht Handels GmbH" city="Hamburg"]
          [watch_company company_id="cmp_3n8Kd2ZpQv"]
          [watch_company company_id="cmp_7Yb3Rt5Mn"]
          تم. ستصلك رسالة خطاف ويب بمجرد ظهور إعلان جديد.

الخطوة المهمة هي الثالثة: عندما يكون الاسم ملتبسًا يسأل الوكيل بدلًا من أن يختار. وهذا بالضبط ما صُمم له نص الخطأ في الأداة.

الصلاحيات

يحمل كل مفتاح صلاحيات. افتراضيًا يستطيع قراءة الإعلانات والشركات والإحصاءات؛ أما الكتابة في قائمة المراقبة فيجب تفعيلها بشكل منفصل.

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

معالجة الأخطاء

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

{
  "content": [
    {
      "type": "text",
      "text": "No unique match: 2 companies are called \"Nordlicht Handels GmbH\" (Hamburg, Kiel). Ask the user for the city or the register number and call check_counterparty again. Do not pick one yourself."
    }
  ],
  "isError": true
}

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

الحدود

تنطبق الحدود نفسها المطبقة على واجهة REST: 120 استدعاء أداة في الدقيقة لكل مفتاح، وما لا يزيد على 31 يومًا في كل بحث في الإعلانات، و24 شهرًا في الإحصاءات. وللحصول على قيم أعلى يكفي بريد إلكتروني.

تجاوز الحد لا ينتج خطأً صارمًا بل نتيجة نصية تذكر متى يمكن المتابعة. وعلى الوكلاء عندئذ أن ينتظروا لا أن يستدعوا من جديد فورًا.

البيانات والمسؤولية

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

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

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

التشغيل

يعمل الخادم على البنية التحتية نفسها التي تعمل عليها واجهة REST. تُعلن نوافذ الصيانة بالبريد الإلكتروني إلى العنوان المخزن، والتغييرات في مخططات الأدوات إضافية فقط.

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

الدعم

للأسئلة والحدود الأعلى والقوالب أو الأدوات الخاصة بسير عمل معين: [email protected] أو نموذج الاتصال.

إذا كنت تفضل العمل مباشرة عبر HTTP العادي، فالبيانات نفسها موثقة بوصفها واجهة REST في وثائق الواجهة البرمجية. يشترك المساران في المفاتيح والحدود والعقد.