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

الموقع الجاهز للوكلاء يمنح البرمجيات طريقًا قصيرًا ومتوقعًا من سؤال «ما هذا؟» إلى سؤال «كيف أستخدمه؟». عمليًا يعني ذلك خمسة ملفات أو أعراف: ملخصًا في /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. إنها ملف Markdown في /llms.txt يتضمن عنوان H1 باسم الموقع (الجزء الإلزامي الوحيد)، وملخصًا في اقتباس، ونصًا حرًا اختياريًا، وأقسام H2 تضم قوائم روابط مع ملاحظات قصيرة. والقسم المعنون «Optional» يحدد الروابط التي يمكن للوكيل تخطيها حين يحتاج إلى سياق أقصر.

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

# 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 مباشرة:

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

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

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 أنفع ما يمكنك نشره. فهو يقدّم معرّفات العمليات والمعاملات والمخططات والمصادقة بصيغة يقرؤها الوكلاء ومولّدات الكود على حد سواء.

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

مرّر جانبيًا لرؤية المخطط كاملًا

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

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

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

{
  "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 بطاقات خوادم 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، وهو مسار تفحصه بعض أدوات الاكتشاف. وجزء الاتصال فيها كالتالي:

{
  "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 وصفة بسيطة لكيفية حصول الوكيل على الوصول: الاكتشاف، ثم التسجيل باستدعاء التسجيل الذاتي، ثم استخدام المفتاح، ثم تسليم رابط تولّي الملكية لإنسان، وكيف يلغي الإنسان الوصول. وتذكر أيضًا القواعد: حد المعدل، وشكل الأخطاء، وتنويع النصوص، والاعتماد على الواجهات الرسمية فقط. يستطيع الوكيل اتباعها من أولها إلى آخرها.

أما https://shager.ai/skills/shager/SKILL.md فهو ملف مهارة بالصيغة التي يستخدمها Claude Code لـ المهارات: مقدمة YAML فيها name وdescription يخبر النموذج متى يستخدمها، ثم تعليمات مرقّمة. ثبّته فيعرف الوكيل مسار العمل في Shager من دون تعليمات طويلة. وبناء نسختك الخاصة مشروح في ابنِ مهارة Claude لـ 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 وقارنها بموقعك. ولما يفعله الوكيل بعد الاكتشاف، فالمحطة التالية هي نقطة دخول الوكلاء.