# موقعك جاهز للوكلاء: llms.txt وصفحات Markdown وOpenAPI وapi-catalog وبطاقات خوادم MCP

_2026-10-03 · ما الذي ينشره موقع جاهز للوكلاء: llms.txt، ونسخ Markdown للصفحات، وOpenAPI، وapi-catalog وفق RFC 9727، وبطاقة خادم MCP، مع shager.ai مثالًا._

الموقع الجاهز للوكلاء يمنح البرمجيات طريقًا قصيرًا ومتوقعًا من سؤال «ما هذا؟» إلى سؤال «كيف أستخدمه؟». عمليًا يعني ذلك خمسة ملفات أو أعراف: ملخصًا في `/llms.txt`، ونسخًا نظيفة بصيغة Markdown من كل صفحة، ووصفًا للـ API بصيغة OpenAPI، وملف `/.well-known/api-catalog` وفق RFC 9727 يشير إليه، وبطاقة خادم MCP تشرح طريقة الاتصال. لا شيء منها صعب النشر. ومعًا تتيح للوكيل أن يجد المنتج ويفهمه ويبدأ استخدامه من دون أن ينسخ إنسان الروابط إلى محادثة.

سأستخدم shager.ai مثالًا تطبيقيًا طوال المقال، لأن كل جزء موصوف هنا يعمل عليه فعلًا، ويمكنك جلب كل ملف بالأمر `curl` وأنت تقرأ.

## لماذا نتعب أنفسنا إن لم يتعهد أي محرك بقراءة هذه الملفات؟

لنبدأ بالصراحة. `llms.txt` مقترح، لا معيار مُعتمد، ولا أعلم أن أي مزود نماذج كبير التزم علنًا باستخدامه في الاسترجاع. أما api-catalog فهو RFC حقيقي من IETF، وبطاقات خوادم MCP امتداد مقبول في MCP، لكن تبنّي برامج الزحف والعملاء لها ما زال في بدايته.

الحجة للقيام بذلك رغم كل شيء حجة عملية. يصل الوكلاء إلى المواقع أكثر فأكثر لأن شخصًا طلب منهم ذلك، كأن يقول «سجّل في هذا واربطه». في تلك اللحظة يجلب الوكيل الصفحات مباشرة. الموقع الذي يرد بـ Markdown نظيف، مع وصف صريح للـ API ووصفة للاتصال، يُستخدم بالشكل الصحيح. والموقع الذي يرد بـ 400 KB من JavaScript يُخمَّن تخمينًا.

## llms.txt: الباب الأمامي

الصيغة معرّفة في [llmstxt.org](https://llmstxt.org/). إنها ملف Markdown في `/llms.txt` يتضمن عنوان H1 باسم الموقع (الجزء الإلزامي الوحيد)، وملخصًا في اقتباس، ونصًا حرًا اختياريًا، وأقسام H2 تضم قوائم روابط مع ملاحظات قصيرة. والقسم المعنون «Optional» يحدد الروابط التي يمكن للوكيل تخطيها حين يحتاج إلى سياق أقصر.

يتبع ملف Shager هذا الشكل. يبدو أعلاه هكذا:

```markdown
# Shager

> Shager (שגר) is agent-first distribution infrastructure for agencies and
> marketers: your agent creates, Shager ships it everywhere. ...

## For AI agents
- MCP server: https://app.shager.ai/api/mcp (OAuth sign-in for any MCP client that supports it, or Authorization: Bearer <api key>)
- REST API: https://app.shager.ai/api/v1 ...
- Self sign-up: POST https://app.shager.ai/api/v1/agent/signup ...
```

بعض الخيارات تستحق التقليد. قسم الوكلاء يأتي قبل صفحات التسويق، لأن الوكيل الذي يقرأ الملف يريد في الغالب أن يتصرف. والأسعار مذكورة بأرقام صريحة في الملف نفسه لا خلف رابط. والقيود مذكورة بوضوح (مثلًا، تبقى منشورات TikTok خاصة إلى أن يوافق TikTok على التطبيق)، كي لا يَعِد الوكيلُ المستخدمَ بشيء لا يستطيع المنتج فعله بعد. وهناك ملف مرافق هو `/llms-full.txt` يضم المحتوى كله في ملف واحد للوكلاء الذين يفضّلون جلبًا واحدًا.

## نسخة Markdown من كل صفحة

يقترح المقترح نفسه تقديم نسخة Markdown نظيفة من كل صفحة، ويوصي بالإعلان عنها عبر `rel="alternate"` و`type="text/markdown"`، إضافة إلى `rel="describedby"` يشير إلى ملف `llms.txt` الذي يغطي الصفحة. ويمكن أن يكون كلاهما عنصر `<link>` في HTML أو ترويسة `Link` في HTTP.

يفعل Shager ذلك بطريقتين. لكل صفحة توأم بصيغة Markdown تحت `/md/`، فالصفحة `/en/pricing` موجودة أيضًا في `/md/en/pricing`. وأي طلب للرابط العادي مع `Accept: text/markdown` يتلقى Markdown مباشرة:

```bash
curl -s -H "Accept: text/markdown" https://shager.ai/en/pricing | head -5
```

وكل صفحة HTML ترسل أيضًا ترويسة `Link` تعلن عن بدائلها:

```http
link: </.well-known/api-catalog>; rel="api-catalog",
      </llms.txt>; rel="describedby"; type="text/plain",
      </md/en/agents>; rel="alternate"; type="text/markdown"
```

تفصيل مهم للبحث: ردود Markdown تحمل `x-robots-tag: noindex`، كي لا تفهرس محركات البحث نسختين من كل صفحة. Markdown للوكلاء، وتبقى صفحة HTML هي الصفحة المرجعية للناس ولنتائج البحث.

## OpenAPI: العقد

لكل ما سيستدعيه الوكيل، يبقى مستند [OpenAPI](https://spec.openapis.org/oas/v3.1.0) أنفع ما يمكنك نشره. فهو يقدّم معرّفات العمليات والمعاملات والمخططات والمصادقة بصيغة يقرؤها الوكلاء ومولّدات الكود على حد سواء.

مستند Shager موجود في [app.shager.ai/api/v1/openapi.json](https://app.shager.ai/api/v1/openapi.json)، بالإصدار 3.1. وفيه ثلاثة أعراف تساعد الوكلاء تحديدًا. معرّفات العمليات تطابق أسماء أدوات MCP (`create_post`، `get_analytics`)، فالوكيل الذي تعلّم واجهة يعرف الأخرى. وكل عملية تعلن صلاحية المفتاح المطلوبة في الامتداد `x-scope`. وأوصاف الحقول مكتوبة كتعليمات، فمثلًا يذكر تجاوز النص في `per_channel` أنه يُستحسن تنويع الصياغة لكل حساب. الأوصاف مساحة للتعليمات، فاستخدمها.

## api-catalog: إخبار البرمجيات بمكان الواجهات

يعرّف [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727)، الذي نشرته IETF في يونيو 2025، عنوانًا معروفًا هو `/.well-known/api-catalog`، وعلاقة ربط باسم `api-catalog`. الطلب إليه يعيد مستندًا يسرد واجهات الناشر البرمجية مع روابط إلى أوصافها ووثائقها. ويشترط الـ RFC نوع الوسائط `application/linkset+json` للمستند، ويستخدم علاقات ربط مثل `service-desc` للأوصاف المقروءة آليًا مثل OpenAPI، و`service-doc` للوثائق الموجهة إلى البشر.

هذا فهرس Shager كاملًا:

```json
{
  "linkset": [
    {
      "anchor": "https://app.shager.ai/api/v1",
      "service-desc": [
        { "href": "https://app.shager.ai/api/v1/openapi.json", "type": "application/openapi+json" }
      ],
      "service-doc": [
        { "href": "https://shager.ai/en/agents", "type": "text/html" },
        { "href": "https://shager.ai/md/en/agents", "type": "text/markdown" }
      ]
    }
  ]
}
```

إنه قصير لأن لدى Shager واجهة API واحدة. والشركة التي لديها عدة واجهات تضع مدخلًا لكل منها. أما الرابط `rel="api-catalog"` في ترويسة `Link` لكل صفحة، كما رأينا أعلاه، فهو ما يجعل العميل الذي يصل إلى أي صفحة يجد الفهرس من دون تخمين المسار.

## بطاقات خوادم MCP: كيف تتصل قبل أن تتصل

يحتاج عميل MCP إلى معرفة مكان الخادم وطريقة المصادقة قبل أن يستطيع استدعاء `tools/list`. ولهذا الغرض تحديدًا يعرّف [SEP-2127](https://modelcontextprotocol.io/seps/2127-mcp-server-cards) بطاقات خوادم MCP: مستند JSON ثابت يصف هوية خادم بعيد، ونقاط النقل الخاصة به، والترويسات المطلوبة، وإصدارات البروتوكول المدعومة. ويحجز الـ SEP المسار `<streamable-http-url>/server-card` موقعًا موصى به، ويصف الاكتشاف على مستوى النطاق عبر AI Catalog يربط بالبطاقات. والمخطط التفصيلي موجود في مستودع الامتداد.

يقدّم Shager بطاقته في الموقع الموصى به، `https://app.shager.ai/api/mcp/server-card`، وكذلك في `https://shager.ai/.well-known/mcp/server-card.json`، وهو مسار تفحصه بعض أدوات الاكتشاف. وجزء الاتصال فيها كالتالي:

```json
{
  "name": "ai.shager/shager",
  "title": "Shager",
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": [
        { "name": "Authorization", "isRequired": true, "isSecret": true,
          "description": "Bearer shgr_… API key (self-signup: POST /api/v1/agent/signup)" }
      ]
    }
  ]
}
```

تسرد البطاقة أيضًا أدوات Shager مع وصف من سطر واحد لكل منها. لاحظ أن الـ SEP يُبقي الأدوات عمدًا خارج الحقول القياسية للبطاقة، لأن ما يكشفه الخادم قد يختلف حسب المستخدم والجلسة. تعامل مع أي قائمة أدوات في البطاقة كمعاينة، فاستدعاء `tools/list` الحي هو المرجع.

## إضافتان: auth.md وملف مهارة

الاكتشاف يخبر الوكيل بما هو موجود. وملفان آخران يخبرانه بما يفعل.

[/auth.md](/auth.md) وصفة بسيطة لكيفية حصول الوكيل على الوصول: الاكتشاف، ثم التسجيل باستدعاء التسجيل الذاتي، ثم استخدام المفتاح، ثم تسليم رابط تولّي الملكية لإنسان، وكيف يلغي الإنسان الوصول. وتذكر أيضًا القواعد: حد المعدل، وشكل الأخطاء، وتنويع النصوص، والاعتماد على الواجهات الرسمية فقط. يستطيع الوكيل اتباعها من أولها إلى آخرها.

أما `https://shager.ai/skills/shager/SKILL.md` فهو ملف مهارة بالصيغة التي يستخدمها Claude Code لـ [المهارات](https://code.claude.com/docs/en/skills): مقدمة YAML فيها `name` و`description` يخبر النموذج متى يستخدمها، ثم تعليمات مرقّمة. ثبّته فيعرف الوكيل مسار العمل في Shager من دون تعليمات طويلة. وبناء نسختك الخاصة مشروح في [ابنِ مهارة Claude لـ Shager](/ar/blog/build-a-claude-skill-for-shager).

## قائمة تحقق لموقعك

1. ملف `/llms.txt` فيه H1، وملخص من فقرة واحدة، وقسم للوكلاء في البداية، وتسميات صادقة لكل ما لم يعمل بعد.
2. نسخة Markdown من كل صفحة، معلن عنها عبر `rel="alternate"` و`type="text/markdown"`، ومُعلَّمة بـ `noindex`.
3. مستند OpenAPI بمعرّفات عمليات تطابق أدوات MCP لديك، وأوصاف مكتوبة كتعليمات.
4. `/.well-known/api-catalog` بنوع `application/linkset+json`، مربوط من كل صفحة عبر `rel="api-catalog"`.
5. بطاقة خادم MCP في `<your MCP URL>/server-card`.
6. وصفة وصول بلغة واضحة مثل `auth.md`، إن كان الوكلاء يستطيعون التسجيل.

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

### هل llms.txt هو نفسه robots.txt؟

لا. يخبر `robots.txt` برامج الزحف بما يُسمح لها بجلبه. أما `llms.txt` فدليل منتقى لما يستحق القراءة، مكتوب للنماذج اللغوية. لا يمنح شيئًا ولا يمنعه.

### هل يحسّن نشر هذه الملفات الترتيب في محركات البحث؟

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

### هل أحتاج إلى خادم MCP كي أستفيد من هذا؟

لا. ملفات `llms.txt` وصفحات Markdown وOpenAPI وapi-catalog مفيدة لأي موقع لديه وثائق أو API. البطاقة وحدها تخص من يشغّل خادم MCP بعيدًا.

## إلى أين بعد ذلك

اجلب ملفات Shager بالأمر `curl` وقارنها بموقعك. ولما يفعله الوكيل بعد الاكتشاف، فالمحطة التالية هي [نقطة دخول الوكلاء](/ar/agents).

---
Source: https://shager.ai/ar/blog/agent-ready-websites-llms-txt