@nimbus-dev/connectors 0.1.0

package/connectors/flux/src/search-filter.ts

@@ -0,0 +1,42 @@
+import {
+  asRecord,
+  makeQueryFilter,
+  nestedString,
+  type SearchMatchOptions,
+} from "../../../shared/search-filter.ts";
+
+export type FluxSearchMatchOptions = SearchMatchOptions;
+
+function readyConditionText(row: Record<string, unknown>): string {
+  const status = asRecord(row["status"]);
+  const conditions = status?.["conditions"];
+  if (!Array.isArray(conditions)) {
+    return "";
+  }
+  for (const entry of conditions) {
+    const c = asRecord(entry);
+    if (c === undefined) {
+      continue;
+    }
+    if (c["type"] === "Ready") {
+      const reason = typeof c["reason"] === "string" ? c["reason"] : "";
+      const message = typeof c["message"] === "string" ? c["message"] : "";
+      return `${reason} ${message}`;
+    }
+  }
+  return "";
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asRecord(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [
+    nestedString(row, ["metadata", "name"]),
+    nestedString(row, ["metadata", "namespace"]),
+    readyConditionText(row),
+  ];
+}
+
+export const filterFluxResources = makeQueryFilter(fieldsOf);

package/connectors/flux/src/server.ts

@@ -0,0 +1,182 @@
+import { FLUX_KINDS, type FluxKindEntry, trimTrailingSlash } from "@nimbus-dev/sdk";
+import { z } from "zod";
+import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { fetchWithTimeout, mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import {
+  runReadOnlyMcpConnector,
+  type ZodToolRegistrar,
+} from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterFluxResources } from "./search-filter.ts";
+
+const KIND_VALUES = FLUX_KINDS.map((e) => e.kind) as [string, ...string[]];
+
+function kindEntry(kind: string): FluxKindEntry {
+  const found = FLUX_KINDS.find((e) => e.kind === kind);
+  if (found === undefined) {
+    throw new Error(`Unknown Flux kind: ${kind}`);
+  }
+  return found;
+}
+
+function apiBase(): string {
+  const v = process.env["FLUX_API_URL"]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error("FLUX_API_URL is not set");
+  }
+  return trimTrailingSlash(v);
+}
+
+function authHeader(): Record<string, string> {
+  const t = process.env["FLUX_TOKEN"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("FLUX_TOKEN is not set");
+  }
+  return { Authorization: `Bearer ${t}`, Accept: "application/json" };
+}
+
+async function agGet(path: string): Promise<unknown> {
+  const res = await fetchWithTimeout(`${apiBase()}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Flux ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function itemsFrom(root: unknown): unknown[] {
+  if (Array.isArray(root)) {
+    return root;
+  }
+  const items = (root as { items?: unknown } | null)?.items;
+  return Array.isArray(items) ? items : [];
+}
+
+function listPath(entry: FluxKindEntry, namespace?: string): string {
+  const prefix = `/apis/${entry.group}/${entry.version}`;
+  if (namespace !== undefined && namespace !== "") {
+    return `${prefix}/namespaces/${encodeURIComponent(namespace)}/${entry.plural}`;
+  }
+  return `${prefix}/${entry.plural}`;
+}
+
+/** Request a reconcile by annotating reconcile.fluxcd.io/requestedAt on the CR (the same mechanism
+ *  `flux reconcile` uses). Returns the RFC3339 timestamp written. Reuses kindEntry/listPath so the
+ *  write path shares the read path's single source of truth — no new kind strings or version drift. */
+async function fluxReconcile(kind: string, namespace: string, name: string): Promise<string> {
+  const entry = kindEntry(kind);
+  const path = `${listPath(entry, namespace)}/${encodeURIComponent(name)}`;
+  const requestedAt = new Date().toISOString();
+  const res = await fetchWithTimeout(`${apiBase()}${path}`, {
+    method: "PATCH",
+    headers: { ...authHeader(), "Content-Type": "application/merge-patch+json" },
+    body: JSON.stringify({
+      metadata: { annotations: { "reconcile.fluxcd.io/requestedAt": requestedAt } },
+    }),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Flux reconcile ${path} ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return requestedAt;
+}
+
+export function registerFluxTools(reg: ZodToolRegistrar, server: unknown): void {
+  // Despite the read-only helper's name, this connector exposes write tools. The consent
+  // kit needs the real server, which the helper now passes through as its second argument.
+  const registerWriteTool = createWriteToolRegistrar(server as ConsentServer, {
+    connector: "flux",
+    scopeEnv: "NIMBUS_MCP_FLUX_WRITE_SCOPE",
+    scopeKinds: ["namespace"],
+  });
+
+  reg(
+    "flux_list",
+    "List Flux Custom Resources of one `kind` (default `kustomization`). Reads the Kubernetes API: all-namespaces by default, or scoped to `namespace` when given. `limit` (default 200) caps the returned `items` client-side. Returns the raw Kubernetes List envelope.",
+    z.object({
+      kind: z.enum(KIND_VALUES).optional(),
+      namespace: z.string().optional(),
+      limit: z.number().int().min(1).max(500).optional(),
+    }),
+    async (p) => {
+      const entry = kindEntry(p.kind ?? "kustomization");
+      const root = await agGet(listPath(entry, p.namespace));
+      const items = itemsFrom(root);
+      const cap = p.limit ?? 200;
+      return jsonResult({ items: items.slice(0, cap) });
+    },
+  );
+
+  reg(
+    "flux_get",
+    "Fetch one Flux Custom Resource by `kind`, `namespace`, and `name` (`/apis/<group>/<version>/namespaces/<ns>/<plural>/<name>`). Throws when no such resource exists.",
+    z.object({
+      kind: z.enum(KIND_VALUES),
+      namespace: z.string().min(1),
+      name: z.string().min(1),
+    }),
+    async (p) => {
+      const entry = kindEntry(p.kind);
+      const path = `${listPath(entry, p.namespace)}/${encodeURIComponent(p.name)}`;
+      return jsonResult(await agGet(path));
+    },
+  );
+
+  reg(
+    "flux_search",
+    "Substring search across Flux Custom Resources of one `kind` (default `kustomization`). Lists the kind across all namespaces and matches the query (case-insensitive) against resource name, namespace, and the Ready condition's reason/message. Returns a `{ matches: [...] }` envelope.",
+    z.object({
+      query: z.string().min(1),
+      kind: z.enum(KIND_VALUES).optional(),
+      limit: z.number().int().min(1).max(200).optional(),
+    }),
+    async (p) => {
+      const entry = kindEntry(p.kind ?? "kustomization");
+      const root = await agGet(listPath(entry));
+      const matches = filterFluxResources(itemsFrom(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+
+  registerWriteTool(
+    "flux_kustomization_reconcile",
+    {
+      mutates: "flux.kustomization.reconcile",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "namespace", value: p.namespace }),
+    },
+    "Request a reconcile of a Flux Kustomization by annotating reconcile.fluxcd.io/requestedAt (PATCH the CR; requires HITL flux.kustomization.reconcile, and the SA's `patch` RBAC verb on kustomizations). Async — verify via the next metadata sync.",
+    z.object({ namespace: z.string().min(1), name: z.string().min(1) }),
+    async (p) =>
+      jsonResult({
+        status: "requested",
+        name: p.name,
+        requestedAt: await fluxReconcile("kustomization", p.namespace, p.name),
+      }),
+  );
+
+  registerWriteTool(
+    "flux_helmrelease_reconcile",
+    {
+      mutates: "flux.helmrelease.reconcile",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "namespace", value: p.namespace }),
+    },
+    "Request a reconcile of a Flux HelmRelease by annotating reconcile.fluxcd.io/requestedAt (PATCH the CR; requires HITL flux.helmrelease.reconcile, and the SA's `patch` RBAC verb on helmreleases). Async — verify via the next metadata sync.",
+    z.object({ namespace: z.string().min(1), name: z.string().min(1) }),
+    async (p) =>
+      jsonResult({
+        status: "requested",
+        name: p.name,
+        requestedAt: await fluxReconcile("helm_release", p.namespace, p.name),
+      }),
+  );
+}
+
+export async function startConnector(): Promise<void> {
+  await runReadOnlyMcpConnector("nimbus-flux", registerFluxTools);
+}
+
+if (import.meta.main) await startConnector();

package/connectors/gcp/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.gcp",
+  "displayName": "Google Cloud",
+  "version": "0.1.0",
+  "description": "GCP CLI connector (IAM control plane + OAuth). Service-specific googleapis.com hosts (storage, bigquery, etc.) are a known Task 14 follow-up. Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["cloudresourcemanager.googleapis.com", "oauth2.googleapis.com"]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/gcp/src/server.ts

@@ -0,0 +1,140 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
+import { runCliJson, runCliOk } from "../../../shared/run-cli-json.ts";
+
+function gcloudEnv(): Record<string, string | undefined> {
+  const e = { ...process.env } as Record<string, string | undefined>;
+  const cf = process.env["GOOGLE_APPLICATION_CREDENTIALS"]?.trim();
+  if (cf !== undefined && cf !== "") {
+    e["GOOGLE_APPLICATION_CREDENTIALS"] = cf;
+  }
+  return e;
+}
+
+async function gcloudJson(args: string[]): Promise<unknown> {
+  const cmd = ["gcloud", ...args, "--format", "json"];
+  const r = await runCliJson(cmd, gcloudEnv());
+  if (!r.ok) {
+    throw new Error(r.message);
+  }
+  return r.data ?? {};
+}
+
+const mcp = new McpServer({ name: "nimbus-gcp", version: "0.1.0" });
+
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+
+const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
+
+/**
+ * Every MUTATING gcp tool goes through here. Outside the gateway this adds the
+ * consent gate, the write-scope allow-list, the mutation budget and the audit record; inside
+ * the gateway it is a pass-through, because executor.ts (I2) is the gate there.
+ */
+const registerWriteTool = createWriteToolRegistrar(mcp, {
+  connector: "gcp",
+  scopeEnv: "NIMBUS_MCP_GCP_WRITE_SCOPE",
+  scopeKinds: ["project"],
+});
+
+reg(
+  "gcp_cloud_run_service_list",
+  "List Cloud Run services in a region.",
+  z.object({ projectId: z.string().min(1), region: z.string().min(1) }),
+  async (p) =>
+    jsonResult(
+      await gcloudJson([
+        "run",
+        "services",
+        "list",
+        `--project=${p.projectId}`,
+        `--region=${p.region}`,
+      ]),
+    ),
+);
+
+registerWriteTool(
+  "gcp_cloud_run_deploy",
+  {
+    mutates: "gcp.cloud_run.deploy",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "project", value: p.projectId }),
+  },
+  "Deploy a container image to Cloud Run.",
+  z.object({
+    projectId: z.string().min(1),
+    region: z.string().min(1),
+    service: z.string().min(1),
+    image: z.string().min(1),
+  }),
+  async (p) => {
+    const r = await runCliOk(
+      [
+        "gcloud",
+        "run",
+        "deploy",
+        p.service,
+        `--project=${p.projectId}`,
+        `--region=${p.region}`,
+        `--image=${p.image}`,
+        "--quiet",
+      ],
+      gcloudEnv(),
+    );
+    if (!r.ok) {
+      throw new Error(r.message);
+    }
+    return jsonResult({ ok: true });
+  },
+);
+
+registerWriteTool(
+  "gcp_gke_workload_restart",
+  {
+    mutates: "gcp.gke.workload.restart",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "project", value: p.projectId }),
+  },
+  "Restart a GKE deployment rollout via kubectl (uses current cluster credentials).",
+  z.object({
+    projectId: z.string().min(1),
+    location: z.string().min(1),
+    cluster: z.string().min(1),
+    namespace: z.string().min(1),
+    deployment: z.string().min(1),
+  }),
+  async (p) => {
+    const getCreds = await runCliOk(
+      [
+        "gcloud",
+        "container",
+        "clusters",
+        "get-credentials",
+        p.cluster,
+        `--project=${p.projectId}`,
+        `--zone=${p.location}`,
+      ],
+      gcloudEnv(),
+    );
+    if (!getCreds.ok) {
+      throw new Error(getCreds.message);
+    }
+    const r = await runCliOk(
+      ["kubectl", "rollout", "restart", "deployment", p.deployment, "-n", p.namespace],
+      gcloudEnv(),
+    );
+    if (!r.ok) {
+      throw new Error(r.message);
+    }
+    return jsonResult({ ok: true });
+  },
+);
+
+const transport = new StdioServerTransport();
+await mcp.connect(transport);

package/connectors/github/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.github",
+  "displayName": "GitHub",
+  "version": "0.1.0",
+  "description": "GitHub REST + GraphQL connector (PRs, issues, reviews, releases). Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.github.com", "uploads.github.com", "raw.githubusercontent.com"]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 300,
+  "minNimbusVersion": "0.2.0"
+}