راهنمای ساخت و انتشار

از اولین منبع
تا یک فایل قابل کشف.

ساخت فایل، یک بخش کار است. بخش بعدی این است که فایل را روی دامنه خودتان منتشر کنید تا مصرف‌کننده‌ها بتوانند آن را پیدا کنند.

۱. آدرس را وارد کنید یا دستی شروع کنید

آدرس عمومی HTTPS سایتتان را وارد کنید. بررسی خودکار ابتدا صفحه اصلی، لینک معرفی کاتالوگ و مسیر شناخته‌شده را بررسی می‌کند. نقشه سایت دریافت می‌شود و تعداد محدودی از فایل‌های مرتبط همان دامنه بررسی می‌شوند.

این صفحه را هنگام بررسی باز نگه دارید. با خروج از صفحه، مرحله‌های بعدی متوقف می‌شوند؛ با بازگشت به همین تب، بررسی از آخرین مرحله ذخیره‌شده ادامه پیدا می‌کند. تب جدید نتیجه قبلی را خودکار بازیابی نمی‌کند.

بررسی کامل تمام صفحه‌های سایت یا همه زیردامنه‌ها انجام نمی‌شود. سرور MCP که فقط endpoint اجرایی دارد و سند معرفی ندارد، از روی نام لینک قابل تأیید نیست. برای چنین منابعی از فرم دستی استفاده کنید.

۲. منابع را مرور و تکمیل کنید

هر منبع حداقل یک identifier و type دارد و باید دقیقاً یکی از url یا data داشته باشد. آدرس باید به سند یا خود منبع اشاره کند؛ نه صرفاً به صفحه اول سایت.

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Your Organization",
    "identifier": "example.com"
  },
  "entries": [
    {
      "identifier": "urn:air:example.com:mcp:search",
      "type": "application/mcp-server-card+json",
      "url": "https://example.com/mcp/server-card.json"
    }
  ]
}

برای فهرست‌های عمومی، شناسه را به شکل urn:air:domain:namespace:name بسازید. نام باید برای همان منبع پایدار بماند. اگر دو نسخه از یک شناسه دارید، نسخه هر دو باید مشخص و ترکیب شناسه و نسخه یکتا باشد.

نوع مناسب منبع را انتخاب کنید

منبع	نوع
کاتالوگ تو در تو	`application/ai-catalog+json`
عامل A2A	`application/a2a-agent-card+json`
کارت سرور MCP	`application/mcp-server-card+json`
مهارت Markdown	`application/agent-skills+md`
بسته مهارت	`application/agent-skills+zip`
بسته افزونه	`application/agent-plugins+zip`
دیتاست Parquet	`application/parquet`

برای مدل، دیتاست یا قالب سفارشی، نوع واقعی همان منبع را وارد کنید. ساختار داده داخلی متعلق به پروتکل آن منبع است. نام، توضیح و نسخه را وقتی منبع خودش مقدار اصلی را دارد تکرار نکنید، مگر برای نمایش متفاوت یا معرفی چند نسخه.

فیلدهای پیشرفته

ویرایشگر JSON همه فیلدها را حفظ می‌کند. می‌توانید publisher، updatedAt، کاتالوگ تو در تو و extensionها را وارد کنید. کلیدهای extension باید URL یا reverse-DNS مثل ir.example.metadata باشند. حداکثر عمق کاتالوگ inline در این ابزار ۴ است.

داده inline می‌تواند هر مقدار JSON باشد، حتی null؛ اما هم‌زمان با آن url نگذارید. برای مدل یا دیتاست بزرگ، آدرس منبع را معرفی کنید و کل داده را در کاتالوگ قرار ندهید.

۳. فایل را دانلود کنید

خروجی UTF-8 با نام ai-catalog.json و فاصله‌گذاری خوانا دانلود می‌شود. خطاهای ساختاری باید قبل از دانلود برطرف شوند. هشدارها را هم مرور کنید؛ معتبر بودن ساختار به معنای تأیید اصالت منابع نیست.

۴. فایل را روی دامنه خودتان بگذارید

مسیر پیشنهادی این است:

https://example.com/.well-known/ai-catalog.json
Content-Type: application/ai-catalog+json; charset=utf-8

استفاده از این مسیر اختیاری است. می‌توانید فایل را در هر آدرس عمومی دیگری هم قرار دهید؛ نوع پاسخ و محتوای JSON مهم هستند.

nginx

فایل را در پوشه .well-known داخل document root سایت قرار دهید و این location را داخل server اضافه کنید:

location = /.well-known/ai-catalog.json {
    default_type application/ai-catalog+json;
    add_header Access-Control-Allow-Origin "*";
    try_files $uri =404;
}

Apache

در تنظیمات VirtualHost، نوع فایل کاتالوگ را مشخص کنید:

<Location "/.well-known/ai-catalog.json">
    ForceType application/ai-catalog+json
</Location>

Cloudflare Workers با Static Assets

فایل را در public/.well-known/ai-catalog.json قرار دهید. در فایل public/_headers این مسیر را اضافه کنید و دوباره deploy کنید:

/.well-known/ai-catalog.json
  Content-Type: application/ai-catalog+json; charset=utf-8
  Access-Control-Allow-Origin: *

۵. لینک معرفی را به HTML اضافه کنید

این تگ را در <head> سایت قرار دهید. اگر آدرس فایل شما متفاوت است، href را تغییر دهید:

<link
    rel="ai-catalog"
    href="/.well-known/ai-catalog.json"
    type="application/ai-catalog+json"
>

به جای تگ HTML می‌توانید هدر HTTP هم بفرستید:

Link: <https://example.com/.well-known/ai-catalog.json>; rel="ai-catalog"

۶. پاسخ نهایی را بررسی کنید

آدرس فایل را باز کنید؛ باید JSON واقعی ببینید، نه صفحه خطا یا فرم ورود. در ترمینال نیز نوع پاسخ را بررسی کنید:

curl -I https://example.com/.well-known/ai-catalog.json

مدارک Trust Manifest را فقط زمانی اضافه کنید که واقعاً دارید. این ابزار کلید امضای ناشر را نگه نمی‌دارد، امضا تولید نمی‌کند و ادعای اعتبار گواهی یا مالکیت دامنه ندارد.

ساخت کاتالوگ ←

از اولین منبعتا یک فایل قابل کشف.