بناء MCP server مخصص لاحتياج عملك: درس كامل 2026

Model Context Protocol (MCP) هو البروتوكول المفتوح من Anthropic الذي يسمح لأي وكيل ذكاء اصطناعي بالوصول إلى أدوات وموارد خاصة بشركتك. بدلاً من تكديس الأدوات في كود الوكيل، تكتب MCP server مرة واحدة، ويتصل به Claude Code، Claude Desktop، VS Code، وأي عميل آخر يدعم البروتوكول. سنبني في هذا الدرس MCP server يخدم منصة تجارة إلكترونية في القاهرة.

1. ما هو MCP بالضبط؟

بروتوكول JSON-RPC 2.0 يقدم ثلاثة مفاهيم: Tools (دوال يستدعيها الوكيل)، Resources (ملفات أو بيانات يقرأها)، Prompts (قوالب جاهزة). الاتصال عبر stdio أو HTTP أو WebSocket. الإصدار الحالي 2025-11 (نوفمبر 2025).

2. أدوات SDK الرسمية

• @modelcontextprotocol/sdk للـ TypeScript/JavaScript.
• mcp لـ Python.
• أمثلة جاهزة: filesystem، github، slack، postgres على الـ MCP servers registry.

3. تجهيز المشروع

mkdir mcp-shop-server && cd mcp-shop-server
npm init -y
npm install @modelcontextprotocol/sdk zod pg
npm install -D typescript @types/node tsx
echo "{\"compilerOptions\":{\"target\":\"ES2022\",\"module\":\"NodeNext\"}}" > tsconfig.json

4. الهيكل الأساسي للخادم

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
import pg from 'pg';

const db = new pg.Pool({ connectionString: process.env.DATABASE_URL });

const server = new Server(
  { name: 'shop-server', version: '1.0.0' },
  { capabilities: { tools: {}, resources: {} } }
);

5. تعريف Tool: البحث عن طلبات عميل

server.setRequestHandler('tools/list', async () => ({
  tools: [{
    name: 'search_orders',
    description: 'البحث عن طلبات عميل بالاسم أو رقم الهاتف. ترجع آخر 10 طلبات مرتبة تنازلياً.',
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'اسم العميل أو رقم هاتفه' },
        limit: { type: 'number', default: 10 }
      },
      required: ['query']
    }
  }]
}));

server.setRequestHandler('tools/call', async (req) => {
  if (req.params.name === 'search_orders') {
    const { query, limit = 10 } = req.params.arguments;
    const r = await db.query(
      'SELECT id, total, status, created_at FROM orders WHERE customer_name ILIKE $1 OR customer_phone = $1 ORDER BY created_at DESC LIMIT $2',
      [`%${query}%`, limit]
    );
    return { content: [{ type: 'text', text: JSON.stringify(r.rows) }] };
  }
});

6. تعريف Resource: كتالوج المنتجات

server.setRequestHandler('resources/list', async () => ({
  resources: [{
    uri: 'shop://products/active',
    name: 'كتالوج المنتجات النشطة',
    mimeType: 'application/json'
  }]
}));

server.setRequestHandler('resources/read', async (req) => {
  if (req.params.uri === 'shop://products/active') {
    const r = await db.query('SELECT id, name, price, stock FROM products WHERE active = true');
    return { contents: [{ uri: req.params.uri, mimeType: 'application/json', text: JSON.stringify(r.rows) }] };
  }
});

7. الاتصال بالعميل

const transport = new StdioServerTransport();
await server.connect(transport);

إعدادات Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "shop": {
      "command": "tsx",
      "args": ["/srv/mcp-shop-server/index.ts"],
      "env": { "DATABASE_URL": "postgres://..." }
    }
  }
}

8. الأمان: حدود الصلاحيات

• استعمل مستخدم PostgreSQL بصلاحية SELECT فقط للأدوات للقراءة، وINSERT محدود لتلك التي تكتب.
• أضف حقل tenant_id في كل استعلام إن كان لديك أكثر من زبون على نفس قاعدة البيانات.
• سجّل كل استدعاء أداة في جدول audit_log.
• قيّد طول النصوص العائدة (max 10000 حرف) لتجنب فيضان السياق.

9. النشر على Coolify

أنشئ Dockerfile، ادفع إلى Forgejo ذاتي الاستضافة، اربط Coolify ليبني وينشر تلقائياً عند كل push. اختر « Service » غير « Web Application » لأن MCP يستخدم stdio عادةً، أو HTTP إن فعّلته. حدد المتغيرات DATABASE_URL وARGO_TOKEN عبر Coolify Secrets.

10. اختبار MCP server

npx @modelcontextprotocol/inspector node index.js

تتح لك Inspector UI لاختبار كل tool وresource يدوياً قبل ربط Claude.

11. الأخطاء الشائعة

12. أسئلة متكررة

هل أستطيع كتابة MCP server بـ Python؟ نعم. pip install mcp ونفس مفاهيم Tools/Resources.

كم عميلاً يمكن أن يتصل بنفس الخادم؟ stdio = عميل واحد، HTTP = عدة عملاء.

كيف أحدّث الخادم دون كسر العميل؟ اتبع semantic versioning، أضف لا تحذف.

للاستزادة

• Claude Agent SDK: الدليل الكامل
• بناء وكيل مخصص
• تنسيق Sub-agents