TokenLab for Agents: نماذج قابلة للقراءة آلياً، وتسعير، وSDKs، وMCP

إن وكيل البرمجة الذي يختار معرف نموذج (model ID) من الذاكرة سينتهي به الأمر باختيار نموذج لم يعد موجوداً، ولن يكتشف ذلك إلا بعد تلقي خطأ 404 أو فاتورة مفاجئة. يوفر TokenLab MCP للوكيل كتالوجاً مباشراً للتحقق أولاً، بحيث يمكنه التأكد من المعرف، وتنسيق الطلب المقبول، والسعر قبل كتابة أي كود تكامل. لقد وصفنا الخادم في الأصل بأنه للقراءة فقط (read-only). تشير الوثائق التي تم الاطلاع عليها بتاريخ 2026-10-03 إلى خلاف ذلك، لذا فإن هذا الإصدار يصحح ذلك ويضيف سير عمل مُعدّ.

أبرز النقاط

• يحتوي خادم TokenLab MCP على ثلاثة ملفات تعريف (profiles): catalog (بدون مفتاح API)، وcore، وfull. فقط catalog هو الذي لا يتطلب مفتاحاً.
• مع وجود مفتاح، يمكنه أيضاً إرسال طلبات النماذج، وإنشاء الوسائط، ومعالجة الملفات، والتحقق من المهام غير المتزامنة (async tasks). إنه ليس للقراءة فقط.
• قم بالتوجيه بناءً على tokenlab.accepted_request_formats، وtokenlab.pricing، وtokenlab.lifecycle، وtokenlab.deliveryAvailability. لا تقم بترميز ترتيب التوصيات بشكل ثابت (hard-code).
• ملفات Gemini، وعمليات الرفع القابلة للاستئناف، وcachedContents ليست موجودة في أي ملف تعريف MCP.
• لا تقم أبداً بلصق مفتاح API في مطالبة (prompt) أو وسيط أداة (tool argument).

ما الذي يقدمه خادم TokenLab MCP لوكيل البرمجة

وفقاً لـ وثائق خادم MCP (التي تم الاطلاع عليها بتاريخ 2026-10-03)، يتيح خادم TokenLab MCP للعميل تصفح النماذج والأسعار الحالية، وإرسال طلبات النماذج، وإنشاء الوسائط، والعمل مع الملفات، والتحقق من المهام غير المتزامنة. تذكر الوثائق هذه الإمكانات:

• سرد النماذج وقراءة إمكانات نموذج واحد (list_models، get_model)
• قراءة الأسعار الحالية أو مقارنة عدة نماذج
• إرسال طلبات Chat Completions، أو Responses، أو Anthropic Messages، أو طلبات Gemini
• تقييم القرارات المكتوبة باستخدام evaluate_decisions
• إنشاء أو تحرير الصور؛ إنشاء الفيديو، الموسيقى، النماذج ثلاثية الأبعاد، الكلام، النسخ، أو الترجمة
• رفع واسترجاع الملفات من خلال API المتوافق مع OpenAI وهو /v1/files
• إنشاء التضمينات (embeddings) أو إعادة ترتيب المستندات (rerank)
• التحقق من المهام غير المتزامنة المدعومة وإلغاؤها (get_task_status للاستطلاع)

لا تدرج الوثائق أسماء الأدوات الخاصة بالتسعير أو نظرة عامة على API في هذا الإصدار. مسودتنا القديمة كانت تسمي get_model_pricing وget_api_overview. تحقق من قائمة أدوات العميل المتصل بك قبل الاعتماد على هذين الاسمين.

تعتمد توفر الأداة على ملف التعريف:

ملف التعريف	مفتاح API	يتضمن
catalog	غير مطلوب	قائمة النماذج، تفاصيل النموذج، الأسعار، المقارنات، نظرة عامة على API
core	مطلوب للمكالمات المدفوعة	أدوات الدردشة الشائعة، القرارات، الوسائط، الصوت، الملفات، المهام، التضمين، إعادة الترتيب، والترجمة
full	مطلوب للمكالمات المدفوعة	core بالإضافة إلى واجهات برمجة تطبيقات إضافية للمطورين

ابدأ بـ catalog إذا كنت تريد فقط اختياراً أفضل للنماذج. استخدم core عندما يحتاج العميل إلى إنشاء محتوى أو استدعاء نموذج.

تثبيت خادم TokenLab MCP في عميلك

تحتاج الحزمة إلى Node.js 18.17 أو أحدث وnpx. تعمل الحزمة محلياً عبر stdio، لذا لا تحتاج إلى تثبيت عالمي. قم بنسخ احتياطي لتكوينك النشط أولاً، وأضف إدخال TokenLab فقط. هذه الأوامر مأخوذة من الوثائق، التي تم الاطلاع عليها بتاريخ 2026-10-03.

Claude Code:

claude mcp add \
  --env TOKENLAB_MCP_TOOL_PROFILE=catalog \
  --scope user \
  tokenlab -- \
  npx -y @tokenlabai/mcp-server@0.6.26

Codex:

codex mcp add \
  --env TOKENLAB_MCP_TOOL_PROFILE=catalog \
  tokenlab -- \
  npx -y @tokenlabai/mcp-server@0.6.26

Cursor (~/.cursor/mcp.json أو .cursor/mcp.json):

{
  "mcpServers": {
    "tokenlab": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server@0.6.26"],
      "env": {
        "TOKENLAB_MCP_TOOL_PROFILE": "catalog"
      }
    }
  }
}

يستخدم VS Code ملف .vscode/mcp.json مع مفتاح servers و "type": "stdio". يستخدم Claude Desktop نفس شكل Cursor في claude_desktop_config.json. انسخ كلاهما من صفحة الوثائق.

لتمكين الأدوات المدفوعة، أنشئ مفتاحاً في Console → API keys واضبط كلا المتغيرين في بيئة الخادم:

{
  "env": {
    "TOKENLAB_API_KEY": "<TOKENLAB_API_KEY>",
    "TOKENLAB_MCP_TOOL_PROFILE": "core"
  }
}

ثم أعد تشغيل العميل وقم بتشغيل claude mcp list أو codex mcp list. اطلب من الوكيل استدعاء list_models. تؤكد القائمة غير الفارغة أن الحزمة بدأت ووصلت إلى TokenLab. إذا وصل مفتاح حقيقي إلى ملف مشترك، أو سجل (log)، أو سجل أوامر (shell history)، فقم بإلغائه وإنشاء مفتاح جديد.

سير عمل وكيل واحد: الاكتشاف، التحقق، الاستدعاء

هذا هو سير العمل الذي نستخدمه. تخيل وكيلاً طُلب منه إضافة إنشاء صور إلى تطبيق Node.js. كل قيمة أدناه مأخوذة من الوثائق وصفحات النماذج المباشرة التي تم الاطلاع عليها بتاريخ 2026-10-03.

1. الاكتشاف. اطلب القائمة المختصرة الحالية، باستخدام أداة MCP أو HTTP العادي:

{ "tool": "list_models", "arguments": { "recommended_for": "image" } }

curl "https://api.tokenlab.sh/v1/models?recommended_for=image"

قيم recommended_for الصالحة هي image، وvideo، وmusic، و3d، وtts، وstt، وembedding، وrerank، وtranslation. لنفترض أن الوكيل اختار nano-banana-pro.

2. التحقق من التنسيقات والسعر. استدعِ get_model، أو GET /v1/models/nano-banana-pro (API النموذج المباشر، الذي تم الاطلاع عليه بتاريخ 2026-10-03). وهو يبلغ عن:

• تنسيقات الطلب المقبولة: gemini_generate_content، والتي تعين إلى /v1beta/models/{model}:generateContent
• الإمكانات: image-edit، وimage-to-image، وtext-to-image
• السعر: per_request بقيمة 0.067 دولار أمريكي، مع نطاق سعري من 0.067 إلى 0.12 (تم تحديث التسعير في 2026-10-02T16:53:30.068Z)

الوكيل الذي افترض Chat Completions كان سيكتب الكود الخاطئ. قارن بـ gpt-image-2 (API النموذج المباشر). لا يسرد أي تنسيقات طلب مقبولة ويتم تسعيره بالرموز (token-priced) بـ 3.5 دولار للإدخال و21 دولاراً للإخراج لكل مليون رمز. يختلف شكل السعر حسب النموذج، لذا يجب على الوكيل قراءته لكل نموذج.

3. إجراء المكالمة. بالنسبة لنموذج الدردشة، يحدد فحص التنسيق نقطة النهاية. يقبل gpt-5.6-terra كلاً من openai_chat_completions وopenai_responses (API النموذج المباشر، الذي تم الاطلاع عليه بتاريخ 2026-10-03)، لذا تعمل حزمة SDK القياسية:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Reply only with OK."}],
)
print(response.choices[0].message.content)

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

لتقدير التكلفة، يفرض gpt-5.6-terra رسوماً قدرها 0.6 دولار لكل مليون رمز إدخال حتى 272 ألف رمز إدخال. لذا فإن مطالبة بـ 10,000 رمز تكلف حوالي 10,000 / 1,000,000 × 0.6 = 0.006 دولار للإدخال (تقدير، قبل الإخراج). فوق 272 ألف رمز إدخال، ينتقل الطلب بالكامل إلى المستوى الأعلى بسعر 1.2 دولار للإدخال و5.4 دولار للإخراج.

حقول API النموذج التي يجب أن يثق بها الوكيل للتوجيه

اقرأ هذه من GET /v1/models/{model} (Get a Model، الذي تم الاطلاع عليه بتاريخ 2026-10-03):

الحقل	ما يعنيه للتوجيه
tokenlab.accepted_request_formats	عائلة نقطة النهاية التي يجب استخدامها: openai_chat_completions هي /v1/chat/completions، وopenai_responses هي /v1/responses، وanthropic_messages هي /v1/messages
tokenlab.pricing / pricing_unit	السعر العام الحالي ووحدة الفوترة الخاصة به، مثل per_token أو per_image
tokenlab.max_input_tokens, max_output_tokens	حدود السياق والإخراج. بالنسبة لـ gpt-5.6-terra: 1,050,000 و128,000
tokenlab.supported_operations	العمليات مثل تحويل النص إلى صورة أو الصورة إلى فيديو
tokenlab.lifecycle	التوفر، تاريخ الإصدار، تاريخ الإيقاف، النموذج البديل
tokenlab.deliveryAvailability	الدعم verified وofficial المكون. الحقل المفقود يعني غير معروف

هناك تحذيران. أولاً، يؤكد التنسيق المقبول نقطة النهاية، ولكن يمكن أن تختلف الأدوات والحقول الفردية حسب النموذج. ثانياً، deliveryAvailability هو دعم مكون، وليس ضماناً في الوقت الفعلي. تعامل مع نتائج recommended_for كقائمة مختصرة، لأن الوثائق تقول بعدم تثبيت ترتيبها.

بالنسبة للأسعار وحدها، GET /v1/models/{model}/pricing هو نقطة النهاية الخاصة بالتسعير فقط. يمكن أن تحمل الإدخالات المعقدة مستويات (tiers). على سبيل المثال، يحتوي seedance-2.0 على أسعار إخراج تعتمد على الدقة ومدخلات الفيديو من 2.04 إلى 6.545 دولار لكل مليون رمز (API النموذج المباشر، الذي تم الاطلاع عليه بتاريخ 2026-10-03).

حقول الخطأ التي توجه الاسترداد

عند حدوث أخطاء في Chat Completions وResponses المتوافقة مع OpenAI، يسرد دليل الخطأ (الذي تم الاطلاع عليه بتاريخ 2026-10-03) الحقول الاختيارية did_you_mean، وsuggestions، وhint، وretryable، وretry_after. تعامل مع حالة HTTP وcode أولاً. قد يحمل خطأ 400 model_not_found حقل did_you_mean. اعرضه للمستخدم بدلاً من تبديل النماذج بصمت. يمكن أن يحتوي خطأ 503 all_channels_failed على retryable: false، ولن يساعد تكراره. تحتفظ Anthropic Messages وGemini بتنسيقات الخطأ الأصلية الخاصة بها.

ما لا يفعله خادم MCP

تنص الوثائق على هذه الحدود:

• لا يغير مزود النموذج الرئيسي لعميلك. استخدم دليل الإعداد الخاص بذلك العميل.
• لا يغطي ملفات Gemini، وعمليات الرفع القابلة للاستئناف، أو cachedContents. تتطلب تلك طلبات HTTP، وفقاً لـ Gemini Files and cache.
• إنه ليس المهارة (Skill). تقوم TokenLab Skill بتثبيت التعليمات باستخدام npx skills add ولا تبدأ أي خادم MCP.
• لا يقوم بالاستطلاع نيابة عنك عند انتهاء المهلة. إذا انتهت مهلة فحص الحالة، فلا تنشئ مهمة ثانية.
• لا يجعل القرارات جديرة بالثقة بحد ذاته. إجابة Noul من evaluate_decisions هي احتمال، وليست قيمة منطقية (Boolean). تحقق من صحتها مقابل حالاتك المصنفة الخاصة.

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

أين لا تزال بحاجة إلى واجهات HTTP العادية

في خط أنابيبنا، احتفظنا بنقاط نهاية اكتشاف HTTP بجانب MCP للوكلاء غير التابعين لـ MCP. https://api.tokenlab.sh/llms.txt هي نظرة عامة مضغوطة مع طلب أول، ونقاط نهاية شائعة، وتوجيهات للخطأ. الوثائق التي تم الاطلاع عليها بتاريخ 2026-10-03 لا تغطي ملف llms-full.txt أو ملفات لقطة model-data من مسودتنا السابقة. تحقق من تلك الروابط بنفسك قبل الاعتماد عليها. للحصول على الحالة المباشرة والتكاليف، راجع كتالوج النماذج العام.

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

هل أحتاج إلى مفتاح API لاستخدام خادم TokenLab MCP؟

لا، ليس للتصفح. يسرد ملف التعريف catalog النماذج والتفاصيل والأسعار والمقارنات بدون مفتاح. تتطلب طلبات النماذج المدفوعة أو الوسائط وجود TOKENLAB_API_KEY في بيئة الخادم، مع ملف التعريف core أو full.

بأي ملف تعريف MCP يجب أن أبدأ؟

ابدأ بـ catalog إذا كنت تريد فقط اختياراً أفضل للنماذج. انتقل إلى core عندما يحتاج العميل إلى استدعاء النماذج أو إنشاء الوسائط. استخدم full فقط إذا كان الوكيل يحتاج حقاً إلى واجهات برمجة تطبيقات إضافية للمطورين.

ما هي حقول النموذج التي يجب أن يثق بها الوكيل عند اختيار نموذج؟

ثق بـ accepted_request_formats لنقطة النهاية، وpricing مع وحدتها للتكلفة، وحدود الرموز، وsupported_operations، وlifecycle. تعامل مع deliveryAvailability كدعم مكون، وليس توفراً مباشراً.

لماذا حصل وكيلي على خطأ 503 all_channels_failed؟

قد لا يكون للعملية أي توريد في مستوى التسليم (Delivery tier) المختار. عندما يكون retryable هو false، لا تكرر الطلب. تحقق من التوفر باستخدام GET /v1/models واختر نموذجاً آخر بموافقة المستخدم.

هل يدعم خادم MCP ملفات Gemini أو cachedContents؟

لا. تقول الوثائق أن ملفات Gemini، وعمليات الرفع القابلة للاستئناف، وcachedContents تتطلب حالياً طلبات HTTP. تستخدم أدوات ملفات MCP واجهة برمجة التطبيقات /v1/files المتوافقة مع OpenAI.

أنشئ مفتاحاً في Console → API keys، ثم أضف ملف التعريف catalog إلى عميلك باستخدام الأوامر أعلاه.