> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# خادم TokenLab MCP

> ربط عملاء MCP باكتشاف نماذج TokenLab والأسعار والمحادثة المتوافقة مع OpenAI ونقاط الاستدلال الأصلية.

يمنح [خادم TokenLab MCP](https://github.com/hedging8563/tokenlab-mcp-server) الوكلاء المتوافقين مع MCP اكتشافًا مباشرًا للنماذج والأسعار وChat Completions المتوافق مع OpenAI وأدوات الاستدلال الأصلية.

استخدمه عندما يحتاج الوكيل إلى مقارنة النماذج أو فحص تنسيقات الطلبات أو التحقق من الأسعار أو استدعاء TokenLab عبر OpenAI Chat Completions أو Responses أو Anthropic Messages أو Gemini generateContent.

<Note>
  لا تتطلب أدوات الكتالوج العام مفتاح API خاصًا بـ TokenLab. اضبط `TOKENLAB_API_KEY` لاستخدام أدوات الاستدلال الأربع المدفوعة.
</Note>

## ما الذي يوفره

* اكتشاف مباشر للنماذج من `https://api.tokenlab.sh/v1/models`.
* البحث عن تفاصيل النموذج من `/v1/models/{model}`.
* البحث عن الأسعار من `/v1/models/{model}/pricing`.
* نظرة عامة على API قابلة للقراءة من قبل الوكيل من `https://api.tokenlab.sh/llms.txt`.
* توجيهات حول عائلات نقاط النهاية للمحادثات المتوافقة مع OpenAI، وResponses، وAnthropic Messages، وGemini، والوسائط، والصوت، والتضمينات (embeddings)، وإعادة التصنيف (rerank)، والترجمة.
* استدلال اختياري عبر Chat Completions المتوافق مع OpenAI وResponses وAnthropic Messages وGemini generateContent.

## التثبيت من GitHub

قم باستنساخ المستودع العام وتثبيت التبعيات:

```bash theme={null}
git clone https://github.com/hedging8563/tokenlab-mcp-server.git
cd tokenlab-mcp-server
npm install
npm test
```

ابدأ تشغيل الخادم عبر stdio:

```bash theme={null}
npm start
```

متغير البيئة الاختياري `TOKENLAB_API_BASE` يكون افتراضياً `https://api.tokenlab.sh`.

## التثبيت في Codex

أضف خادم الكتالوج العام إلى إعدادات Codex:

```bash theme={null}
codex mcp add tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server
```

ابدأ جلسة Codex جديدة بعد إضافة الخادم. لا تتطلب أدوات الكتالوج العام `TOKENLAB_API_KEY`.

لتمكين أدوات الاستدلال، أضف مفتاح TokenLab API عند تسجيل الخادم:

```bash theme={null}
codex mcp add --env TOKENLAB_API_KEY=your-tokenlab-api-key tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server
```

## التثبيت في Cline

ثبّت خادم stdio المنشور باستخدام Cline CLI:

```bash theme={null}
cline mcp add tokenlab --yes -- npx -y @tokenlabai/mcp-server
```

تم التحقق من الأمر باستخدام Cline CLI ويكتمل دون تحذيرات إعداد. تعمل أدوات الكتالوج العامة مباشرة؛ اضبط `TOKENLAB_API_KEY` في بيئة Cline عند الحاجة إلى أدوات الاستدلال.

## إعداد Claude Desktop

أضف حزمة npm المنشورة إلى إعدادات عميل MCP:

```json theme={null}
{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"]
    }
  }
}
```

أعد تشغيل عميل MCP بعد حفظ الإعدادات.

## Cursor وWindsurf وعملاء MCP الآخرون

استخدم نفس الأمر والوسائط في أي عميل يدعم خوادم stdio MCP:

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "@tokenlabai/mcp-server"],
  "env": {
    "TOKENLAB_API_BASE": "https://api.tokenlab.sh"
  }
}
```

إذا كان عميلك يخزن خوادم مسماة، استخدم `tokenlab-model-catalog` كاسم للخادم.

## الأدوات

| الأداة                     | الغرض                                                                                                                                            |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `list_models`              | سرد نماذج TokenLab العامة. يمكن التصفية اختيارياً باستخدام `recommended_for` مثل `image` أو `video` أو `embedding` أو `rerank` أو `translation`. |
| `get_model`                | جلب التفاصيل العامة لنموذج واحد وتنسيق الطلب المدعوم.                                                                                            |
| `get_model_pricing`        | جلب تفاصيل الأسعار العامة لنموذج واحد.                                                                                                           |
| `compare_models`           | مقارنة تفاصيل وأسعار عدة معرفات للنماذج.                                                                                                         |
| `create_chat_completion`   | استدعاء نقطة `/v1/chat/completions` المتوافقة مع OpenAI، مع دعم الرسائل متعددة الوسائط واستدعاء الأدوات. يتطلب `TOKENLAB_API_KEY`.               |
| `create_response`          | استدعاء نقطة `/v1/responses`. يتطلب `TOKENLAB_API_KEY`.                                                                                          |
| `create_anthropic_message` | استدعاء نقطة Anthropic Messages على `/v1/messages`. يتطلب `TOKENLAB_API_KEY`.                                                                    |
| `create_gemini_content`    | استدعاء نقطة Gemini الأصلية `generateContent`. يتطلب `TOKENLAB_API_KEY`.                                                                         |
| `get_api_overview`         | جلب نظرة عامة `llms.txt` الخاصة بـ TokenLab للحصول على توجيهات نقاط النهاية القابلة للقراءة من قبل الوكيل.                                       |

تعيد أدوات الاستدلال نتائج JSON عادية. يتم تعطيل البث عمدًا في استدعاءات أدوات MCP.

## سير عمل الوكيل الموصى به

1. استدعِ `list_models` عندما لا يحدد المستخدم اسماً لنموذج معين.
2. استخدم `recommended_for` للمهام غير المتعلقة بالمحادثة، مثل الصور، الفيديو، الموسيقى، 3D، تحويل النص إلى كلام (TTS)، تحويل الكلام إلى نص (STT)، التضمينات، إعادة التصنيف، أو الترجمة.
3. استدعِ `get_model` قبل إنشاء طلب غير متعلق بالمحادثة، أو إعادة محاولة طلب فاشل، أو التبديل بين عائلات نقاط النهاية.
4. استدعِ `get_model_pricing` عندما تؤثر تكلفة النموذج على اختيار المستخدم.
5. استخدم `compare_models` عندما يعتمد الاختيار على عدة نماذج مرشحة.
6. استدعِ أداة الاستدلال المطابقة لعقد API المطلوب، أو استخدم `get_api_overview` للحصول على خريطة موجزة لعائلات TokenLab API.

## توجيهات نقاط النهاية الأصلية

يدعم TokenLab المسارات المتوافقة مع OpenAI وعائلات نقاط النهاية الأصلية. يساعد خادم MCP الوكيل في اختيار المسار الصحيح قبل كتابة التعليمات البرمجية:

| العائلة                  | المسار الشائع                                                            |
| ------------------------ | ------------------------------------------------------------------------ |
| محادثة متوافقة مع OpenAI | `/v1/chat/completions`                                                   |
| Responses                | `/v1/responses`                                                          |
| Anthropic Messages       | `/v1/messages`                                                           |
| Gemini native            | `/v1beta/models/{model}:generateContent`                                 |
| الصور                    | `/v1/images/generations`, `/v1/images/edits`                             |
| الفيديو                  | `/v1/videos/generations`                                                 |
| الموسيقى                 | `/v1/music/generations`                                                  |
| 3D                       | `/v1/3d/generations`                                                     |
| الصوت                    | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| التضمينات وإعادة التصنيف | `/v1/embeddings`, `/v1/rerank`                                           |
| ترجمة النصوص             | `/v1/translations`                                                       |

## مستكشف النماذج المستضاف

يمكن للعملاء الذين يدعمون Streamable HTTP الاتصال بـ:

```text theme={null}
https://tokenlab-model-explorer.vercel.app/mcp
```

المستكشف المستضاف عام ويوفر `open_tokenlab_model_explorer` و`compare_tokenlab_models` و`generate_tokenlab_endpoint_example`. استخدم خادم npm المحلي أعلاه عند الحاجة إلى الأدوات التسع كاملة أو الاستدلال الموثق.

## الاستخدام مع مهارات TokenLab

يعد خادم MCP مفيداً في وقت التشغيل، بينما يقوم [مستودع مهارات TokenLab](https://github.com/hedging8563/tokenlab-skills) بتعليم وكلاء البرمجة كيفية إنشاء وإصلاح تعليمات التكامل البرمجية.

استخدم كلاهما عند توفرهما:

* خادم MCP: لاكتشاف النماذج الحالية، والأسعار، وتفاصيل نقاط النهاية.
* مهارة `tokenlab-api-integration`: لإنشاء أمثلة API قابلة للتشغيل ومعالجة أخطاء TokenLab المهيكلة.
* مهارة `tokenlab-model-picker`: لاختيار نماذج قوية لمهمة المستخدم.
* مهارة `tokenlab-native-endpoints`: لاتخاذ قرار بشأن استخدام مسارات Responses، أو Anthropic Messages، أو Gemini، أو الوسائط، أو الصوت، أو التضمينات، أو إعادة التصنيف، أو الترجمة.

## استكشاف الأخطاء وإصلاحها

<AccordionGroup>
  <Accordion title="لا يمكن للعميل بدء تشغيل الخادم">
    تأكد من أن إصدار Node.js هو 18.17 على الأقل، ثم شغّل `npx -y @tokenlabai/mcp-server` مرة واحدة في الطرفية لإظهار أخطاء npm أو الشبكة.
  </Accordion>

  <Accordion title="قائمة النماذج فارغة">
    تحقق من أن الجهاز يمكنه الوصول إلى `https://api.tokenlab.sh/v1/models`. إذا قمت بتجاوز `TOKENLAB_API_BASE`، فتأكد من أنه لا يتضمن شرطة مائلة في النهاية.
  </Accordion>

  <Accordion title="لا يزال الوكيل يختار معرفات نماذج قديمة">
    اطلب من الوكيل استدعاء `list_models` أو `get_model` قبل كتابة اسم النموذج بشكل ثابت (hardcoding). إن إقران خادم MCP مع `tokenlab-model-picker` يعطي نتائج أفضل.
  </Accordion>

  <Accordion title="هل يمكن لهذا الخادم استدعاء واجهات برمجة تطبيقات الاستدلال المدفوعة لـ TokenLab؟">
    نعم. اضبط `TOKENLAB_API_KEY` ثم استخدم `create_chat_completion` أو `create_response` أو `create_anthropic_message` أو `create_gemini_content`. تبقى أدوات الكتالوج والأسعار متاحة دون مفتاح.
  </Accordion>
</AccordionGroup>

## الموارد

<CardGroup cols={2}>
  <Card title="مستودع GitHub" icon="github" href="https://github.com/hedging8563/tokenlab-mcp-server">
    الكود المصدري وتعليمات الإعداد المحلي
  </Card>

  <Card title="مهارات TokenLab" icon="sparkles" href="https://github.com/hedging8563/tokenlab-skills">
    مهارات الوكيل المحدثة لتكاملات TokenLab
  </Card>

  <Card title="API كتالوج النماذج" icon="list" href="https://api.tokenlab.sh/v1/models">
    نقطة نهاية اكتشاف النماذج العامة
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    نظرة عامة على TokenLab API قابلة للقراءة من قبل الوكيل
  </Card>

  <Card title="خادم Glama MCP" icon="globe" href="https://glama.ai/mcp/servers/hedging8563/tokenlab-mcp-server">
    اعرض إدراج TokenLab MCP Server الذي تم التحقق منه
  </Card>

  <Card title="مستكشف نماذج Glama" icon="search" href="https://glama.ai/mcp/servers/hedging8563/tokenlab-openai-apps-model-explorer">
    استكشف النماذج والأسعار وأمثلة نقاط النهاية الأصلية
  </Card>

  <Card title="إدراج MCP.so" icon="compass" href="https://mcp.so/servers/tokenlab-mcp-server">
    اكتشف TokenLab في دليل AI & Agents
  </Card>

  <Card title="مستكشف النماذج المستضاف" icon="rocket" href="https://tokenlab-model-explorer.vercel.app">
    افتح مستكشف النماذج العام ونقطة نهاية MCP البعيدة
  </Card>
</CardGroup>