@nimbus-dev/connectors 0.2.1 → 0.2.3

package/connectors/firebase/src/tools.ts

@@ -0,0 +1,106 @@
+import { mintGoogleAccessToken } from "@nimbus-dev/sdk";
+import { z } from "zod";
+import { matchesResult } from "../../../shared/mcp-search-tool.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterFirebaseReleases } from "./search-filter.ts";
+import { configuredAppIds, projectNumberFromAppId, serviceAccountFromEnv } from "./token.ts";
+
+const APP_DISTRIBUTION_API = "https://firebaseappdistribution.googleapis.com";
+
+// App Distribution OAuth2 tokens last ~1h; cache and refresh conservatively.
+let cachedToken: { token: string; expiresAt: number } | null = null;
+
+/**
+ * Forget the cached access token. Tests only: the cache is module state shared by every test in
+ * the process, and a token one test left behind lets a later tool call skip reading its
+ * credential entirely.
+ */
+export function __resetFirebaseTokenCacheForTests(): void {
+  cachedToken = null;
+}
+
+async function accessToken(): Promise<string> {
+  const now = Date.now();
+  if (cachedToken !== null && cachedToken.expiresAt > now + 60_000) {
+    return cachedToken.token;
+  }
+  const token = await mintGoogleAccessToken(serviceAccountFromEnv());
+  if (token === null) {
+    throw new Error("failed to mint a Firebase access token");
+  }
+  cachedToken = { token, expiresAt: now + 30 * 60 * 1000 };
+  return token;
+}
+
+async function appDistGet(path: string): Promise<unknown> {
+  const res = await fetch(`${APP_DISTRIBUTION_API}${path}`, {
+    headers: { Authorization: `Bearer ${await accessToken()}`, Accept: "application/json" },
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Firebase App Distribution ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function appBasePath(appId: string): string {
+  const projectNumber = projectNumberFromAppId(appId);
+  if (projectNumber === null) {
+    throw new Error(`cannot derive a project number from app id: ${appId}`);
+  }
+  return `/v1/projects/${encodeURIComponent(projectNumber)}/apps/${encodeURIComponent(appId)}`;
+}
+
+function releasesPath(appId: string, pageSize: number): string {
+  return `${appBasePath(appId)}/releases?pageSize=${String(pageSize)}`;
+}
+
+function releasePath(appId: string, releaseId: string): string {
+  return `${appBasePath(appId)}/releases/${encodeURIComponent(releaseId)}`;
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const FIREBASE_TOOL_NAMES = ["firebase_get", "firebase_list", "firebase_search"] as const;
+
+export function registerFirebaseTools(reg: ZodToolRegistrar): void {
+  reg(
+    "firebase_list",
+    "List Firebase App Distribution resources. When `appId` is omitted, returns the connector's configured app ids. When `appId` is provided, returns that app's most-recent releases via GET /v1/projects/<n>/apps/<appId>/releases (pageSize optional, default 50).",
+    z.object({
+      appId: z.string().min(1).optional(),
+      pageSize: z.number().int().min(1).max(100).optional(),
+    }),
+    async (p) => {
+      if (p.appId === undefined) {
+        return jsonResult({ appIds: configuredAppIds() });
+      }
+      return jsonResult(await appDistGet(releasesPath(p.appId, p.pageSize ?? 50)));
+    },
+  );
+
+  reg(
+    "firebase_get",
+    "Fetch a single Firebase App Distribution release via GET /v1/projects/<n>/apps/<appId>/releases/<releaseId>.",
+    z.object({
+      appId: z.string().min(1),
+      releaseId: z.string().min(1),
+    }),
+    async (p) => jsonResult(await appDistGet(releasePath(p.appId, p.releaseId))),
+  );
+
+  reg(
+    "firebase_search",
+    "Substring search across an app's recent releases. Matches the query against each release's display version, build version, release notes, and resource name (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    z.object({
+      appId: z.string().min(1),
+      query: z.string().min(1),
+      limit: z.number().int().min(1).max(100).optional(),
+    }),
+    async (p) => {
+      const root = await appDistGet(releasesPath(p.appId, 100));
+      const releases = (root as { releases?: unknown[] } | null)?.releases;
+      return matchesResult(releases, filterFirebaseReleases, p);
+    },
+  );
+}

package/connectors/flagsmith/src/server.ts

@@ -1,102 +1,6 @@
-import { z } from "zod";
-import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
 import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
-import { filterFlagsmithFeatures } from "./search-filter.ts";
-
-const DEFAULT_API_BASE = "https://api.flagsmith.com";
-
-function apiBase(): string {
-  const v = process.env["FLAGSMITH_API_BASE"]?.trim();
-  return v === undefined || v === "" ? DEFAULT_API_BASE : v;
-}
-
-function authHeader(): Record<string, string> {
-  const t = process.env["FLAGSMITH_TOKEN"]?.trim();
-  if (t === undefined || t === "") {
-    throw new Error("FLAGSMITH_TOKEN is not set");
-  }
-  return { Authorization: `Token ${t}`, Accept: "application/json" };
-}
-
-async function fsGet(path: string): Promise<unknown> {
-  const res = await fetch(`${apiBase()}/api/v1${path}`, { headers: authHeader() });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`Flagsmith ${String(res.status)}: ${text.slice(0, 400)}`);
-  }
-  return JSON.parse(text) as unknown;
-}
-
-function featuresFromPage(root: unknown): unknown[] {
-  if (Array.isArray(root)) {
-    return root;
-  }
-  const results = (root as { results?: unknown } | null)?.results;
-  return Array.isArray(results) ? results : [];
-}
+import { registerFlagsmithTools } from "./tools.ts";
 
 await runReadOnlyMcpConnector("nimbus-flagsmith", (reg) => {
-  reg(
-    "flagsmith_list",
-    "List Flagsmith projects, or feature flags for a project. Without `projectId`, returns the account's projects (`/projects/`). With `projectId`, returns that project's feature flags (`/projects/{projectId}/features/`), capped at `limit` (default 100).",
-    z.object({
-      projectId: z.number().int().optional(),
-      limit: z.number().int().min(1).max(500).optional(),
-    }),
-    async (p) => {
-      if (p.projectId === undefined) {
-        return jsonResult(await fsGet("/projects/"));
-      }
-      const search = new URLSearchParams({ page_size: String(p.limit ?? 100) });
-      return jsonResult(
-        await fsGet(
-          `/projects/${encodeURIComponent(String(p.projectId))}/features/?${search.toString()}`,
-        ),
-      );
-    },
-  );
-
-  reg(
-    "flagsmith_get",
-    "Fetch one Flagsmith feature flag by project id + feature name. Flagsmith has no GET-by-name endpoint, so this searches the project's features and narrows to the exact-name match. Throws when no match is found.",
-    z.object({
-      projectId: z.number().int(),
-      featureName: z.string().min(1),
-    }),
-    async (p) => {
-      const search = new URLSearchParams({ page_size: "100", search: p.featureName });
-      const root = await fsGet(
-        `/projects/${encodeURIComponent(String(p.projectId))}/features/?${search.toString()}`,
-      );
-      const match = featuresFromPage(root).find(
-        (f) =>
-          f !== null && typeof f === "object" && (f as { name?: unknown }).name === p.featureName,
-      );
-      if (match === undefined) {
-        throw new Error(`Flagsmith feature not found: ${p.featureName}`);
-      }
-      return jsonResult(match);
-    },
-  );
-
-  reg(
-    "flagsmith_search",
-    "Substring search across a project's feature flags. Matches the query against flag name, description, and tags (case-insensitive). Returns a `{ matches: [...] }` envelope.",
-    z.object({
-      projectId: z.number().int(),
-      query: z.string().min(1),
-      limit: z.number().int().min(1).max(200).optional(),
-    }),
-    async (p) => {
-      const search = new URLSearchParams({ page_size: "500" });
-      const root = await fsGet(
-        `/projects/${encodeURIComponent(String(p.projectId))}/features/?${search.toString()}`,
-      );
-      const matches = filterFlagsmithFeatures(featuresFromPage(root), {
-        query: p.query,
-        limit: p.limit,
-      });
-      return jsonResult({ matches });
-    },
-  );
+  registerFlagsmithTools(reg);
 });

package/connectors/flagsmith/src/tools.ts

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { createJsonGetter, envAuthHeaders, optionalEnv } from "../../../shared/env-json-api.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterFlagsmithFeatures } from "./search-filter.ts";
+
+const DEFAULT_API_BASE = "https://api.flagsmith.com";
+
+const fsGet = createJsonGetter({
+  // `optionalEnv`, not `optionalBaseUrl`: a trailing slash on the override is left as given.
+  base: () => `${optionalEnv("FLAGSMITH_API_BASE", DEFAULT_API_BASE)}/api/v1`,
+  label: "Flagsmith",
+  headers: envAuthHeaders({ env: "FLAGSMITH_TOKEN", scheme: "Token" }),
+});
+
+function featuresFromPage(root: unknown): unknown[] {
+  if (Array.isArray(root)) {
+    return root;
+  }
+  const results = (root as { results?: unknown } | null)?.results;
+  return Array.isArray(results) ? results : [];
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const FLAGSMITH_TOOL_NAMES = [
+  "flagsmith_list",
+  "flagsmith_get",
+  "flagsmith_search",
+] as const;
+
+export function registerFlagsmithTools(reg: ZodToolRegistrar): void {
+  reg(
+    "flagsmith_list",
+    "List Flagsmith projects, or feature flags for a project. Without `projectId`, returns the account's projects (`/projects/`). With `projectId`, returns that project's feature flags (`/projects/{projectId}/features/`), capped at `limit` (default 100).",
+    z.object({
+      projectId: z.number().int().optional(),
+      limit: z.number().int().min(1).max(500).optional(),
+    }),
+    async (p) => {
+      if (p.projectId === undefined) {
+        return jsonResult(await fsGet("/projects/"));
+      }
+      const search = new URLSearchParams({ page_size: String(p.limit ?? 100) });
+      return jsonResult(
+        await fsGet(
+          `/projects/${encodeURIComponent(String(p.projectId))}/features/?${search.toString()}`,
+        ),
+      );
+    },
+  );
+
+  reg(
+    "flagsmith_get",
+    "Fetch one Flagsmith feature flag by project id + feature name. Flagsmith has no GET-by-name endpoint, so this searches the project's features and narrows to the exact-name match. Throws when no match is found.",
+    z.object({
+      projectId: z.number().int(),
+      featureName: z.string().min(1),
+    }),
+    async (p) => {
+      const search = new URLSearchParams({ page_size: "100", search: p.featureName });
+      const root = await fsGet(
+        `/projects/${encodeURIComponent(String(p.projectId))}/features/?${search.toString()}`,
+      );
+      const match = featuresFromPage(root).find(
+        (f) =>
+          f !== null && typeof f === "object" && (f as { name?: unknown }).name === p.featureName,
+      );
+      if (match === undefined) {
+        throw new Error(`Flagsmith feature not found: ${p.featureName}`);
+      }
+      return jsonResult(match);
+    },
+  );
+
+  reg(
+    "flagsmith_search",
+    "Substring search across a project's feature flags. Matches the query against flag name, description, and tags (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    z.object({
+      projectId: z.number().int(),
+      query: z.string().min(1),
+      limit: z.number().int().min(1).max(200).optional(),
+    }),
+    async (p) => {
+      const search = new URLSearchParams({ page_size: "500" });
+      const root = await fsGet(
+        `/projects/${encodeURIComponent(String(p.projectId))}/features/?${search.toString()}`,
+      );
+      const matches = filterFlagsmithFeatures(featuresFromPage(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+}

package/connectors/flux/src/server.ts

@@ -1,6 +1,7 @@
 import { FLUX_KINDS, type FluxKindEntry, trimTrailingSlash } from "@nimbus-dev/sdk";
 import { z } from "zod";
 import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { createJsonGetter, envAuthHeaders, requiredEnv } from "../../../shared/env-json-api.ts";
 import { fetchWithTimeout, mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
 import {
   runReadOnlyMcpConnector,
@@ -18,30 +19,24 @@ function kindEntry(kind: string): FluxKindEntry {
   return found;
 }
 
+/** Only ONE trailing slash is dropped here — not `requiredBaseUrl`'s strip-them-all. */
 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);
+  return trimTrailingSlash(requiredEnv("FLUX_API_URL"));
 }
 
-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" };
-}
+/**
+ * `fetchWithTimeout`, not the global fetch: this is a self-hosted control plane,
+ * and one that stops answering must fail the tool call rather than hang it.
+ */
+/** Shared with the mutating request below, which adds its own Content-Type. */
+const authHeader = envAuthHeaders({ env: "FLUX_TOKEN" });
 
-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;
-}
+const agGet = createJsonGetter({
+  base: apiBase,
+  label: "Flux",
+  headers: authHeader,
+  fetch: fetchWithTimeout,
+});
 
 function itemsFrom(root: unknown): unknown[] {
   if (Array.isArray(root)) {
@@ -80,6 +75,24 @@ async function fluxReconcile(kind: string, namespace: string, name: string): Pro
   return requestedAt;
 }
 
+/** The Flux CRs a reconcile can be requested on. */
+const RECONCILABLE = [
+  {
+    tool: "flux_kustomization_reconcile",
+    kind: "kustomization",
+    mutates: "flux.kustomization.reconcile",
+    description:
+      "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.",
+  },
+  {
+    tool: "flux_helmrelease_reconcile",
+    kind: "helm_release",
+    mutates: "flux.helmrelease.reconcile",
+    description:
+      "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.",
+  },
+] as const;
+
 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.
@@ -140,39 +153,25 @@ export function registerFluxTools(reg: ZodToolRegistrar, server: unknown): void
     },
   );
 
-  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),
-      }),
-  );
+  // Both reconcile tools are the same annotation PATCH against a different CR.
+  for (const { tool, kind, mutates, description } of RECONCILABLE) {
+    registerWriteTool(
+      tool,
+      {
+        mutates,
+        recoverable: true,
+        scopeTargetOf: (p) => ({ kind: "namespace", value: p.namespace }),
+      },
+      description,
+      z.object({ namespace: z.string().min(1), name: z.string().min(1) }),
+      async (p) =>
+        jsonResult({
+          status: "requested",
+          name: p.name,
+          requestedAt: await fluxReconcile(kind, p.namespace, p.name),
+        }),
+    );
+  }
 }
 
 export async function startConnector(): Promise<void> {

package/connectors/gcp/src/server.ts

@@ -1,140 +1,10 @@
 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 ?? {};
-}
+import { registerGcpTools } from "./tools.ts";
 
 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 });
-  },
-);
+registerGcpTools(mcp);
 
 const transport = new StdioServerTransport();
 await mcp.connect(transport);