راهاندازی MCP و Agents
Gerdoo CLI یک سرور MCP روی stdio دارد که پروژهها، محیطها، سرویسها، دامنهها، متغیرها، لاگها، بیلدها و ریلیزهای گردو را بهصورت ابزارهای ساختیافته در اختیار دستیارهای هوش مصنوعی (Claude Code، Cursor، Codex، GitHub Copilot، OpenCode، Grok، Devin، Pi، Gemini Antigravity و هر کلاینت سازگار با MCP) قرار میدهد. با این قابلیت میتوانید از داخل ویرایشگر یا ترمینال خود از دستیار بخواهید سرویسی بسازد، دیپلوی کند، لاگ بگیرد یا متغیرهای محیطی را تنظیم کند — بدون آنکه دستیار مستقیماً به توکن حساب شما دسترسی مستقل داشته باشد؛ همان توکن CLI که با gerdoo login ذخیره کردهاید استفاده میشود.
راهاندازی یکدستوری
بعد از نصب CLI، کافی است gerdoo setup agent را در ریشهٔ پروژه اجرا کنید. این دستور هم فایل تنظیمات MCP را برای همهٔ دستیارهای شناختهشده مینویسد و هم مهارت (Skill) use-gerdoo را نصب میکند تا دستیار بداند چطور از ابزارهای گردو استفاده کند.
مراحل راهاندازی
نصب و ورود به CLI
اگر هنوز gerdoo را نصب نکردهاید، دستور curl -fsSL https://get.gerdoo.cloud/install.sh | sh را اجرا کنید و سپس با gerdoo login وارد حساب خود شوید. این دستور مرورگر شما را روی گردو باز میکند و ورود را همانجا تأیید میکنید؛ رمز عبور هرگز در ترمینال وارد نمیشود. سرور MCP از همین توکن ذخیرهشده استفاده میکند؛ نیازی به احراز هویت جداگانه نیست.
اتصال دستیار به گردو
در ریشهٔ پروژهای که دستیار روی آن کار میکند، دستور زیر را اجرا کنید:
gerdoo setup agentاین دستور بهصورت پیشفرض تنظیمات MCP را برای همهٔ ابزارهای پشتیبانیشده مینویسد و مهارت use-gerdoo را نصب میکند. اگر فقط یکی از این ابزارها را استفاده میکنید، با فلگ --agent مشخص کنید.
تأیید اتصال
ویرایشگر یا ترمینال خود را دوباره باز کنید (یا سرورهای MCP را ریلود کنید) و از دستیار بخواهید فهرست سرویسها یا پروژههای شما را نشان دهد. اگر ابزارهای gerdoo_* در فهرست ابزارهای دستیار دیده شوند، اتصال برقرار است.
فلگهای gerdoo setup agent
gerdoo setup agent [--agent claude-code|cursor|codex|copilot|opencode|devin|pi|grok|antigravity|print]
[--skill-only] [--no-skill] [--global]| فلگ | توضیح |
|---|---|
--agent <name> | فقط یک ابزار مشخص را پیکربندی کنید؛ بدون این فلگ همهٔ ابزارها تنظیم میشوند. مقدار print بهجای نوشتن فایل، تنظیمات را در هر چهار قالب رایج چاپ میکند تا در هر ابزار سازگار با MCP قابل استفاده باشد. |
--skill-only | فقط مهارت use-gerdoo را نصب کنید، بدون تغییر تنظیمات MCP. |
--no-skill | فقط تنظیمات MCP را بنویسید، بدون نصب مهارت. |
--global | مهارت را در مسیر عمومی کاربر نصب کنید (~/.claude/skills/use-gerdoo) بهجای پوشهٔ پروژه (.claude/skills/use-gerdoo). |
اجرای دوباره این دستور بیخطر است: فایلهای موجود بازنویسی نمیشوند، فقط تنظیمات گردو در آنها بهروزرسانی میشود.
هر ابزار دقیقاً کجا پیکربندی میشود؟
| ابزار | فایل تنظیمات |
|---|---|
| Claude Code | .mcp.json در ریشهٔ پروژه؛ ورودیهای دیگر این فایل دستنخورده میمانند. |
| Grok | همان .mcp.json و .cursor/mcp.json را میخواند؛ تنظیم جداگانهای لازم ندارد. |
| Cursor | .cursor/mcp.json در ریشهٔ پروژه، با همان ساختار. |
| Codex CLI | جدول [mcp_servers.gerdoo] در .codex/config.toml، بدون دستکاری بقیهٔ فایل. |
| GitHub Copilot | .vscode/mcp.json (قالب VS Code با کلید servers و type: stdio). |
| OpenCode | opencode.json در ریشهٔ پروژه (کلید mcp با type: local). |
| Devin | .devin/mcp_config.json در ریشهٔ پروژه. |
| Pi | .pi/mcp.json در ریشهٔ پروژه. |
| Gemini Antigravity | .agents/mcp_config.json در ریشهٔ پروژه (فرمت مشترک IDE و CLI Antigravity). |
اگر ابزار دیگری با MCP سازگار دارید — یا ابزاری که تنظیماتش در یک پنل تحتوب انجام میشود و فایل محلی ندارد — gerdoo setup agent --agent print را اجرا کنید تا تنظیمات لازم در هر چهار قالب رایج چاپ شود. gerdoo mcp یک سرور استاندارد stdio است و با هر کلاینت MCP کار میکند.
دستور gerdoo mcp
اگر ترجیح میدهید تنظیمات را دستی بنویسید، سرور MCP با دستور زیر روی ورودی/خروجی استاندارد (stdio) اجرا میشود:
gerdoo mcpاین دستور معمولاً مستقیم اجرا نمیشود؛ ابزار دستیار آن را خودش بهعنوان زیرفرآیند اجرا میکند. تنها نکته این است که فرمان gerdoo باید در مسیر PATH همان محیطی باشد که ابزار دستیار در آن اجرا میشود. روی ماشینهای بدون مرورگر (CI یا سرور راه دور) بهجای gerdoo login میتوانید متغیر GERDOO_TOKEN را تنظیم کنید.
ابزارهای در دسترس دستیار
سرور MCP گردو بیش از ۴۰ ابزار در اختیار دستیار میگذارد که تمام سطح API گردو را پوشش میدهند:
- شناخت حساب:
gerdoo_whoamiایمیل حساب بههمراه خلاصهٔ سرویسها (تعداد کل، تفکیک بر اساس وضعیت و فهرست کوتاه سرویسها) را برمیگرداند؛ مناسب اولین فراخوانی برای آشنایی با وضعیت حساب. - هزینهها:
gerdoo_get_pricingنرخنامهٔ pay-as-you-go را به تومان میدهد (CPU و RAM ساعتی، دیسک ماهانه، ترافیک خروجی و دقیقهٔ بیلد) و با دادن اندازهٔ سرویس، برآورد هزینهٔ ماهانه را هم محاسبه میکند.gerdoo_get_spendingموجودی کیف پول، هزینهٔ ماه جاری و گرانترین سرویسها را نشان میدهد. - پروژهها و محیطها: فهرست، جزئیات، ساخت پروژه و محیط جدید.
- سرویسها: فهرست، جزئیات، ساخت از ایمیج Docker، دیپلوی از پوشهٔ محلی (
gerdoo_deploy_service_source)، بهروزرسانی تنظیمات، شروع/توقف/ریاستارت. - متغیرها: هم نقشهٔ سادهٔ env و هم انبار متغیر تایپدار (build-time/secret). همهٔ نام متغیرها نمایش داده میشوند، اما مقدار متغیرهای secret و مقادیر حساس در env با
[redacted]پنهان میشوند. - دامنهها: افزودن، تأیید و حذف دامنهٔ اختصاصی همراه با رکوردهای DNS.
- دیتابیس و افزونههای مدیریتشده:
gerdoo_add_databaseبا یک فراخوانی یک افزونه (PostgreSQL، Redis، MinIO، RabbitMQ، MariaDB، MongoDB) میسازد و به سرویس متصل میکند تا متغیرهای اتصال (DATABASE_URL،REDIS_URL، …) خودکار تزریق شوند؛ بهعلاوهٔ ساخت، فهرست، اتصال و قطع اتصال افزونهها. - قالبهای مارکتپلیس: فهرست و جزئیات قالبها و دیپلوی یکمرحلهای آنها (
gerdoo_deploy_template). ایمیج و اعتبارنامهها همیشه از کاتالوگ پلتفرم میآیند و مقدار رمزهای تولیدشده به دستیار برگردانده نمیشود. - شبکهٔ داخلی:
gerdoo_get_serviceآدرس داخلی سرویس (internal_address) و فهرست سرویسهای همپروژه را برمیگرداند وgerdoo_list_servicesمقدارinternal_hostهر سرویس را؛ برای اتصال سرویسها به یکدیگر باید از همین نام داخلی استفاده شود، نه از آدرس عمومی. - مشاهده و عیبیابی:
gerdoo_diagnose_serviceدر یک فراخوانی وضعیت سرویس، لاگ کانتینر، آخرین بیلد و لاگ آن و توضیح خطای بیلد را برمیگرداند.gerdoo_get_logsفیلترهایlevel،grep،sinceوinvertرا میپذیرد و تعداد خطوط منطبق را هم گزارش میکند.gerdoo_execیک دستور تکمرحلهای داخل کانتینر سرویس در حال اجرا اجرا میکند. بهعلاوهٔ فهرست بیلدها و ریلیزها و متریک ترافیک (gerdoo_get_metrics). - تیکت پشتیبانی: ساخت، خواندن، پاسخ و بستن تیکت (
gerdoo_create_ticketو …) برای مشکلاتی که حل آنها بر عهدهٔ پلتفرم است. - دیپلوی از پوشهٔ محلی: اگر بیلد شکست بخورد، نتیجهٔ
gerdoo_deploy_service_sourceخودِ تشخیص خطا را در فیلدdiagnosisهمراه دارد؛ دستیار برای فهمیدن علت به فراخوانیهای اضافه نیاز ندارد. - عملیات حساس: حذف سرویس/پروژه، rollback، تعلیق سرویس — همگی نیازمند پارامتر
confirm: trueو در MCP با نشانهٔ «مخرب» (destructive) علامتگذاری شدهاند تا کلاینت پیش از اجرا از کاربر تأیید بگیرد.
حریم خصوصی و محدودهٔ دسترسی
ابزار gerdoo_whoami فقط ایمیل حساب فعلی را برمیگرداند؛ MCP تلفن، نشانی و اطلاعات هویتی را به دستیار نمیفرستد. با این حال ابزارها از همان توکن کامل حساب CLI استفاده میکنند؛ یعنی دستیار میتواند همهٔ پروژهها و سرویسهای حساب را مدیریت کند، نه فقط پروژهٔ فعلی. پیش از تأیید هر عملیات مخرب (حذف، rollback، تعلیق) حتماً مطمئن شوید سرویس/پروژه درست انتخاب شده است.
منابع (Resources) مرجع
علاوه بر ابزارها، سرور MCP چند «منبع» مرجع هم منتشر میکند تا دستیار بهجای حدس زدن مقدارها آنها را بخواند:
| منبع | محتوا |
|---|---|
gerdoo://catalog/templates | فهرست زندهٔ قالبهای قابل استقرار این حساب |
gerdoo://catalog/addon-kinds | انواع افزونه و متغیرهای اتصالی که هرکدام تزریق میکنند |
gerdoo://catalog/frameworks | مقادیر مجاز framework (پیشفرض auto) |
gerdoo://reference/variable-precedence | ترتیب اولویت انبارهای متغیر و نحو ${{ }} |
gerdoo://reference/service-statuses | معنی هر وضعیت سرویس و اقدام مناسب |
مهارت use-gerdoo
مهارت use-gerdoo یک راهنمای رویهای (Skill) است که همراه CLI نصب میشود و به دستیار میگوید در چه سناریویی کدام ابزار را صدا بزند: ساخت سرویس جدید، دیپلوی پوشهٔ فعلی، عیبیابی از طریق لاگ و بیلدها، مدیریت متغیرها و دامنه، و مهمتر از همه — تأکید بر اینکه دستیار پیش از هر عملیات مخرب باید صریحاً از کاربر تأیید بگیرد.
با اجرای gerdoo upgrade، نسخهٔ نصبشدهٔ این مهارت هم بهروزرسانی میشود (مگر آنکه خودتان آن را ویرایش کرده باشید؛ در آن صورت دستنخورده میماند و پیام مربوطه نمایش داده میشود).
# فقط نصب مهارت، بدون تغییر تنظیمات MCP
gerdoo setup agent --skill-only
# نصب سراسری برای همهٔ پروژهها
gerdoo setup agent --skill-only --global