# hamravesh-mcp

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

[![npm version](https://img.shields.io/npm/v/hamravesh-mcp.svg)](https://www.npmjs.com/package/hamravesh-mcp)
[![CI](https://github.com/bakhtarimohammad/hamravesh-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/bakhtarimohammad/hamravesh-mcp/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/hamravesh-mcp.svg)](./LICENSE)
[![node](https://img.shields.io/node/v/hamravesh-mcp.svg)](https://nodejs.org)

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

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an AI assistant manage your [Hamravesh](https://hamravesh.com) (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 با تمدیدِ خودکار).
- 🧰 **۲۱ ابزار** — خواندنی (اپ‌ها، لاگ، کانتینرها، منیفست، بیلدها، دیتابیس، رجیستری، صورتحساب، کلیدها)، نوشتنی (ری‌استارت، دیپلوی، اسکیل، روشن/خاموش، تغییرِ env، ساخت/حذفِ اپ، ساخت/حذفِ کلید) و یک ابزارِ جوکر به‌نامِ `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، یک خط:**

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

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

```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` | توصیه‌شده | سازمانِ پیش‌فرض (مثل `wgcup`)؛ در هر ابزار قابلِ تغییر. |
| `HAMRAVESH_BASE` | نه | پیش‌فرض `https://api.hamravesh.com`. |
| `HAMRAVESH_ALLOW_WRITE` | نه | `1` برای فعال‌کردنِ ابزارهای نوشتن (پیش‌فرض خاموش). |
| `HAMRAVESH_ALLOW_DELETE` | نه | `1` برای فعال‌کردنِ ابزارهای حذف (پیش‌فرض خاموش). |

### ایمنی

به‌صورتِ پیش‌فرض فقط **خواندن** مجاز است؛ هیچ تغییری روی سرویسِ زنده رخ نمی‌دهد. برای تغییر/حذف باید فلگ‌های بالا را روی `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`](ENDPOINTS.md) — کاتالوگِ دسته‌بندی‌شده.
- [`WRITE-ENDPOINTS.md`](WRITE-ENDPOINTS.md) — شکلِ بدنهٔ همهٔ ۱۶۲ درخواستِ نوشتنی.
- [`LIVE-STATUS.md`](LIVE-STATUS.md) — وضعیتِ زندهٔ هر endpoint با حسابِ admin.
- [`ENDPOINTS-RAW.txt`](ENDPOINTS-RAW.txt) — لیستِ خامِ همهٔ ۵۷۸ آدرس (متد+مسیر).

### توسعه

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

---

## English

### Features

- 🔑 **Two auth modes** — a stable **API key** (`Authorization: Api-Key …`, recommended) or **email/password** (JWT with auto-refresh).
- 🧰 **21 tools** — read (apps, logs, containers, manifests, builds, databases, registries, billing, api-keys), write (restart, redeploy, scale, enable/disable, update env, create/delete app, create/delete api-key), plus a generic `hamravesh_request` escape hatch for any endpoint.
- 🔒 **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:**

```bash
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`):

```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 (e.g. `wgcup`); 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). |

### 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`](ENDPOINTS.md) — categorized endpoint catalog.
- [`WRITE-ENDPOINTS.md`](WRITE-ENDPOINTS.md) — request-body shapes for all 162 write endpoints.
- [`LIVE-STATUS.md`](LIVE-STATUS.md) — live status of each endpoint with an admin account.
- [`ENDPOINTS-RAW.txt`](ENDPOINTS-RAW.txt) — raw list of all 578 method+path pairs.

### Develop

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

---

## مجوز / License

[MIT](./LICENSE) © محمد باختری — Mohammad Bakhtari