يوجد 10000 خادم MCP: هذا هو ما يفصل بين الخوادم الجيدة

1. تنظيم الأدوات؛ لا تتخلص من واجهة برمجة التطبيقات (API) بأكملها

الخطأ الأكبر: تسجيل كل نقطة نهاية لواجهة برمجة التطبيقات (API) كأداة MCP. لدى Botoi أكثر من 150 نقطة نهاية. إذا كانت جميعها أدوات MCP، فسيستهلك بيان الأداة أكثر من 30000 رمزًا مميزًا قبل المحادثة يبدأ. وهذا يترك مساحة أقل لسؤال المستخدم الفعلي، ويزيد من فرصة اختيار النموذج للسؤال أداة خاطئة، وتبطئ كل طلب لأن النموذج يجب أن يقرأ مئات الأدوات التعاريف.

يسجل Botoi 49. معايير الاختيار: الأدوات التي يستخدمها المطورون أثناء جلسات البرمجة (DNS البحث، وفك تشفير JWT، وتوليد التجزئة)، يمكن للأدوات التي تنتج نماذج مخرجات منظمة أن تفكر في ذلك (التحقق من صحة JSON، واكتشاف معلومات تحديد الهوية الشخصية)، والأدوات التي تحفظ تبديل السياق (تشفير Base64، وبيانات تعريف URL استخراج).

// curated-tools.ts - 49 tools from 150+ endpoints
export const CURATED_TOOLS: Record<string, CuratedTool> = {
  lookup_dns: {
    path: "/v1/dns/lookup",
    method: "post",
    title: "DNS Lookup",
    description:
      "Query DNS records (A, AAAA, MX, TXT, CNAME, NS) for a domain. " +
      "Use when you need to check DNS configuration or troubleshoot domain resolution.",
    annotations: { readOnlyHint: true, openWorldHint: true },
  },
  dev_hash: {
    path: "/v1/hash",
    method: "post",
    title: "Hash Text",
    description:
      "Generate a hash (MD5, SHA-1, SHA-256, SHA-512) of input text. " +
      "Use for checksums, data integrity, or fingerprinting.",
    annotations: { readOnlyHint: true },
  },
  // ... 47 more curated tools
};

الأدوات التي لم تنجح في القطع: العمليات المجمعة ذات الحمولات الكبيرة (إنشاء PDF من HTML)، الأدوات التي تُرجع البيانات الثنائية (صورة رمز الاستجابة السريعة، والتقاط لقطة الشاشة)، والأدوات المتداخلة الوظيفة (ثلاث نقاط نهاية تجزئة مختلفة تم دمجها في نقطة واحدة). كل أداة تضيفها تكلف الرموز المميزة. تعامل مع بيان MCP الخاص بك كمنتج، وليس كمرآة لمستندات API الخاصة بك.

2. اكتب أوصاف الأدوات التي تساعد النموذج على الاختيار بشكل صحيح

يقرأ النموذج وصف أداتك ليقرر ما إذا كان سيتم استدعاؤها أم لا. وصف غامض مثل "هل "أشياء DNS" تجبر النموذج على التخمين. الوصف المحشو بتفاصيل التنفيذ يهدر الرموز المميزة على المعلومات التي لا يحتاجها النموذج.

النمط الذي يعمل: جملة واحدة تبدأ بفعل يوضح ما تفعله الأداة، متبوعةً بـ جملة ثانية تبدأ بـ "استخدم متى" والتي تصف حالة التشغيل.

أوصاف سيئة

// Bad: vague, no trigger condition
{
  name: "dns",
  description: "Does DNS stuff"
}

// Bad: too long, includes implementation details
{
  name: "dns_lookup_tool",
  description: "This tool uses the DNS-over-HTTPS protocol to query Cloudflare's 1.1.1.1 resolver via a GET request to https://cloudflare-dns.com/dns-query with an Accept header of application/dns-json. It supports A, AAAA, MX, TXT, CNAME, and NS record types and returns the raw DNS response parsed into JSON format."
}

أوصاف جيدة

// Good: verb-first, one sentence what + one sentence when
{
  name: "lookup_dns",
  description:
    "Query DNS records (A, AAAA, MX, TXT, CNAME, NS) for a domain. " +
    "Use when you need to check DNS configuration or troubleshoot domain resolution."
}

// Good: specific about capabilities and trigger condition
{
  name: "security_pii_detect",
  description:
    "Scan text for personal identifiable information (emails, phones, SSNs, credit cards). " +
    "Use when you need to audit user input or log output for sensitive data before storage."
}

الجملة الأولى مخصصة لاختيار الأداة: فهي تخبر النموذج بما تفعله الأداة وما الذي يُدخلها يقبل. الجملة الثانية مخصصة لتوضيح: عندما يمكن أن تتطابق أداتان، عبارة "استخدم متى". يساعد النموذج على اختيار النموذج المناسب.

تتبع جميع الأدوات الـ 49 الموجودة في خادم MCP الخاص بـ Botoi هذا النمط. النتيجة: تختار النماذج باستمرار الأداة الصحيحة من المحاولة الأولى، حتى عندما تكون هناك أدوات متعددة ذات إمكانيات متداخلة (على سبيل المثال، lookup_email مقابل lookup_dns لفحص سجلات MX).

3. استخدم التعليقات التوضيحية للأداة

تحدد مواصفات MCP أربعة تلميحات توضيحية: readOnlyHint, destructiveHint, idempotentHint، و openWorldHint. معظم الخوادم تتجاهلها. نماذج و العملاء الذين يحترمون هذه التلميحات يتخذون قرارات أكثر أمانًا: لن يطلقوا على الأدوات المدمرة بدونها التأكيد، سيعيدون تجربة الأدوات غير الفعالة عند الفشل، وسيحذرون المستخدمين قبل الأدوات من ذلك اتصل بالخدمات الخارجية.

// Annotations from Botoi's curated-tools.ts
lookup_dns: {
  path: "/v1/dns/lookup",
  annotations: {
    readOnlyHint: true,    // reads data, changes nothing
    openWorldHint: true,   // contacts external DNS servers
  },
},

storage_paste_create: {
  path: "/v1/paste/create",
  annotations: {
    destructiveHint: true,   // creates new data
    idempotentHint: false,   // each call creates a new paste
  },
},

dev_hash: {
  path: "/v1/hash",
  annotations: {
    readOnlyHint: true,      // pure computation
    idempotentHint: true,    // same input = same output
  },
},

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

4. كن عديم الجنسية باستخدام HTTP القابل للتدفق

تم إهمال نقل SSE (الأحداث المرسلة من الخادم) في مواصفات MCP. كان يتطلب المثابرة الاتصالات وإدارة الجلسة ومنطق إعادة الاتصال. يستبدله HTTP القابل للتدفق بالمعيار طلبات HTTP POST تحمل حمولات JSON-RPC 2.0. لا يوجد اتصال مستمر. لا توجد حالة جلسة. يعمل مع كل بنية تحتية لـ HTTP: شبكات CDN، وموازنات التحميل، وأوقات تشغيل الحافة، والأنظمة الأساسية بدون خادم.

يعمل خادم MCP الخاص بـ Botoi على Cloudflare Workers. كل طلب يخلق جديدة McpServer على سبيل المثال، يسجل جميع الأدوات الـ 49، ويتعامل مع الطلب، ويعيده. لا يوجد معرف الجلسة، لا إعادة الاتصال معالج، لا توجد حالة لإدارة بين الطلبات.

// MCP server on Cloudflare Workers with Streamable HTTP
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import {
  WebStandardStreamableHTTPServerTransport
} from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";

app.all("/mcp", async (c) => {
  const apiKey =
    c.req.header("X-API-Key") ||
    c.req.header("Authorization")?.replace("Bearer ", "");

  const server = createMcpServer(apiKey, c.env);
  const transport = new WebStandardStreamableHTTPServerTransport();
  await server.connect(transport);
  return transport.handleRequest(c.req.raw);
});

ال WebStandardStreamableHTTPServerTransport من MCP SDK يعمل مع أي وقت تشغيل الذي يدعم معايير الويب Request/Response واجهة برمجة التطبيقات: عمال Cloudflare، Deno Deploy وBun وVercel Edge Functions وNode.js 18+. إذا كنت تبدأ خادم MCP جديدًا في 2026، استخدم HTTP القابل للتدفق. إذا كنت تقوم بتشغيل خادم SSE، فقم بالترحيل قبل أن يسقط العملاء الدعم.

5. التحقق من صحة المدخلات مع المخططات

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

نهج بوتوي: ال schema-builder.ts تقرأ الوحدة تعريفات مسار OpenAPI على وقت التسجيل وتحويل كل خاصية إلى نوع Zod. يقوم MCP SDK بالتحقق من صحة المدخلات مقابل مخطط Zod قبل تشغيل معالج الأداة.

// schema-builder.ts - OpenAPI to Zod conversion
import { z } from "zod";
import { paths } from "../../openapi-paths";

function mapPropertyToZod(
  prop: OpenApiProperty,
  isRequired: boolean
): z.ZodTypeAny {
  let schema: z.ZodTypeAny;

  if (prop.enum && prop.enum.length > 0) {
    schema = z.enum(prop.enum as [string, ...string[]]);
  } else {
    switch (prop.type) {
      case "number":
      case "integer":
        schema = z.number(); break;
      case "boolean":
        schema = z.boolean(); break;
      default:
        schema = z.string(); break;
    }
  }

  if (!isRequired) schema = schema.optional();
  return schema;
}

export function buildZodSchema(
  apiPath: string,
  method: "get" | "post"
): Record<string, z.ZodTypeAny> {
  const operation = getOperation(apiPath, method);
  if (!operation) return {};

  const schema = operation.requestBody?.content?.["application/json"]?.schema;
  if (!schema?.properties) return {};

  const required = new Set(schema.required ?? []);
  const result: Record<string, z.ZodTypeAny> = {};

  for (const [key, prop] of Object.entries(schema.properties)) {
    result[key] = mapPropertyToZod(prop, required.has(key));
  }

  return result;
}

تقوم حلقة التسجيل بتمرير المخطط الذي تم إنشاؤه كـ inputSchema لكل أداة:

// server.ts - register tools with Zod schemas
for (const [toolName, tool] of Object.entries(CURATED_TOOLS)) {
  const zodSchema = buildZodSchema(tool.path, tool.method);

  server.registerTool(toolName, {
    title: tool.title,
    description: tool.description,
    inputSchema: zodSchema,
    annotations: tool.annotations,
  }, async (args: Record<string, unknown>) => {
    return callApi(tool.path, tool.method, args, apiKey, env);
  });
}

وهذا يعني أن كل أداة تحصل على التحقق من صحة الإدخال مجانًا. إذا أرسل النموذج عددًا صحيحًا حيث تكون السلسلة كما هو متوقع، تقوم MCP SDK بإرجاع خطأ منظم قبل تشغيل رمز المعالج الخاص بك. يرى النموذج الخطأ، ويصحح الإدخال، ويعيد المحاولة.

6. قم بإرجاع الأخطاء المنظمة التي يمكن للنموذج أن يفكر فيها

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

استجابة خطأ سيئة

// Bad: the model can't fix this
{
  "content": [{ "type": "text", "text": "Something went wrong" }],
  "isError": true
}

استجابة جيدة للخطأ

// Structured error the model can reason about
{
  "content": [
    {
      "type": "text",
      "text": "{\\n  \\"error\\": \\"validation_error\\",\\n  \\"message\\": \\"Invalid record type\\",\\n  \\"field\\": \\"type\\",\\n  \\"expected\\": [\\"A\\", \\"AAAA\\", \\"MX\\", \\"TXT\\", \\"CNAME\\", \\"NS\\"],\\n  \\"received\\": \\"INVALID\\"\\n}"
    }
  ],
  "isError": true
}

بوتوي callApi يلتقط المجمع الخطأ الهيكلي من REST API الأساسي و يمررها إلى استجابة MCP مع isError: true:

// server.ts - API call wrapper with structured errors
async function callApi(
  path: string,
  method: string,
  body: unknown,
  apiKey: string | undefined,
  env: Env
) {
  const headers: Record<string, string> = {
    "Content-Type": "application/json",
  };
  if (apiKey) headers["X-API-Key"] = apiKey;

  const req = new Request(\`http://internal\${path}\`, {
    method: method.toUpperCase(),
    headers,
    body: method === "post" ? JSON.stringify(body) : undefined,
  });

  const res = await appFetcher(req, env);
  const json = await res.json();

  if (!json.success) {
    return {
      content: [{
        type: "text",
        text: JSON.stringify(json.error, null, 2),
      }],
      isError: true,
    };
  }

  return {
    content: [{
      type: "text",
      text: JSON.stringify(json.data, null, 2),
    }],
  };
}

التفاصيل الرئيسية: isError: true تخبر العلامة النموذج بفشل استدعاء الأداة. JSON المنظم في text الحقل يخبرها لماذا. نماذج تم تدريبها على أنماط استخدام الأدوات سوف يقرأ الخطأ، ويحدد حقل المشكلة، ويعيد المحاولة باستخدام القيمة المصححة. خطأ عام السلاسل تجبر النموذج على التخمين أو الاستسلام.

7. أضف مصادقة دون كسر تجربة المطور

تحتاج خوادم MCP إلى المصادقة. تدعم المواصفات OAuth 2.1 لتدفقات التفويض الكاملة، ولكن معظمها تعمل أدوات المطور بشكل جيد مع إعادة توجيه مفتاح API. يضيف المطور مفتاحه إلى عميل MCP التكوين مرة واحدة؛ يستخرجه الخادم من رؤوس الطلب ويمرره إلى كل استدعاء لواجهة برمجة التطبيقات.

إليك تكوين العميل لـ Claude Desktop باستخدام مفتاح API:

// Client config: Claude Desktop
{
  "mcpServers": {
    "botoi": {
      "type": "streamable-http",
      "url": "https://api.botoi.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

يقوم الخادم باستخراج المفتاح من ملف Authorization رأس أو X-API-Key head، ثم يعيد توجيهه إلى كل استدعاء داخلي لواجهة برمجة التطبيقات:

// server.ts - extract API key from MCP request headers
app.all("/mcp", async (c) => {
  const apiKey =
    c.req.header("X-API-Key") ||
    c.req.header("Authorization")?.replace("Bearer ", "");

  // Pass the key through to every API call
  const server = createMcpServer(apiKey, c.env);
  const transport = new WebStandardStreamableHTTPServerTransport();
  await server.connect(transport);
  return transport.handleRequest(c.req.raw);
});

بدون مفتاح، لا يزال الخادم يعمل. يسمح Botoi بالوصول المجهول بمعدل 5 طلبات في الدقيقة و 100 في اليوم، وهو ما يكفي للاستخدام غير الرسمي أثناء جلسة البرمجة. باستخدام مفتاح، يحد الحجم إلى مستوى خطة المطور. يعني هذا النهج تأهيلًا خاليًا من الاحتكاك (لا يلزم الاشتراك لتجربته) مع مسار ترقية واضح عندما ينمو الاستخدام.

خادم MCP جيد مقابل خادم MCP سيء

المشهد الذي يضم 10000 خادم

حدث النمو من 1000 إلى 10000 خادم MCP في ستة أشهر بسبب استقرار البروتوكول. استبدل OAuth 2.1 أنماط المصادقة المخصصة. حل HTTP المتدفق محل SSE. مؤسسة لينكس أعطت الحوكمة الشركات الثقة لبناء خوادم الإنتاج. تم تخفيض أدوات تطوير البرامج (SDKs) بست لغات حاجز الدخول.

لكن الكمية لم تجلب الجودة. كانت معظم هذه الخوادم عبارة عن تجارب نهاية الأسبوع لم يتم تجاوزها أبدًا مرحلة "تسجيل جميع نقاط النهاية الخاصة بي ورؤية ما سيحدث". الخوادم التي يستخدمها المطورون يوميًا استثمرت في التنظيم والأوصاف والمخططات ومعالجة الأخطاء والمصادقة. هذه المناطق الخمس حيث 90٪ من فجوة سهولة الاستخدام.

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

خادم MCP الخاص بـ Botoi مفتوح للاختبار. الاتصال من Claude Desktop، Claude Code، Cursor، VS Code، أو ركوب الأمواج باستخدام التكوينات الموجودة على صفحة إعداد MCP. بيان الأداة الكامل هو في api.botoi.com/v1/mcp/tools.json, و مستندات API قم بتغطية كل نقطة نهاية خلف الأدوات.