كيف أنشأت خادم MCP متصل بـ Claude Desktop باستخدام TypeScript

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

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

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

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

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

فهم بروتوكول سياق النموذج

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

يوفر MCP عدة مزايا مقارنةً بأساليب الدمج التقليدية للذكاء الاصطناعي:

• الوعي بالسياق: تحافظ كلود على تاريخ المحادثة بالكامل عند تقديم الطلبات
• الاتصالات ثنائية الاتجاه: يدعم البروتوكول التفاعلات المعقدة بين كلود والخادم الخاص بك
• الأمان والتحكم: أنت تحدد الوظائف التي ترغب في تقديمها وكيفية معالجة الطلبات
• تجربة سلسة: يتفاعل المستخدمون مع كلود بشكل طبيعي دون الحاجة لمعرفة التكاملات الأساسية

المتطلبات الأساسية

قبل أن نبدأ في بناء خادم MCP الخاص بنا، تأكد من أن لديك ما يلي:

• Node.js (الإصدار 18 أو أحدث) مثبت
• برنامج تحرير كود مثل Visual Studio Code
• معرفة أساسية بلغة TypeScript
• تطبيق كلود المكتبي مثبت
• معرفة بـ Express.js (لبناء نقاط النهاية للخادم)

إعداد مشروع TypeScript الخاص بك

لنبدأ بإنشاء مشروع TypeScript جديد لخادم MCP الخاص بنا:

mkdir claude-mcp-server
cd claude-mcp-server
npm init -y
npm install typescript @types/node ts-node express @types/express cors @types/cors
npx tsc --init

بعد ذلك، حدث ملف tsconfig.json لتضمين هذه الإعدادات:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

تنفيذ خادم MCP

أنشئ ملفًا جديدًا يسمى server.ts في الدليل الجذر لمشروعك. سيكون هذا هو نقطة الدخول لخادم MCP الخاص بنا:

import express from 'express';
import cors from 'cors';
import { Request, Response } from 'express';

// تعريف الأنواع لبروتوكول MCP
interface MCPRequest {
  query: string;
  conversation_id: string;
  request_id: string;
  parameters?: Record<string, any>;
}

interface MCPResponse {
  response: string;
  status: 'success' | 'error';
  error?: string;
}

const app = express();
app.use(cors());
app.use(express.json());

// نقطة تفقد الصحة
app.get('/health', (req: Request, res: Response) => {
  res.status(200).json({ status: 'صحي' });
});

// نقطة نهاية MCP
app.post('/mcp', (req: Request, res: Response) => {
  try {
    const mcpRequest = req.body as MCPRequest;
    console.log('تم استلام طلب MCP:', JSON.stringify(mcpRequest, null, 2));

    // معالجة الطلب بناءً على الاستعلام
    const response = processQuery(mcpRequest);
    
    res.status(200).json({
      status: 'success',
      response
    } as MCPResponse);
  } catch (error) {
    console.error('خطأ أثناء معالجة طلب MCP:', error);
    res.status(500).json({
      status: 'error',
      error: error instanceof Error ? error.message : 'خطأ غير معروف',
      response: 'عذرًا، كان هناك خطأ أثناء معالجة طلبك.'
    } as MCPResponse);
  }
});

// دالة لمعالجة أنواع الاستعلامات المختلفة
function processQuery(request: MCPRequest): string {
  const { query, parameters } = request;

  // مثال على معالجة الاستعلام - قم بتخصيص هذا لحالة الاستخدام الخاصة بك
  switch (query) {
    case 'getCurrentTime':
      return `الوقت الحالي هو ${new Date().toLocaleTimeString()}`;
    
    case 'getWeather':
      const location = parameters?.location || 'غير معروف';
      // في تطبيق حقيقي، ستقوم هنا باستدعاء واجهة برمجة تطبيقات الطقس
      return `حالة الطقس في ${location} مشمسة حاليًا ودرجات الحرارة 72°F`;
    
    case 'calculateSum':
      if (parameters?.numbers && Array.isArray(parameters.numbers)) {
        const sum = parameters.numbers.reduce((a: number, b: number) => a + b, 0);
        return `مجموع الأرقام هو ${sum}`;
      }
      return 'معلمات غير صالحة لحساب المجموع';

    default:
      return `استعلام غير معترف به: ${query}`;
  }
}

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`خادم MCP يعمل على المنفذ ${PORT}`);
});

تشغيل خادم MCP الخاص بك

لتشغيل الخادم الخاص بك، نفذ:

npx ts-node server.ts

يجب أن يكون خادم MCP الخاص بك الآن قيد التشغيل على المنفذ 3000 (أو المنفذ المحدد الخاص بك).

الاتصال بتطبيق كلود المكتبي

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

1. افتح تطبيق كلود المكتبي
2. اذهب إلى الإعدادات (عادةً في الزاوية العليا اليمنى)
3. انتقل إلى قسم "الميزات التجريبية"
4. قم بتمكين زر التبديل "بروتوكول سياق النموذج"
5. أضف نقطة نهاية MCP جديدة مع عنوان URL http://localhost:3000/mcp
6. احفظ إعداداتك

سيكون تطبيق كلود المكتبي قادرًا الآن على التواصل مع خادم MCP المخصص الخاص بك.

اختبار التكامل

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

• "ما هو الوقت الآن؟" (يجب أن يؤدي إلى تفعيل استعلام getCurrentTime)
• "كيف تكون حالة الطقس في سان فرانسيسكو؟" (يجب أن يؤدي إلى تفعيل استعلام getWeather مع "سان فرانسيسكو" كمعلمة موقع)
• "هل يمكنك حساب مجموع 5 و10 و15 و20؟" (يجب أن يؤدي إلى تفعيل استعلام calculateSum)

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

توسيع خادم MCP الخاص بك

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

إضافة المصادقة

لتأمين خادم MCP الخاص بك، أضف المصادقة:

// middleware لمصادقة بسيطة
const authenticateMCP = (req: Request, res: Response, next: Function) => {
  const apiKey = req.headers['x-api-key'];
  if (!apiKey || apiKey !== process.env.MCP_API_KEY) {
    return res.status(401).json({
      status: 'error',
      error: 'غير مصرح',
      response: 'فشلت المصادقة'
    });
  }
  next();
};

// تطبيق middleware على نقطة نهاية MCP
app.post('/mcp', authenticateMCP, (req: Request, res: Response) => {
  // كود المعالجة الحالي
});

تنفيذ تكامل قاعدة البيانات

قم بتوصيل خادم MCP الخاص بك بقاعدة بيانات لاسترجاع أو تخزين المعلومات:

import { MongoClient } from 'mongodb';

// تهيئة اتصال قاعدة البيانات
const dbClient = new MongoClient('mongodb://localhost:27017');
let db: any;

async function connectToDb() {
  await dbClient.connect();
  db = dbClient.db('mcpDatabase');
  console.log('متصل بقاعدة البيانات');
}

connectToDb().catch(console.error);

// إضافة معالج استعلام لتفاعلات قاعدة البيانات
case 'getUserData':
  if (parameters?.userId) {
    const user = await db.collection('users').findOne({ id: parameters.userId });
    return user ? JSON.stringify(user) : 'المستخدم غير موجود';
  }
  return 'معرف المستخدم غير صالح';

إضافة دعم الويب هوك

تنفيذ وظيفة الويب هوك لإخطار الخدمات الخارجية:

case 'sendNotification':
  if (parameters?.message && parameters?.destination) {
    // استدعاء خدمة الإخطار الخارجية
    await fetch('https://your-webhook-url.com', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: parameters.message })
    });
    return `تم إرسال الإخطار إلى ${parameters.destination}`;
  }
  return 'معلمات الإخطار غير صالحة';

أفضل الممارسات لتطوير خادم MCP

1. التعامل مع الأخطاء برشاقة: قم دائمًا بالتقاط الاستثناءات وعودة رسائل خطأ معلوماتية
2. تنفيذ التسجيل: قم بتسجيل جميع الطلبات والردود لأغراض التصحيح والتدقيق
3. استخدم واجهات TypeScript: حدد واجهات واضحة لجميع الهياكل البيانات
4. حدد أوقات الانتظار: نفذ أوقات الانتظار للطلبات لمنع العمليات المعلقة
5. تحقق من المدخلات: تحقق بعناية من جميع معلمات المدخلات قبل المعالجة
6. إضافة اختبارات وحدة: اختبر معالجات الاستعلام الخاصة بك بدقة لضمان الموثوقية

الخاتمة

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

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

ابدأ في استكشاف الإمكانيات من خلال توسيع خادمك بمعالجات استعلام إضافية محددة لحالات الاستخدام الخاصة بك، وشارك تجاربك مع مجتمع مطوري MCP المتزايد.