دليل البدء مع MCP Starter Kit: ربط واجهات API الخلفية الخاصة بك بأمان مع وكلاء الذكاء الاصطناعي

MCP Starter Kit هو هيكل مشروع (scaffold) غير مرتبط بمشروع معين، يُستخدم لبناء خادم MCP (Model Context Protocol) آمن وجاهز للنشر لأي مشروع: كل أداة تُقابل نقطة نهاية (endpoint) في الخلفية، ويتم التوثيق باستخدام مفتاح API + نطاقات (scopes)، لربط وكلاء الذكاء الاصطناعي (Claude Desktop/Web، أو ChatGPT، أو وكلاء مخصصة) بواجهات API الخاصة بخلفيتك. إذا كنت تريد فقط تجربة أدوات جاهزة، فهو غير مناسب لك؛ إذ يتطلب أن تمتلك واجهة API خلفية، وأن تكون قادراً على استضافة الخدمة، وأن تقبل سير عمل البناء والنشر.

لمن هذا مناسب

• المطورون الذين يرغبون في تمكين وكلاء مثل Claude وChatGPT من استدعاء واجهات API الخلفية الخاصة بهم بأمان.
• الفرق التي تحتاج إلى أداة لكل نقطة نهاية، مع التحكم في الصلاحيات باستخدام مفتاح API + نطاقات (scopes)؛ الوضع الافتراضي هو القراءة فقط، ما لم تضف صراحةً نطاق (scope) للكتابة.
• السيناريوهات التي تحتاج إلى طريقتي وصول: عبر الإنترنت (Streamable HTTP، متعدد العملاء) وClaude Desktop (stdio)، أو بين توثيق OAuth 2.0 عديم الحالة (PKCE S256) ومفتاح API في الترويسة (header).
• غير مناسب لـ: المستخدمين الذين لا يمتلكون واجهة API خلفية، أو لا تتوفر لديهم شروط استضافة TLS، أو لا يرغبون في إجراء أي تعديلات على الكود أو الإعدادات. لا توضح الوثائق الرسمية تفاصيل تكلفة الاستضافة أو متطلبات بيئة التشغيل، وهذه النقاط المجهولة يجب عليك التحقق منها بنفسك.

إتمام المحاولة الأولى في 3 دقائق

يُنصح في المحاولة الأولى بالبدء ببناء الهيكل نفسه واختبار الاتصال به (يحدث استدعاء نقاط النهاية الفعلية بعد تكوين الأدوات):

1. المتطلبات المسبقة: تثبيت Node/npm؛ وتجهيز نطاق يدعم TLS (يجب استضافة الخدمة خلف TLS، والمسار هو /mcp).
2. اتبع مسار القوالب في ملف README: انتقل إلى templates/، وأعد تسمية gitignore إلى .gitignore، واستبدل __PROJECT__ باسم مشروعك، واملأ ملف .env، وأضف أدواتك في src/server.ts.
3. شغّل أمر البناء المذكور رسمياً:

npm install && npm run build

1. استضف الخدمة خلف TLS (المسار /mcp)، ثم اتصل من Claude Desktop باستخدام mcp-remote وتحقق من الاتصال مرة واحدة (تهيئة الاتصال إجراء منخفض المخاطر، ويتم التحقق من المفتاح لدى الخلفية عند initialize):

npx -y mcp-remote https://<domain>/mcp --header "Authorization: Bearer <key>"

إشارة النجاح: يكمل العميل عملية initialize وينجح التحقق من المفتاح لدى الخلفية (تنص الوثائق الرسمية صراحة على أن هذا يمنع الطلبات غير الموثقة عند التهيئة). أما في Claude Web، فيُستخدم موصل مخصص (custom connector) بعنوان URL هو /mcp وترويسة x-api-key. ملاحظة: قيم <domain> و<key> في الأوامر أعلاه هي قيم حقيقية يجب عليك استبدالها؛ وتعبئة المفاتيح في .env تُعد كتابةً في الحالة المحلية وليست عملية قراءة فقط.

حالات الاستخدام

1. استدعاء نقاط النهاية للقراءة فقط في خلفيتك باستخدام Claude Desktop: بعد إتمام البناء والاستضافة خلف TLS وفق المسار الرئيسي أعلاه، اتصل بـ /mcp من Claude Desktop عبر mcp-remote باستخدام مفتاح Bearer. وبما أن الوضع الافتراضي هو القراءة فقط، فلن تؤدي الاستدعاءات إلى عمليات كتابة في الخلفية ما لم تضف صراحةً نطاق (scope) للكتابة — هذا سلوك مُعلن رسمياً، لكنه لا يعني انعدام المخاطر تماماً؛ إذ لا يزال المفتاح يُتحقق منه لدى الخلفية ويُمرر عبر mcp-remote.
2. الوصول إلى الخدمة نفسها عبر موصل مخصص في Claude Web: قم بتكوين موصل مخصص في Claude Web باستخدام عنوان URL هو /mcp مع ترويسة x-api-key. يمكن التأكد من وصولك حتى خطوة إنشاء الاتصال؛ أما تنسيق مخرجات أداة معينة فيعتمد على كيفية تنفيذك لتلك الأداة في src/server.ts، ولم تقدم الوثائق الرسمية أمثلة على أدوات محددة، لذا لا يمكن التنبؤ بذلك أكثر.

حدود الاستخدام

• طبيعة القراءة/الكتابة: القالب افتراضياً للقراءة فقط، وإمكانية الكتابة تتطلب إضافة نطاق (scope) صراحةً؛ وعمليات الكتابة هي عمليات كتابة عن بُعد، فيجب التأكد من الآثار الجانبية قبل التنفيذ.
• بيانات الاعتماد: يتم التوثيق باستخدام مفتاح API (أو اختيارياً OAuth 2.0 عديم الحالة بنمط PKCE S256)؛ ويجب تعبئة الإعدادات في .env، وهو ما يُعد حالة محلية حساسة.
• السجلات (Logs): تُكتب سجلات التدقيق إلى stderr، بينما يُترك stdout لـ JSON-RPC؛ انتبه للفرق بين القناتين أثناء تصحيح الأخطاء.
• حدود آليات الأمان: يتم التحقق من المفتاح عند initialize لمنع الاستخدام غير الموثق؛ والوضع الافتراضي للقراءة فقط والتحقق عند initialize يعنيان عدم تنفيذ عمليات الكتابة والتحقق من المفتاح، لكنهما لا يعنيان عدم وجود اتصال بالإنترنت أو عدم وجود حدود خصوصية أخرى.
• معلومات غير مؤكدة: لم توضح الوثائق الرسمية تنسيق ملفات التكوين التفصيلي لكل عميل، أو متطلبات منصات الاستضافة، أو أمثلة تنفيذ لنقاط نهاية/أدوات محددة؛ ويجب عليك مراجعة المستودع والتأكد من هذه الأمور بنفسك قبل الاستخدام الأول.