كيف تبني أول خادم MCP لك: دليل عملي

جدول المحتويات

محدّث يونيو 2026.

ملخص: MCP (بروتوكول سياق النماذج) هو الطريقة التي تمنح بها Claude وصولاً منظماً إلى الأدوات والبيانات الخارجية — قواعد البيانات، والملفات، وواجهات API — دون إثقال نافذة السياق. الخادم أبسط مما يبدو: ثبّت الـ SDK، وعرّف أدواتك كـ JSON schema، ونفّذ المعالجات، وتواصل عبر stdio. يمكنك جعل Claude يستدعي أدواتك المخصصة في أقل من 30 دقيقة.

[منظور المشغّل] أقوم بربط أدوات جديدة بوكلائي باستمرار، وأصبح MCP الآن الطريق المعياري للقيام بذلك بشكل نظيف. بمجرد بناء الخادم، يمكن لأي عميل متوافق — Claude Desktop، وClaude Code، وأي تطبيق يستخدم Anthropic SDK — استخدامه دون تغييرات في كود الاستدعاء. هذه هي القيمة: البناء مرة واحدة، وإعادة الاستخدام في كل مكان.

ما هو MCP في الواقع

بروتوكول سياق النماذج هو بروتوكول مفتوح يُقنّن كيفية اتصال نماذج الذكاء الاصطناعي بالسياق الخارجي والأدوات. فكّر فيه كمعيار USB-C لتكاملات الذكاء الاصطناعي: قبله، كان على كل تطبيق يريد أن يقرأ Claude قاعدة بيانات أو يستدعي واجهة API أن يخترع حله الخاص. بعده، تبني خادم MCP واحداً ويمكن لأي مضيف متوافق استخدامه.

يعرّف MCP ثلاثة أشياء يمكن للخادم تقديمها:

• الأدوات — دوال يمكن لـ Claude استدعاؤها (قراءة ملف، استعلام قاعدة بيانات، إرسال رسالة Slack)
• الموارد — بيانات يمكن لـ Claude قراءتها (مستندات، صفوف قواعد البيانات، هياكل الملفات)
• المطالبات — قوالب مطالبات قابلة لإعادة الاستخدام يمكن للمضيف حقنها

لمعظم حالات الاستخدام التشغيلية، تبني خوادم أدوات. الموارد والمطالبات تأتي لاحقاً بعد أن تعمل الأساسيات.

البنية هي عميل-خادم، حيث يتحكم العميل (Claude Desktop، Claude Code، تطبيقك المخصص) في كل شيء. الخادم سلبي — يستمع فقط لطلبات استدعاء الأدوات ويعيد النتائج.

الأجزاء الثلاثة لكل خادم MCP

كل خادم MCP تبنيه له نفس البنية:

1. كائن الخادم — يعلن اسم خادمك وإصداره وإمكانياته (أدوات، موارد، مطالبات)
2. تعريفات الأدوات — قائمة بالأدوات مع الأسماء والأوصاف وJSON schemas لمدخلاتها
3. معالجات الطلبات — الدوال التي تعمل عندما يستدعي Claude أداةً

هذا كل شيء. لا قاعدة بيانات، ولا HTTP stack، ولا طبقة مصادقة مطلوبة للبدء. الخادم الأدنى يحتوي على أقل من 30 سطراً من TypeScript.

المتطلبات المسبقة (دقيقتان)

• Node.js 18+ — تحقق مع node --version
• TypeScript 5+ (مضمّن كاعتمادية تطوير)
• عميل MCP للاختبار — Claude Desktop مجاني وأسهل طريقة لرؤية خادمك يعمل

لا تحتاج إلى مفتاح Anthropic API لتشغيل خادم MCP. المفتاح يعيش في العميل (Claude Desktop)، وليس في خادمك.

الخطوة 1: إعداد المشروع (3 دقائق)

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript tsx @types/node

أضف إلى package.json:

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts"
  }
}

أنشئ tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "strict": true
  },
  "include": ["src/**/*"]
}

الخطوة 2: كتابة الخادم الأدنى (5 دقائق)

أنشئ src/index.ts:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "my-mcp-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// أعلن عن الأدوات التي يقدمها هذا الخادم
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_word_count",
      description: "يحسب الكلمات في كتلة نص.",
      inputSchema: {
        type: "object",
        properties: {
          text: {
            type: "string",
            description: "النص لعدّ الكلمات فيه",
          },
        },
        required: ["text"],
      },
    },
  ],
}));

// معالجة استدعاءات الأدوات من العميل
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_word_count") {
    const { text } = args as { text: string };
    const count = text.trim().split(/\s+/).filter(Boolean).length;
    return {
      content: [{ type: "text", text: `عدد الكلمات: ${count}` }],
    };
  }

  throw new Error(`أداة غير معروفة: ${name}`);
});

// الاتصال عبر stdio — هكذا يتحدث Claude Desktop مع الخادم
const transport = new StdioServerTransport();
await server.connect(transport);

هذا هو الخادم الكامل. يسجّل أداةً واحدة (get_word_count) وينفّذها. البنية هي ما يهم.

الخطوة 3: البناء والتسجيل في Claude Desktop (5 دقائق)

ابنِ TypeScript:

npm run build

سجّله الآن في ملف تكوين Claude Desktop.

على macOS: ~/Library/Application Support/Claude/claude_desktop_config.json على Windows: %APPDATA%\Claude\claude_desktop_config.json

إذا لم يكن الملف موجوداً، أنشئه:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/المسار/المطلق/إلى/my-mcp-server/build/index.js"]
    }
  }
}

استخدم المسار المطلق. أعد تشغيل Claude Desktop بعد الحفظ. ستظهر أيقونة مطرقة (🔨) في حقل إدخال الرسائل — هذا يعني أن Claude اكتشف أدواتك.

الخطوة 4: بناء أداة مفيدة

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

import { readFileSync, readdirSync } from "fs";
import { join, extname } from "path";

const ALLOWED_EXTENSIONS = [".md", ".txt", ".ts", ".json", ".yaml"];
const PROJECT_DIR = process.env.PROJECT_DIR ?? process.cwd();

المنطق هو نفسه: عرّف الأدوات بـ JSON schemas دقيقة، ونفّذ المعالجات، وتحقق من المدخلات لمنع path traversal، وأعد النص للعميل.

الأخطاء التي ارتكبتها (لئلا ترتكبها)

يجب أن يكون المسار مطلقاً. المسارات النسبية في تكوين Claude Desktop لا تُحلّ كما تتوقع. استخدم دائماً المسار الكامل /home/user/....

stdio يعني عدم استخدام console.log في خادمك. يتواصل Claude Desktop مع خادمك عبر stdin/stdout. أي console.log للتصحيح يفسد تدفق JSON-RPC. سجّل إلى stderr:

process.stderr.write(`تصحيح: ${message}\n`);

أعد تشغيل Claude Desktop بعد كل تغيير في التكوين. تُحمَّل خوادم MCP عند بدء التشغيل. ملف التكوين المحرَّر لا يفعل شيئاً حتى تغلق التطبيق وتعيد فتحه.

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

كيف أستخدم خوادم MCP في الإنتاج

يعمل نمط stdio بشكل ممتاز لـ Claude Desktop وClaude Code (محلياً). لوكلاء الإنتاج — 30+ أشغّلها على Cloudflare Workers — أستخدم tool-use API من Anthropic SDK مباشرةً، لأنني أحتاج إلى مرونة التوجيه نحو Haiku مقابل Sonnet في كل خطوة.

الأنماط التي أستخدمها فعلاً:

1. أدوات التطوير المحلية — خوادم MCP لـ Claude Code تكشف أدوات خاصة بالمشروع
2. حقن السياق — خوادم MCP تُحمّل المستندات ذات الصلة مسبقاً دون نسخ يدوي
3. جسر النموذج الأولي للـ API — أبني MCP أولاً (أسرع للتكرار)، ثم أنقل المنطق إلى SDK tool-use للإنتاج

ما تبنيه بعد ذلك

بمجرد أن تتضح بنية الخادم، الأدوات المفيدة هي تلك التي تصل إلى السياق الخارجي لـ Claude:

• قارئ قاعدة البيانات — ينفّذ استعلام SQL للقراءة فقط ويعيد النتائج كـ JSON
• قارئ Slack — يجلب آخر N رسائل من قناة
• قارئ GitHub — يسرد PRs المفتوحة، يقرأ ملفاً عند commit محدد
• مغلّف API داخلي — يستدعي REST API الخاص بك مع رؤوس المصادقة المدمجة

الأسئلة الشائعة

هل أحتاج إلى مفتاح Anthropic API لبناء خادم MCP؟

لا. خادم MCP لا يستدعي Anthropic API. إنه فقط يستجيب لطلبات استدعاء الأدوات من العميل. المفتاح يعيش في العميل، وليس في الخادم.

هل يمكن لخادم MCP الخاص بي استدعاء APIs خارجية؟

نعم — المعالج هو مجرد كود TypeScript غير متزامن. استدعِ API طقس، استعلم قاعدة بيانات، اكتب في ملف. الخادم لا يهتم بما يفعله المعالج داخلياً.

ما الفرق بين نقلَي stdio وHTTP؟

stdio للخوادم المحلية — نفس جهاز Claude Desktop أو Claude Code. HTTP مع SSE للخوادم البعيدة التي يمكن نشرها كخدمة ويب. ابدأ بـ stdio؛ إنه أبسط في التصحيح.

كيف يعرف Claude متى يستدعي أداتي؟

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