hamravesh-mcp

کنترلِ کنسولِ هم‌روش / دارکوب از داخلِ هر کلاینتِ MCP (مثل Claude) — بدونِ پنل، بدونِ کلیک. Control the Hamravesh / Darkube console from any MCP client (Claude, etc.) — no panel, no clicking.

سرورِ MCP که به دستیارِ هوشِ مصنوعی اجازه می‌دهد اپ‌های هم‌روش (دارکوب) را مستقیم از طریقِ API داخلیِ کنسول مدیریت کند: دیدن و بررسیِ اپ‌ها، لاگ، ری‌استارت، دیپلوی، اسکیل، تغییرِ env، مدیریتِ دیتابیس/رجیستری/صورتحساب — و صدا زدنِ هر endpointِ دیگر.

A Model Context Protocol server that lets an AI assistant manage your Hamravesh (Darkube) apps directly via the console's internal API: list & inspect apps, view logs, restart, redeploy, scale, edit env vars, manage databases, registries, billing — and call any other endpoint.

⚠️ غیررسمی. این ابزار از API داخلیِ کنسولِ هم‌روش (api.hamravesh.com) استفاده می‌کند که عمومی/مستند نیست و ممکن است بدونِ اطلاع تغییر کند. Unofficial. Uses Hamravesh's internal console API (api.hamravesh.com), which is not a public/documented API and may change without notice.

فارسی

امکانات

• 🔑 دو روشِ ورود — یا کلید API (هدرِ Authorization: Api-Key …، توصیه‌شده) یا ایمیل/رمز (JWT با تمدیدِ خودکار).
• 🧰 ۳۰ ابزار — خواندنی (اپ‌ها، لاگ، کانتینرها، منیفست، بیلدها، دیتابیس، رجیستری، بازارچه/SaaS، صورتحساب، کلیدها)، نوشتنی (ری‌استارت، دیپلوی، اسکیل، روشن/خاموش، تغییرِ env، ساخت/حذفِ اپ، ساخت/حذف/روشن‌خاموشِ دیتابیس، ساخت SaaS، basic-auth، ساخت/حذفِ کلید) و یک ابزارِ جوکر hamravesh_request برای هر endpoint.
• 🔒 پیش‌فرض امن — نوشتن و حذف تا وقتی خودت روشن نکنی خاموش‌اند. ابزارِ جوکر روی میزبانِ هم‌روش قفل است (بدونِ SSRF) و رازها از پیامِ خطا پاک می‌شوند.
• 📦 بدونِ build، یک وابستگی — ESMِ ساده، فقط @modelcontextprotocol/sdk.

گرفتنِ کلید API

در پنلِ هم‌روش: تنظیماتِ سازمان ← امنیت ← API Keys ← یک کلید بساز. (یا به‌جایش ایمیل/رمز بده — جدولِ پایین.)

شروعِ سریع

با Claude، Cursor، VS Code، Windsurf و هر کلاینتِ MCP کار می‌کند. نیازی به نصبِ سراسری نیست — npx خودش موقعِ اجرا دانلودش می‌کند.

🪄 روشِ A — بدونِ کدنویسی (بذار Claude خودش انجامش دهد). اگر همه‌کارت را با Claude انجام می‌دهی، فقط بگو:

«MCP هم‌روش (hamravesh-mcp) را برایم نصب و تنظیم کن. کلیدِ APIم این است: … و سازمانم ….»

Claude خودش نصب و تنظیمش می‌کند. تمام.

⌨️ روشِ B — Claude Code، یک خط:

claude mcp add hamravesh --env HAMRAVESH_API_KEY=کلیدت --env HAMRAVESH_ORG=سازمانت -- npx -y hamravesh-mcp

📝 روشِ C — فایلِ پیکربندی (claude_desktop_config.json یا .mcp.jsonِ پروژه):

{
  "mcpServers": {
    "hamravesh": {
      "command": "npx",
      "args": ["-y", "hamravesh-mcp"],
      "env": {
        "HAMRAVESH_API_KEY": "کلیدِ تو",
        "HAMRAVESH_ORG": "نامِ سازمان"
      }
    }
  }
}

متغیرهای محیطی

| متغیر | لازم؟ | توضیح | |---|---|---| | HAMRAVESH_API_KEY | یکی از این دو | کلید API (توصیه‌شده). | | HAMRAVESH_EMAIL + HAMRAVESH_PASSWORD | یکی از این دو | ایمیل/رمز (JWT). اگر 2FA داری HAMRAVESH_OTP. | | HAMRAVESH_ORG | توصیه‌شده | سازمانِ پیش‌فرض (نامِ سازمانت)؛ در هر ابزار قابلِ تغییر. | | HAMRAVESH_BASE | نه | پیش‌فرض https://api.hamravesh.com. | | HAMRAVESH_ALLOW_WRITE | نه | 1 برای فعال‌کردنِ ابزارهای نوشتن (پیش‌فرض خاموش). | | HAMRAVESH_ALLOW_DELETE | نه | 1 برای فعال‌کردنِ ابزارهای حذف (پیش‌فرض خاموش). | | HAMRAVESH_DRY_RUN | نه | 1 تا همه‌ی نوشتن‌ها فقط پیش‌نمایش شوند (هیچ تغییری اعمال نشود). | | HAMRAVESH_APP_ALLOWLIST | نه | فهرستِ id/name اپ‌ها (با کاما) که نوشتن فقط روی آن‌ها مجاز است. |

ایمنی

به‌صورتِ پیش‌فرض فقط خواندن مجاز است؛ هیچ تغییری روی سرویسِ زنده رخ نمی‌دهد. برای تغییر/حذف باید فلگ‌های بالا را روی 1 بگذاری. این یعنی امکان ندارد دستیار اشتباهی چیزی را خراب کند.

ابزارها

خواندنی (همیشه روشن): hamravesh_whoami، hamravesh_list_apps، hamravesh_get_app، hamravesh_app_containers، hamravesh_app_logs، hamravesh_app_manifests، hamravesh_app_builds، hamravesh_list_databases، hamravesh_list_registries، hamravesh_billing، hamravesh_list_apikeys

نوشتنی (نیازمندِ ALLOW_WRITE=1): hamravesh_restart_app، hamravesh_redeploy_app، hamravesh_scale_app، hamravesh_set_app_enabled، hamravesh_update_app_envs، hamravesh_create_app، hamravesh_create_apikey، و hamravesh_delete_app/hamravesh_delete_apikey (نیازمندِ ALLOW_DELETE=1)

جوکر: hamravesh_request — هر متد/مسیر (GET آزاد؛ نوشتن/حذف تابعِ فلگ‌ها).

مرجع

• ENDPOINTS.md — کاتالوگِ دسته‌بندی‌شده.
• WRITE-ENDPOINTS.md — شکلِ بدنهٔ همهٔ ۱۶۲ درخواستِ نوشتنی.
• LIVE-STATUS.md — وضعیتِ زندهٔ هر endpoint با حسابِ admin.
• ENDPOINTS-RAW.txt — لیستِ خامِ همهٔ ۵۷۸ آدرس (متد+مسیر).

توسعه

npm ci
npm test        # بدونِ شبکه: ابزارها و محافظِ نوشتن را چک می‌کند

English

Features

• 🔑 Two auth modes — a stable API key (Authorization: Api-Key …, recommended) or email/password (JWT with auto-refresh).
• 🧰 30 tools — read (apps, logs, containers, manifests, builds, databases, registries, marketplace/SaaS, billing, api-keys), write (restart, redeploy, scale, enable/disable, update env, create/delete app, create/delete/power database, create SaaS, basic-auth, create/delete api-key), plus a generic hamravesh_request escape hatch. Write tools support dry_run.
• 🔒 Safe by default — write and delete operations are disabled unless you explicitly turn them on. The generic tool is host-locked (no SSRF) and secrets are redacted from error messages.
• 📦 Zero build, one dependency — plain ESM, only @modelcontextprotocol/sdk.

Get an API key

In the Hamravesh panel: Organization settings → Security → API Keys → create one. (Or use email/password instead — see the table below.)

Quick start

Works with Claude, Cursor, VS Code, Windsurf and any MCP client. No global install — npx fetches it on demand.

🪄 Option A — No coding (let Claude do it). If you do everything through Claude, just tell it:

"Set up the hamravesh-mcp MCP server for me. My Hamravesh API key is … and my org is …."

Claude installs it and writes the config for you. Done.

⌨️ Option B — Claude Code, one line:

claude mcp add hamravesh --env HAMRAVESH_API_KEY=your-key --env HAMRAVESH_ORG=your-org -- npx -y hamravesh-mcp

📝 Option C — config file (Claude Desktop claude_desktop_config.json, or a project .mcp.json):

{
  "mcpServers": {
    "hamravesh": {
      "command": "npx",
      "args": ["-y", "hamravesh-mcp"],
      "env": {
        "HAMRAVESH_API_KEY": "your-api-key",
        "HAMRAVESH_ORG": "your-org-name"
      }
    }
  }
}

Environment variables

| Variable | Required | Description | |---|---|---| | HAMRAVESH_API_KEY | one of these | API key (recommended). | | HAMRAVESH_EMAIL + HAMRAVESH_PASSWORD | one of these | Email/password (JWT). HAMRAVESH_OTP if 2FA. | | HAMRAVESH_ORG | recommended | Default organization (your org name); per-call overridable. | | HAMRAVESH_BASE | no | Defaults to https://api.hamravesh.com. | | HAMRAVESH_ALLOW_WRITE | no | 1 to enable write tools (default off). | | HAMRAVESH_ALLOW_DELETE | no | 1 to enable delete tools (default off). | | HAMRAVESH_DRY_RUN | no | 1 to make all writes preview-only (nothing is applied). | | HAMRAVESH_APP_ALLOWLIST | no | Comma-separated app ids/names; writes allowed only on these. |

Tools

Read (always on): hamravesh_whoami, hamravesh_list_apps, hamravesh_get_app, hamravesh_app_containers, hamravesh_app_logs, hamravesh_app_manifests, hamravesh_app_builds, hamravesh_list_databases, hamravesh_list_registries, hamravesh_billing, hamravesh_list_apikeys

Write (need ALLOW_WRITE=1): hamravesh_restart_app, hamravesh_redeploy_app, hamravesh_scale_app, hamravesh_set_app_enabled, hamravesh_update_app_envs, hamravesh_create_app, hamravesh_create_apikey, hamravesh_delete_app/hamravesh_delete_apikey (need ALLOW_DELETE=1)

Generic: hamravesh_request — any method/path (GET free; write/delete follow the flags).

Reference

• ENDPOINTS.md — categorized endpoint catalog.
• WRITE-ENDPOINTS.md — request-body shapes for all 162 write endpoints.
• LIVE-STATUS.md — live status of each endpoint with an admin account.
• ENDPOINTS-RAW.txt — raw list of all 578 method+path pairs.

Develop

npm ci
npm test        # network-free: checks tools + write guard

مجوز / License

MIT © محمد باختری — Mohammad Bakhtari