بناء خوادم MCP عديمة الحالة باستخدام TypeScript: دليل مواصفة 2026-07-28

mkdir kb-mcp-server && cd kb-mcp-server
pnpm init
pnpm add @modelcontextprotocol/server@beta zod
pnpm add -D typescript tsx @types/node

npx tsc --init \
  --target ES2023 \
  --module NodeNext \
  --moduleResolution NodeNext \
  --strict

mkdir src && touch src/index.ts

{
  "scripts": {
    "start": "tsx src/index.ts",
    "build": "tsc"
  }
}

import { McpServer } from "@modelcontextprotocol/server/mcp.js";
import { StreamableHttpServerTransport } from "@modelcontextprotocol/server/streamable-http.js";
import { z } from "zod";
import http from "node:http";
 
// مخزن في الذاكرة للتعليم. استبدله بقاعدة بيانات حقيقية في الإنتاج.
const articles = new Map([
  ["001", { title: "البدء مع MCP", content: "MCP بروتوكول...", tags: ["mcp", "intro"] }],
  ["002", { title: "أنماط التصميم عديمة الحالة", content: "الخدمات عديمة الحالة تُزيل...", tags: ["architecture"] }],
]);
 
const server = new McpServer({
  name: "kb-server",
  version: "2.0.0",
});
 
server.registerTool(
  "search-docs",
  {
    description: "بحث نصي كامل في قاعدة المعرفة.",
    inputSchema: z.object({
      query: z.string().describe("مصطلحات البحث"),
      limit: z.number().int().min(1).max(20).default(5),
    }),
  },
  async ({ query, limit }) => {
    const q = query.toLowerCase();
    const results = [...articles.entries()]
      .filter(([, a]) => a.title.toLowerCase().includes(q) || a.content.toLowerCase().includes(q))
      .slice(0, limit)
      .map(([id, a]) => ({ id, title: a.title, tags: a.tags }));
 
    return {
      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
    };
  }
);
 
server.registerTool(
  "get-article",
  {
    description: "استرداد مقالة واحدة عبر معرّفها.",
    inputSchema: z.object({
      id: z.string().describe("معرّف المقالة"),
    }),
  },
  async ({ id }) => {
    const article = articles.get(id);
    if (!article) {
      return {
        isError: true,
        content: [{ type: "text", text: `المقالة ${id} غير موجودة` }],
      };
    }
    return {
      content: [{ type: "text", text: JSON.stringify({ id, ...article }, null, 2) }],
    };
  }
);

const transport = new StreamableHttpServerTransport({ stateless: true });
await server.connect(transport);
 
const httpServer = http.createServer(async (req, res) => {
  // يوجّه النقل server/discover وtools/call وtasks/get وغيرها تلقائيًا.
  await transport.handleRequest(req, res);
});
 
httpServer.listen(3000, () => {
  console.log("خادم KB MCP → http://localhost:3000/mcp");
});

npx @modelcontextprotocol/inspector@beta http://localhost:3000/mcp

server.registerTool(
  "get-article",
  {
    description: "استرداد مقالة واحدة عبر معرّفها.",
    inputSchema: z.object({ id: z.string() }),
  },
  async ({ id }, context) => {
    const clientName = context.meta?.clientInfo?.name ?? "غير معروف";
    const clientVersion = context.meta?.clientInfo?.version ?? "?";
    console.log(`[${clientName}@${clientVersion}] get-article id=${id}`);
 
    const article = articles.get(id);
    if (!article) {
      return { isError: true, content: [{ type: "text", text: `غير موجود: ${id}` }] };
    }
    return { content: [{ type: "text", text: JSON.stringify({ id, ...article }) }] };
  }
);

import { TasksExtension } from "@modelcontextprotocol/server/extensions/tasks.js";
 
const tasks = new TasksExtension(server);
 
server.registerTool(
  "export-collection",
  {
    description: "تصدير جميع المقالات المطابقة لوسم معين كملف JSON.",
    inputSchema: z.object({
      tag: z.string().describe("الوسم لتصفية المقالات"),
    }),
  },
  async ({ tag }) => {
    const task = tasks.create(async (taskCtx) => {
      await taskCtx.updateStatus("running", "جمع المقالات...");
 
      const matching = [...articles.entries()].filter(([, a]) => a.tags.includes(tag));
      await taskCtx.updateStatus("running", `تم إيجاد ${matching.length} مقالة. جاري التعبئة...`);
 
      // محاكاة عمل غير متزامن (استعلام قاعدة بيانات، ضغط، رفع، إلخ)
      await new Promise((r) => setTimeout(r, 2000));
 
      const payload = JSON.stringify(Object.fromEntries(matching), null, 2);
      await taskCtx.complete({ data: payload, filename: `${tag}-export.json` });
    });
 
    // إعادة معرّف المهمة فورًا — العميل يستفسر عبر tasks/get
    return { type: "task", taskId: task.id };
  }
);

import { InputRequiredResult } from "@modelcontextprotocol/server/mcp.js";
 
server.registerTool(
  "create-article",
  {
    description: "إنشاء مقالة جديدة في قاعدة المعرفة.",
    inputSchema: z.object({
      title: z.string(),
      content: z.string(),
      tags: z.array(z.string()),
      confirmed: z.boolean().optional().describe("مرّر true بعد تأكيد المستخدم"),
    }),
  },
  async ({ title, content, tags, confirmed }) => {
    if (!confirmed) {
      return new InputRequiredResult({
        message: `إنشاء مقالة "${title}" بوسوم [${tags.join("، ")}]؟ أجب بنعم أو لا.`,
        schema: z.object({ confirmed: z.boolean() }),
      });
    }
 
    const id = String(articles.size + 1).padStart(3, "0");
    articles.set(id, { title, content, tags });
 
    return {
      content: [{ type: "text", text: `تم إنشاء المقالة ${id}: "${title}"` }],
    };
  }
);

upstream standard { server kb-mcp-1:3000; server kb-mcp-2:3000; server kb-mcp-3:3000; }
upstream heavy    { server kb-mcp-heavy:3000; }
 
server {
    listen 80;
    location /mcp {
        set $pool standard;
        if ($http_mcp_name = "export-collection") {
            set $pool heavy;
        }
        proxy_pass http://$pool;
    }
}

npx @modelcontextprotocol/codemod@beta v1-to-v2 ./src

version: "3.9"
 
services:
  kb-mcp-1:
    build: .
    environment:
      NODE_ENV: production
 
  kb-mcp-2:
    build: .
    environment:
      NODE_ENV: production
 
  kb-mcp-3:
    build: .
    environment:
      NODE_ENV: production
 
  nginx:
    image: nginx:alpine
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    ports:
      - "80:80"

upstream mcp_pool {
    server kb-mcp-1:3000;
    server kb-mcp-2:3000;
    server kb-mcp-3:3000;
}
 
server {
    listen 80;
    location /mcp {
        proxy_pass http://mcp_pool;
    }
}

pnpm start

npx @modelcontextprotocol/inspector@beta http://localhost:3000/mcp