Model Context Protocol

ایمجین را به دستیار هوش مصنوعی خودتان وصل کنید

سرور MCP دیمو ایمجین به کلاینت‌هایی مثل claude.ai، Claude Code، Cursor، VS Code و ایجنت‌های Hermes اجازه می‌دهد مستقیماً تصویر، ویدیو، گفتار و موسیقی بسازند. هر درخواست با کلید حساب خود شما پردازش می‌شود. شناسایی یا با «ورود» (OAuth) انجام می‌شود یا با یک توکن شخصی در هدر.

HTTP https://dimosoftwares.ir/imagine/mcp

راه‌اندازی

دو راه برای اتصال وجود دارد. اگر کلاینت شما «ورود» را پشتیبانی می‌کند، راه اول ساده‌تر و امن‌تر است.

۱. ورود (OAuth): برای claude.ai، Claude Desktop، اپ موبایل Claude، Cursor، VS Code و Claude Code. فقط نشانی سرور را وارد کنید؛ صفحهٔ ورود دیمو باز می‌شود و پس از «اجازه می‌دهم» اتصال برقرار است. توکن لازم نیست.
۲. توکن شخصی: برای کلاینت‌هایی که فقط هدر می‌پذیرند (Hermes، اسکریپت‌ها، curl) یا وقتی نمی‌خواهید مرورگر باز شود. توکن را در بخش بعد بسازید و در هدر Authorization بفرستید.

نشانی سرور را در کلاینت اضافه کنید.
نوع اتصال HTTP (Streamable HTTP) است. نمونهٔ هر کلاینت در بخش «پیکربندی کلاینت‌ها» آمده است.
وارد شوید یا توکن را وارد کنید.
با OAuth، دکمهٔ Connect/Authenticate کلاینت را بزنید. با توکن، آن را در هدر قرار دهید.
اتصال را امتحان کنید.
از دستیار بخواهید check_account_status را اجرا کند؛ باید مصرف و سقف کلیدتان را نشان دهد.

توکن شخصی شما

فقط برای اتصال با توکن (راه دوم) لازم است. توکن مثل رمز عبور است: آن را در کد یا مخزن عمومی قرار ندهید و فقط در تنظیمات کلاینت MCP وارد کنید.

برای ساخت توکن شخصی وارد حساب کاربری خود شوید.

ورود / ثبت‌نام

پیکربندی کلاینت‌ها

در نمونه‌های توکنی، DIMO_MCP_TOKEN را با توکن خود جایگزین کنید (اگر همین حالا توکن ساخته باشید، خودکار جایگزین شده است). برای اتصال با ورود، بخش headers را حذف کنید.

توکن لازم نیست. در claude.ai به Settings → Connectors → Add custom connector بروید، نشانی زیر را وارد کنید و پس از «Add» روی «Connect» بزنید. صفحهٔ ورود دیمو باز می‌شود؛ «اجازه می‌دهم» را بزنید.

https://dimosoftwares.ir/imagine/mcp

بخش «Advanced settings» (Client ID / Secret) را خالی بگذارید. Claude Desktop و اپ موبایل هم از همین connector استفاده می‌کنند.

با ورود: سرور را اضافه کنید، سپس داخل Claude Code فرمان /mcp را اجرا کرده و گزینهٔ Authenticate را بزنید.

claude mcp add --transport http dimo-imagine https://dimosoftwares.ir/imagine/mcp

با توکن:

claude mcp add --transport http dimo-imagine https://dimosoftwares.ir/imagine/mcp \
  --header "Authorization: Bearer DIMO_MCP_TOKEN"

برای دسترسی در همهٔ پروژه‌ها --scope user را اضافه کنید.

به فایل ~/.cursor/mcp.json اضافه کنید. اگر بخش headers را حذف کنید، Cursor دکمهٔ «Connect» نشان می‌دهد و با ورود (OAuth) وصل می‌شود.

{
  "mcpServers": {
    "dimo-imagine": {
      "url": "https://dimosoftwares.ir/imagine/mcp",
      "headers": {
        "Authorization": "Bearer DIMO_MCP_TOKEN"
      }
    }
  }
}

به فایل .vscode/mcp.json پروژه اضافه کنید. بدون بخش headers، VS Code هنگام شروع سرور صفحهٔ ورود را باز می‌کند.

{
  "servers": {
    "dimo-imagine": {
      "type": "http",
      "url": "https://dimosoftwares.ir/imagine/mcp",
      "headers": {
        "Authorization": "Bearer DIMO_MCP_TOKEN"
      }
    }
  }
}

ساده‌ترین راه: connector را یک بار در claude.ai اضافه کنید (تب claude.ai)؛ در Claude Desktop هم در دسترس خواهد بود.

اگر connector نمی‌خواهید، از پل mcp-remote (نیازمند Node.js) استفاده کنید. به claude_desktop_config.json اضافه کنید و Claude Desktop را دوباره باز کنید:

{
  "mcpServers": {
    "dimo-imagine": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://dimosoftwares.ir/imagine/mcp",
        "--header",
        "Authorization:${DIMO_AUTH}"
      ],
      "env": {
        "DIMO_AUTH": "Bearer DIMO_MCP_TOKEN"
      }
    }
  }
}

ایجنت‌های ساخته‌شده در دیمو این سرور را از پیش دارند و به توکن شما نیازی ندارند. برای Hermes Agent خودتان، به ~/.hermes/config.yaml اضافه کنید:

mcp_servers:
  dimo_imagine:
    url: "https://dimosoftwares.ir/imagine/mcp"
    headers:
      Authorization: "Bearer DIMO_MCP_TOKEN"
    timeout: 300
    connect_timeout: 30

سرور بدون نشست (stateless) است؛ هر درخواست مستقل است و می‌توانید مستقیماً ابزارها را فهرست کنید:

curl -X POST https://dimosoftwares.ir/imagine/mcp \
  -H "Authorization: Bearer DIMO_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

اجرای یک ابزار:

curl -X POST https://dimosoftwares.ir/imagine/mcp \
  -H "Authorization: Bearer DIMO_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"check_account_status","arguments":{}}}'

احراز هویت

هر درخواست HTTP باید توکن را در هدر داشته باشد. توکن در نشانی (query string) پذیرفته نمی‌شود، چون نشانی‌ها در لاگ‌ها ثبت می‌شوند. کلاینت‌هایی که ورود را پشتیبانی می‌کنند، مسیر OAuth را از هدر پاسخ ۴۰۱ خودکار پیدا می‌کنند.

Authorization: Bearer dimo_mcp_…     # توکن شخصی
Authorization: Bearer dimo_oat_…     # صادرشده با OAuth (claude.ai، Cursor)

# یا به‌جای آن:
X-Dimo-Key: dimo_mcp_…

۴۰۱ Unauthorized: توکن ارسال نشده، منقضی یا باطل شده است. پاسخ شامل هدر WWW-Authenticate است تا کلاینت‌ها ورود OAuth را خودکار شروع کنند.
دسترسی فعال نیست: اگر دسترسی هوش مصنوعی حساب فعال نباشد اتصال برقرار می‌شود، اما ابزارهای تولید پیام خطای راهنما برمی‌گردانند.
توکن‌های OAuth: توکن دسترسی یک ساعت اعتبار دارد و کلاینت آن را خودکار تمدید می‌کند؛ اگر ۶۰ روز استفاده نشود، باید دوباره وارد شوید. با دکمهٔ «قطع اتصال همهٔ برنامه‌ها» همهٔ این اتصال‌ها فوراً باطل می‌شوند.
ایجنت‌های دیمو: هر ایجنت توکن مخصوص خودش (dimo_mcpa_…) را دارد و به توکن شخصی شما وابسته نیست. خاموش کردن ایمجین یا حذف ایجنت، دسترسی آن را قطع می‌کند.
تعویض توکن: با «ساخت توکن جدید» توکن قبلی بلافاصله از کار می‌افتد؛ کلاینت‌ها را به‌روز کنید.
نگهداری: دیمو فقط هش توکن‌ها را ذخیره می‌کند؛ به همین دلیل امکان نمایش دوبارهٔ توکن شخصی وجود ندارد.

ابزارها

کلاینت فهرست ابزارها را خودکار دریافت می‌کند. شناسهٔ مدل‌ها را با list_models بگیرید؛ modality یکی از image، video، speech (گفتار) یا audio (موسیقی) است. ابزارهای کاتالوگ و وضعیت حساب فقط‌خواندنی‌اند و هزینه‌ای ندارند.

generate_imageتصویر

تولید ۱ تا ۴ تصویر. پیش‌نمایش تصویر و پیوند فایل ذخیره‌شده در فضای ذخیره‌سازی برمی‌گردد.

model, prompt, n, aspect_ratio, resolution, output_format, quality, background, seed, reference_urls, include_preview, include_base64

submit_videoویدیو

ثبت یک کار تولید ویدیو. شناسهٔ کار (job_id) را برمی‌گرداند.

model, prompt, duration, resolution, aspect_ratio, size, generate_audio, seed, frame_image_urls, reference_urls

poll_videoویدیو

بررسی (و در صورت نیاز انتظار برای) کار ویدیو؛ پس از آماده شدن، فایل خودکار ذخیره و پیوندش برگردانده می‌شود.

job_id, wait_seconds, include_base64

download_videoویدیو

ذخیرهٔ دستی ویدیوی آماده (برای سازگاری با کلاینت‌های قدیمی).

job_id | url, include_base64

generate_speechصدا

تبدیل متن به گفتار؛ فایل صوتی ذخیره و پیوندش برگردانده می‌شود.

model, text, voice (صدای خود مدل), response_format (mp3/wav), instructions

generate_musicصدا

ساخت موسیقی از روی توضیح متنی؛ فایل ذخیره و پیوندش برگردانده می‌شود.

model, prompt, instrumental, lyrics, seed

list_modelsکاتالوگ

فهرست مدل‌های یک نوع خروجی: image، video، speech یا audio.

modality, force_refresh

find_modelکاتالوگ

جزئیات یک مدل مشخص.

modality, model_id

full_catalogueکاتالوگ

کاتالوگ کامل همهٔ مدل‌ها.

force_refresh

check_account_statusحساب

مصرف و سقف باقی‌ماندهٔ کلید شما.

—

نمونه درخواست‌ها

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

تصویر: «با ایمجین یک پوستر مینیمال ۹:۱۶ از یک فنجان قهوه در باران بساز.»
چند گزینه: «سه نسخهٔ متفاوت از لوگوی یک نانوایی با پس‌زمینهٔ شفاف بساز.»
ویدیو: «یک ویدیوی ۵ ثانیه‌ای از موج‌های دریا هنگام غروب بساز و وقتی آماده شد لینکش را بده.»
گفتار: «این متن را با صدای nova و لحن آرام به فایل صوتی تبدیل کن: …»
موسیقی: «یک قطعهٔ لوفای آرام ۳۰ ثانیه‌ای برای پس‌زمینهٔ ویدیو بساز.»
مدل‌ها: «کدام مدل‌های تصویر ایمجین پس‌زمینهٔ شفاف را پشتیبانی می‌کنند؟»

نکته‌ها

هزینه: همهٔ تولیدها روی کلید حساب شما محاسبه می‌شود؛ همان سقفی که در استودیو دارید.
خروجی: همهٔ فایل‌ها در پوشهٔ «خروجی‌های ایمجین» فضای ذخیره‌سازی شما ذخیره می‌شوند و در گالری ایمجین هم دیده می‌شوند. کلاینت پیوند مشاهده و دانلود و برای تصاویر یک پیش‌نمایش دریافت می‌کند. برای دریافت خود فایل به‌صورت base64، include_base64=true بفرستید.
ویدیو: ناهمگام است: submit_video و سپس poll_video با wait_seconds تا آماده شدن؛ فایل نهایی خودکار ذخیره می‌شود.
تصاویر مرجع: reference_urls باید نشانی عمومی https یا data URL باشد.
ایجنت‌ها: خروجی ایجنت‌ها علاوه بر فضای ذخیره‌سازی، روی دیسک خود ایجنت هم قرار می‌گیرد تا بتواند آن را در مراحل بعد یا در تلگرام استفاده کند.
زمان پاسخ: تصویر معمولاً چند ثانیه تا یک دقیقه طول می‌کشد؛ ویدیو از حدود ۳۰ ثانیه تا چند دقیقه.

عیب‌یابی

claude.ai وصل نمی‌شود: نشانی را دقیقاً مثل بالا و بدون / در انتها وارد کنید و بخش Advanced settings را خالی بگذارید. اگر پس از «اجازه می‌دهم» به claude.ai برنگشتید، دکمهٔ «بازگشت به برنامه» را بزنید.
۴۰۱ با توکن: توکن باطل یا عوض شده است، یا پیشوند Bearer فراموش شده. یک توکن جدید بسازید و در کلاینت جایگزین کنید.
«دسترسی فعال نیست»: با پشتیبانی تماس بگیرید تا دسترسی هوش مصنوعی حساب فعال شود؛ نیازی به اتصال دوباره نیست.
اعتبار کافی نیست: خطای ۴۰۲ یعنی اعتبار هوش مصنوعی حساب تمام شده است. با check_account_status سقف باقی‌مانده را ببینید.
قطع شدن در کارهای طولانی: مهلت پیش‌فرض برخی کلاینت‌ها کوتاه است. برای ویدیو از poll_video با wait_seconds کمتر استفاده کنید تا هر فراخوانی کوتاه بماند.
ابزارها دیده نمی‌شوند: پس از تغییر پیکربندی، کلاینت را دوباره اجرا کنید یا در فهرست سرورهای MCP آن را Refresh کنید.