hamravesh-mcp 0.1.0

package/src/index.js

@@ -0,0 +1,546 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * Hamravesh MCP server — کنترل کنسول هم‌روش از داخل Claude بدون ورود به پنل.
+ *
+ * پیکربندی از طریق متغیرهای محیطی:
+ *   HAMRAVESH_API_KEY     کلید API هم‌روش (توصیه‌شده)
+ *   HAMRAVESH_EMAIL       (جایگزین) ایمیل حساب
+ *   HAMRAVESH_PASSWORD    (جایگزین) رمز حساب
+ *   HAMRAVESH_OTP         (اختیاری) کد دومرحله‌ای
+ *   HAMRAVESH_ORG         سازمان پیش‌فرض (مثل wgcup)
+ *   HAMRAVESH_BASE        (اختیاری) base URL، پیش‌فرض https://api.hamravesh.com
+ *   HAMRAVESH_ALLOW_WRITE = "1" تا ابزارهای تغییردهنده فعال شوند (پیش‌فرض: خاموش)
+ *   HAMRAVESH_ALLOW_DELETE= "1" تا ابزارهای حذف فعال شوند (پیش‌فرض: خاموش)
+ */
+import { readFileSync } from "node:fs";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { HamraveshClient, HamraveshError } from "./client.js";
+
+// --- بارگذاری اختیاری .env برای تست لوکال ---
+try {
+  const env = readFileSync(new URL("../.env", import.meta.url), "utf8");
+  if (env.length <= 256 * 1024) {
+    for (const line of env.split("\n")) {
+      const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+      if (m && process.env[m[1]] === undefined) {
+        process.env[m[1]] = m[2].replace(/^["']|["']$/g, "");
+      }
+    }
+  }
+} catch {
+  /* .env نبود، مهم نیست */
+}
+
+// --- نسخه و راهنمای خط فرمان / version + CLI help ---
+const PKG = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  } catch {
+    return { version: "?" };
+  }
+})();
+
+const HELP = `hamravesh-mcp v${PKG.version} — MCP server for the Hamravesh / Darkube console.
+
+This is an MCP server — it normally runs under an MCP client (Claude, Cursor, VS Code…),
+not by hand. Configure it with environment variables:
+
+  HAMRAVESH_API_KEY      your Hamravesh API key  (Org settings → Security → API Keys)
+  HAMRAVESH_EMAIL / HAMRAVESH_PASSWORD   alternative login (+ HAMRAVESH_OTP if 2FA)
+  HAMRAVESH_ORG          default organization name
+  HAMRAVESH_ALLOW_WRITE=1    enable write tools  (off by default)
+  HAMRAVESH_ALLOW_DELETE=1   enable delete tools (off by default)
+
+Add to Claude Code in one line:
+  claude mcp add hamravesh --env HAMRAVESH_API_KEY=YOUR_KEY --env HAMRAVESH_ORG=YOUR_ORG -- npx -y hamravesh-mcp
+
+Docs: https://github.com/bakhtarimohammad/hamravesh-mcp
+──────────────────────────────────────────────────────────────────────────
+این یک سرور MCP است و معمولاً زیرِ یک کلاینتِ MCP (مثل Claude) اجرا می‌شود، نه دستی.
+با متغیرهای محیطیِ بالا تنظیمش کن. کلیدِ API را از پنل بساز: تنظیماتِ سازمان ← امنیت ← API Keys.
+یا ساده‌تر: این را به Claude بگو «MCP هم‌روش را برایم نصب کن، کلیدم این است: …».`;
+
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) {
+  console.log(HELP);
+  process.exit(0);
+}
+if (argv.includes("--version") || argv.includes("-v")) {
+  console.log(PKG.version);
+  process.exit(0);
+}
+
+const CFG = {
+  allowWrite: process.env.HAMRAVESH_ALLOW_WRITE === "1" || process.env.HAMRAVESH_ALLOW_WRITE === "true",
+  allowDelete: process.env.HAMRAVESH_ALLOW_DELETE === "1" || process.env.HAMRAVESH_ALLOW_DELETE === "true",
+  org: process.env.HAMRAVESH_ORG || "",
+};
+
+let client;
+try {
+  client = new HamraveshClient({
+    apiKey: process.env.HAMRAVESH_API_KEY,
+    email: process.env.HAMRAVESH_EMAIL,
+    password: process.env.HAMRAVESH_PASSWORD,
+    otp: process.env.HAMRAVESH_OTP,
+    org: process.env.HAMRAVESH_ORG,
+    base: process.env.HAMRAVESH_BASE,
+  });
+} catch (e) {
+  // پیامِ مهربان: اگر کسی بدونِ تنظیمات اجراش کرد، راهنما را نشان بده (نه ارورِ خشک)
+  console.error("hamravesh-mcp: " + (e?.message || e) + "\n");
+  console.error(HELP);
+  process.exit(1);
+}
+
+// --- کمکی‌ها ---
+const MAX_TEXT = 200_000; // سقف حجم پاسخ برای جلوگیری از پرشدن context
+/** رازها را از متن پاک می‌کند تا در پیام خطا لو نروند. */
+function redact(s) {
+  let out = String(s ?? "");
+  for (const k of ["HAMRAVESH_API_KEY", "HAMRAVESH_PASSWORD", "HAMRAVESH_OTP"]) {
+    const v = process.env[k];
+    if (v) out = out.split(v).join("***");
+  }
+  return out.replace(/(Api-Key|Bearer)\s+[A-Za-z0-9._-]+/g, "$1 ***");
+}
+const T = (text) => {
+  let s = redact(text);
+  if (s.length > MAX_TEXT) s = s.slice(0, MAX_TEXT) + `\n…(بریده شد؛ ${s.length} کاراکتر بود)`;
+  return { content: [{ type: "text", text: s }] };
+};
+const J = (obj) => T(typeof obj === "string" ? obj : JSON.stringify(obj, null, 2));
+const ERR = (text) => ({ content: [{ type: "text", text: redact(text) }], isError: true });
+
+const APP_FIELDS =
+  "id,name,namespace,cluster,state,creation_method,custom_domain_address," +
+  "ram_limit,cpu_request,replicas,is_enabled,enable_SSL,image_repo,image_tag," +
+  "git_repo_url,git_branch_name,is_deployable,type";
+
+/** @type {Array<{name:string,description:string,inputSchema:any,write?:boolean,destructive?:boolean,handler:(a:any)=>Promise<any>}>} */
+const TOOLS = [
+  // ---------- خواندنی ----------
+  {
+    name: "hamravesh_whoami",
+    description: "پروفایل کاربر + فهرست سازمان‌ها، نقش‌ها، بودجه و کلاسترها.",
+    inputSchema: { type: "object", properties: {} },
+    handler: async () => {
+      const { body } = await client.get("/api/v2/users/profile");
+      const orgs = (body.organizations || []).map((o) => ({
+        id: o.id,
+        name: o.name,
+        roles: o.current_user_roles,
+        budget: o.budget,
+        is_restricted: o.is_restricted,
+      }));
+      return J({ full_name: body.full_name, email: body.email, organizations: orgs });
+    },
+  },
+  {
+    name: "hamravesh_list_apps",
+    description: "فهرست اپ‌های دارکوب یک سازمان (با وضعیت، دامنه، منابع، replicas).",
+    inputSchema: {
+      type: "object",
+      properties: { org: { type: "string", description: "نام سازمان؛ پیش‌فرض از تنظیمات" } },
+    },
+    handler: async (a) => {
+      const { body } = await client.get("/api/v1/darkube/apps/", {
+        org: a.org,
+        params: { limit: 555, offset: 0, fields: APP_FIELDS },
+      });
+      return J(body.results || body);
+    },
+  },
+  {
+    name: "hamravesh_get_app",
+    description: "جزئیات کامل یک اپ دارکوب (env، دامنه، منابع، بیلد، وضعیت).",
+    inputSchema: {
+      type: "object",
+      properties: { app_id: { type: "string" }, org: { type: "string" } },
+      required: ["app_id"],
+    },
+    handler: async (a) => J((await client.get(`/api/v1/darkube/apps/${a.app_id}/`, { org: a.org })).body),
+  },
+  {
+    name: "hamravesh_app_containers",
+    description: "فهرست پادها/کانتینرهای یک اپ.",
+    inputSchema: {
+      type: "object",
+      properties: { app_id: { type: "string" }, org: { type: "string" } },
+      required: ["app_id"],
+    },
+    handler: async (a) =>
+      J((await client.get(`/api/v1/darkube/apps/${a.app_id}/app_containers/`, { org: a.org })).body),
+  },
+  {
+    name: "hamravesh_app_logs",
+    description: "لاگ‌های اخیر یک اپ. می‌توان pod_name و container_name داد.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        app_id: { type: "string" },
+        pod_name: { type: "string" },
+        container_name: { type: "string" },
+        previous: { type: "boolean", description: "لاگ نمونه‌ی قبلی (کرش‌شده)" },
+        org: { type: "string" },
+      },
+      required: ["app_id"],
+    },
+    handler: async (a) =>
+      J(
+        (
+          await client.get(`/api/v1/darkube/apps/${a.app_id}/app_log/`, {
+            org: a.org,
+            params: { pod_name: a.pod_name, container_name: a.container_name, previous: a.previous },
+          })
+        ).body
+      ),
+  },
+  {
+    name: "hamravesh_app_manifests",
+    description: "منیفست‌های Kubernetes یک اپ (YAML).",
+    inputSchema: {
+      type: "object",
+      properties: { app_id: { type: "string" }, org: { type: "string" } },
+      required: ["app_id"],
+    },
+    handler: async (a) =>
+      J((await client.get(`/api/v1/darkube/apps/${a.app_id}/manifests/`, { org: a.org })).body),
+  },
+  {
+    name: "hamravesh_app_builds",
+    description: "تاریخچه‌ی بیلدهای یک اپ.",
+    inputSchema: {
+      type: "object",
+      properties: { app_id: { type: "string" }, limit: { type: "number" }, org: { type: "string" } },
+      required: ["app_id"],
+    },
+    handler: async (a) =>
+      J(
+        (
+          await client.get(`/api/v1/darkube/build/app/${a.app_id}/`, {
+            org: a.org,
+            params: { limit: Math.min(Math.max(Number(a.limit) || 10, 1), 200), offset: 0 },
+          })
+        ).body
+      ),
+  },
+  {
+    name: "hamravesh_list_databases",
+    description: "فهرست دیتابیس‌های مدیریت‌شده (DBaaS) یک سازمان.",
+    inputSchema: { type: "object", properties: { org: { type: "string" } } },
+    handler: async (a) => J((await client.get("/dbaas/api/v1/app/database/", { org: a.org })).body),
+  },
+  {
+    name: "hamravesh_list_registries",
+    description: "فهرست کانتینر رجیستری‌ها و مصرف فضای آن‌ها.",
+    inputSchema: { type: "object", properties: { org: { type: "string" } } },
+    handler: async (a) => J((await client.get("/api/v1/registry/", { org: a.org })).body),
+  },
+  {
+    name: "hamravesh_billing",
+    description: "وضعیت مالی سازمان: کیف‌پول‌ها، بودجه و بدهی.",
+    inputSchema: { type: "object", properties: { org: { type: "string" } } },
+    handler: async (a) => {
+      const org = a.org || CFG.org;
+      const prof = (await client.get("/api/v2/users/profile")).body;
+      const o = (prof.organizations || []).find((x) => x.name === org) || {};
+      const wallets = (await client.get("/api/v1/billing/wallets/", { org }).catch(() => ({ body: null }))).body;
+      let account = null;
+      if (o.billing_account_id) {
+        account = (
+          await client
+            .get(`/api/v1/billing/billing-accounts/${o.billing_account_id}/`, { org })
+            .catch(() => ({ body: null }))
+        ).body;
+      }
+      return J({ org, budget: o.budget, is_restricted: o.is_restricted, account, wallets });
+    },
+  },
+  {
+    name: "hamravesh_list_apikeys",
+    description: "فهرست کلیدهای API سازمان.",
+    inputSchema: { type: "object", properties: { org: { type: "string" } } },
+    handler: async (a) => J((await client.get("/api/v1/apikeys/", { org: a.org })).body),
+  },
+
+  // ---------- نوشتنی (نیازمند ALLOW_WRITE) ----------
+  {
+    name: "hamravesh_restart_app",
+    description: "ری‌استارت یک اپ (همه‌ی پادها دوباره راه می‌افتند).",
+    write: true,
+    inputSchema: {
+      type: "object",
+      properties: { app_id: { type: "string" }, org: { type: "string" } },
+      required: ["app_id"],
+    },
+    handler: async (a) =>
+      J((await client.request("POST", `/api/v1/darkube/apps/${a.app_id}/restart/`, { org: a.org, body: {} })).body),
+  },
+  {
+    name: "hamravesh_redeploy_app",
+    description: "دیپلوی مجدد اپ از روی آخرین کامیت/بیلد.",
+    write: true,
+    inputSchema: {
+      type: "object",
+      properties: { app_id: { type: "string" }, org: { type: "string" } },
+      required: ["app_id"],
+    },
+    handler: async (a) =>
+      J(
+        (
+          await client.get("/api/v1/darkube/build/build_last_commit/", {
+            org: a.org,
+            params: { app_id: a.app_id, deploy: true },
+          })
+        ).body
+      ),
+  },
+  {
+    name: "hamravesh_scale_app",
+    description: "تغییر تعداد replica های یک اپ.",
+    write: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        app_id: { type: "string" },
+        replicas: { type: "number" },
+        org: { type: "string" },
+      },
+      required: ["app_id", "replicas"],
+    },
+    handler: async (a) =>
+      J(
+        (
+          await client.request("PATCH", `/api/v1/darkube/apps/${a.app_id}/`, {
+            org: a.org,
+            body: { fields: ["replicas"], replicas: a.replicas },
+          })
+        ).body
+      ),
+  },
+  {
+    name: "hamravesh_set_app_enabled",
+    description: "روشن/خاموش کردن یک اپ (is_enabled).",
+    write: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        app_id: { type: "string" },
+        enabled: { type: "boolean" },
+        org: { type: "string" },
+      },
+      required: ["app_id", "enabled"],
+    },
+    handler: async (a) =>
+      J(
+        (
+          await client.request("PATCH", `/api/v1/darkube/apps/${a.app_id}/`, {
+            org: a.org,
+            body: { fields: ["is_enabled"], is_enabled: a.enabled },
+          })
+        ).body
+      ),
+  },
+  {
+    name: "hamravesh_update_app_envs",
+    description:
+      "به‌روزرسانی متغیرهای محیطی (env) یک اپ. ⚠️ ابتدا با hamravesh_get_app شکل فعلی envs را ببین؛ این کل آرایه را جایگزین می‌کند.",
+    write: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        app_id: { type: "string" },
+        envs: { type: "array", items: { type: "object" }, description: "آرایه‌ی کامل env ها" },
+        org: { type: "string" },
+      },
+      required: ["app_id", "envs"],
+    },
+    handler: async (a) =>
+      J(
+        (
+          await client.request("PATCH", `/api/v1/darkube/apps/${a.app_id}/`, {
+            org: a.org,
+            body: { fields: ["envs"], envs: a.envs },
+          })
+        ).body
+      ),
+  },
+  {
+    name: "hamravesh_create_app",
+    description:
+      "ساخت یک اپِ داکر-ایمیجِ جدید در دارکوب (بدنه‌اش با تست زنده تأیید شده). " +
+      "به plan (uuid پلن منابع)، namespace (id عددی namespace) و organization (id عددی سازمان) نیاز دارد — " +
+      "این‌ها را از hamravesh_get_app روی یک اپ موجود بگیر. مثال wgcup: organization=24772, namespace=165693, plan=73904144-6592-40ce-a96f-3789f611b5e4.",
+    write: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "نام اپ (بعداً تغییرناپذیر)" },
+        image_repo: { type: "string", description: "آدرس ایمیج، مثل traefik/whoami" },
+        image_tag: { type: "string", description: "تگ ایمیج، مثل latest" },
+        service_port: { type: "number", description: "پورت سرویس/کانتینر، مثل 80" },
+        plan: { type: "string", description: "uuid پلن منابع" },
+        namespace: { type: "number", description: "id عددی namespace" },
+        organization: { type: "number", description: "id عددی سازمان" },
+        replicas: { type: "number", description: "پیش‌فرض 1" },
+        org: { type: "string", description: "نام سازمان برای هدر X-Organization" },
+      },
+      required: ["name", "image_repo", "image_tag", "service_port", "plan", "namespace", "organization"],
+    },
+    handler: async (a) => {
+      const port = Number(a.service_port);
+      const body = {
+        image_repo: a.image_repo,
+        image_tag: a.image_tag,
+        builder: "dockerfile",
+        creation_method: "docker_image",
+        name: a.name,
+        svc: { type: "ClusterIP", ports: { main: { protocol: "TCP", servicePort: port, containerPort: port } } },
+        command: "",
+        args: "",
+        readiness_probe_path: "",
+        custom_config: {},
+        plan: a.plan,
+        replicas: Number(a.replicas) || 1,
+        backup_config: null,
+        namespace: Number(a.namespace),
+        deploy_context: null,
+        ssl_challenge_type: "dns01",
+        organization: Number(a.organization),
+      };
+      return J((await client.request("POST", "/api/v1/darkube/apps/", { org: a.org, body })).body);
+    },
+  },
+  {
+    name: "hamravesh_delete_app",
+    description: "حذفِ کاملِ یک اپ دارکوب (برگشت‌ناپذیر). نیازمند ALLOW_DELETE.",
+    write: true,
+    destructive: true,
+    inputSchema: {
+      type: "object",
+      properties: { app_id: { type: "string" }, org: { type: "string" } },
+      required: ["app_id"],
+    },
+    handler: async (a) => {
+      const { status, body } = await client.request("DELETE", `/api/v1/darkube/apps/${a.app_id}/`, { org: a.org });
+      return J(body !== undefined && body !== "" ? body : `حذف شد (HTTP ${status})`);
+    },
+  },
+  {
+    name: "hamravesh_create_apikey",
+    description: "ساخت یک کلید API جدید برای سازمان. مقدار کلید فقط همین یک بار برمی‌گردد.",
+    write: true,
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string" }, org: { type: "string" } },
+      required: ["name"],
+    },
+    handler: async (a) =>
+      J((await client.request("POST", "/api/v1/apikeys/", { org: a.org, body: { name: a.name } })).body),
+  },
+  {
+    name: "hamravesh_delete_apikey",
+    description: "حذف یک کلید API (با شناسه‌ی id، نه مقدار value).",
+    write: true,
+    destructive: true,
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string" }, org: { type: "string" } },
+      required: ["id"],
+    },
+    handler: async (a) => {
+      const { status, body } = await client.request("DELETE", `/api/v1/apikeys/${a.id}/`, { org: a.org });
+      return J(body !== undefined && body !== "" ? body : `حذف شد (HTTP ${status})`);
+    },
+  },
+
+  // ---------- جوکر: هر endpoint دلخواه ----------
+  {
+    name: "hamravesh_request",
+    description:
+      "درخواست خام به هر endpoint هم‌روش (برای کارهایی که ابزار اختصاصی ندارند). " +
+      "GET همیشه مجاز است؛ POST/PUT/PATCH نیازمند ALLOW_WRITE و DELETE نیازمند ALLOW_DELETE است. " +
+      "فهرست کامل مسیرها در ENDPOINTS.md پروژه است.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        method: { type: "string", enum: ["GET", "POST", "PUT", "PATCH", "DELETE"] },
+        path: { type: "string", description: "مثل /api/v1/darkube/plans/" },
+        org: { type: "string" },
+        params: { type: "object", description: "کوئری‌پارامترها" },
+        body: { type: "object", description: "بدنه‌ی JSON برای متدهای نوشتنی" },
+      },
+      required: ["method", "path"],
+    },
+    handler: async (a) => {
+      const m = String(a.method).toUpperCase();
+      const path = String(a.path || "");
+      if (!path.startsWith("/"))
+        return ERR("path باید مسیر نسبی باشد و با / شروع شود (URL کامل مجاز نیست).");
+      const isWrite = m !== "GET";
+      const isDelete = m === "DELETE";
+      if (isWrite && !CFG.allowWrite)
+        return ERR(`متد ${m} نیازمند فعال‌بودن نوشتن است. HAMRAVESH_ALLOW_WRITE=1 را تنظیم کن.`);
+      if (isDelete && !CFG.allowDelete)
+        return ERR("DELETE نیازمند HAMRAVESH_ALLOW_DELETE=1 است.");
+      const { status, body } = await client.request(m, path, { org: a.org, params: a.params, body: a.body });
+      return J({ status, body });
+    },
+  },
+];
+
+const BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
+
+const server = new Server(
+  { name: "hamravesh-mcp", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map((t) => {
+    let description = t.description;
+    if (t.write && !CFG.allowWrite) description += "  (غیرفعال — برای فعال‌سازی HAMRAVESH_ALLOW_WRITE=1)";
+    return { name: t.name, description, inputSchema: t.inputSchema };
+  }),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const tool = BY_NAME.get(req.params.name);
+  if (!tool) return ERR(`ابزار ناشناخته: ${req.params.name}`);
+  const args = req.params.arguments || {};
+  if (tool.write && !CFG.allowWrite)
+    return ERR(
+      `«${tool.name}» یک عملیات نوشتنی است و فعلاً خاموش است. برای فعال‌سازی HAMRAVESH_ALLOW_WRITE=1 را در تنظیمات MCP بگذار.`
+    );
+  if (tool.destructive && !CFG.allowDelete)
+    return ERR(`«${tool.name}» یک عملیات حذف است. برای فعال‌سازی HAMRAVESH_ALLOW_DELETE=1 را تنظیم کن.`);
+  try {
+    return await tool.handler(args);
+  } catch (e) {
+    if (e instanceof HamraveshError) return ERR(`خطای هم‌روش — ${e.message}`);
+    return ERR(`خطا: ${e?.message || String(e)}`);
+  }
+});
+
+process.on("unhandledRejection", (reason) => {
+  console.error("hamravesh-mcp: unhandledRejection —", redact(reason?.stack || reason));
+});
+
+try {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(
+    `hamravesh-mcp آماده است. auth=${client.authMode} org=${CFG.org || "(تعیین‌نشده)"} ` +
+      `write=${CFG.allowWrite ? "on" : "off"} delete=${CFG.allowDelete ? "on" : "off"}`
+  );
+} catch (e) {
+  console.error("hamravesh-mcp: اتصال ناموفق —", redact(e?.message || String(e)));
+  process.exit(1);
+}