@nimbus-dev/connectors 0.8.0 → 0.10.0

package/connectors/kubernetes/src/tools.ts

@@ -1,7 +1,13 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import { z } from "zod";
 import { cliArg } from "../../../shared/cli-json-kit.ts";
 import type { ConsentServer } from "../../../shared/consent-kit.ts";
-import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createPrepareToolRegistrar,
+  createWriteToolRegistrar,
+} from "../../../shared/consent-kit.ts";
 import { isKubectlNotFound, projectDeployment } from "../../../shared/k8s-deployment-view.ts";
 import {
   createRegisterSimpleTool,
@@ -9,7 +15,9 @@ import {
   mcpJsonResult as jsonResult,
 } from "../../../shared/mcp-tool-kit.ts";
 import { withPrivateKubeconfig } from "../../../shared/private-kubeconfig.ts";
-import { runCliJsonThrowing, runCliOkThrowing } from "../../../shared/run-cli-json.ts";
+import { withScratchDir } from "../../../shared/private-scratch.ts";
+import { runCliCode, runCliJsonThrowing, runCliOkThrowing } from "../../../shared/run-cli-json.ts";
+import { type ScannedObject, scanNamespacedManifest } from "./manifest-scan.ts";
 
 function kubectlBase(): string[] {
   const args = ["kubectl"];
@@ -33,6 +41,185 @@ function kubectlJson(rest: string[]): Promise<unknown> {
   return withKube((env) => runCliJsonThrowing(cmd, env));
 }
 
+/** A manifest may be at most this many UTF-8 bytes (the schema's character cap is a floor of it). */
+const MANIFEST_MAX_BYTES = 262_144;
+/** The diff in a plan reply; the owner approves what the preview shows, so a bigger one is refused. */
+const DIFF_MAX_BYTES = 65_536;
+/** The whole plan reply, which the gateway refuses above this size. */
+const PLAN_REPLY_MAX_BYTES = 262_144;
+/** Domain separator of the plan hash: sha256 of this, a newline, the namespace, a newline, the manifest. */
+const PLAN_HASH_DOMAIN = "nimbus-k8s-manifest-v1";
+const MISMATCH = "manifest does not match the approved hash";
+
+interface ManifestInput {
+  readonly namespace: string;
+  readonly manifest: string;
+}
+
+/**
+ * The checks every manifest tool makes before it touches a file or a process, in this order: size
+ * in UTF-8 bytes, the namespaced-subset scan (manifest-scan.ts), and the hash of the exact bytes
+ * kubectl will be handed. Throws a fixed message.
+ */
+function checkedManifest(p: ManifestInput): {
+  bytes: Buffer;
+  sha256: string;
+  scanned: ScannedObject[];
+} {
+  const bytes = Buffer.from(p.manifest, "utf8");
+  if (bytes.length > MANIFEST_MAX_BYTES) {
+    throw new Error(`manifest is larger than ${String(MANIFEST_MAX_BYTES)} bytes`);
+  }
+  const scanned = scanNamespacedManifest(p.manifest, p.namespace);
+  // The hash binds the namespace to the manifest, so an approved plan for one namespace cannot be
+  // replayed against another. The kube CONTEXT is owner environment (KUBE_CONTEXT), not caller
+  // input, and is deliberately not part of it.
+  const hashed = [PLAN_HASH_DOMAIN, p.namespace, p.manifest].join("\n");
+  const sha256 = createHash("sha256").update(hashed, "utf8").digest("hex");
+  return { bytes, sha256, scanned };
+}
+
+/** {@link checkedManifest}, then the apply's own check: the manifest must hash to what was approved. */
+function approvedManifest(p: ManifestInput & { readonly planSha256: string }) {
+  const checked = checkedManifest(p);
+  const want = Buffer.from(p.planSha256, "hex");
+  const have = Buffer.from(checked.sha256, "hex");
+  // Equal length is checked first: timingSafeEqual throws on unequal buffers. The schema pins 64 hex.
+  if (want.length !== have.length || !timingSafeEqual(want, have)) {
+    throw new Error(MISMATCH);
+  }
+  return checked;
+}
+
+function refusalOf(check: () => unknown): string | undefined {
+  try {
+    check();
+    return undefined;
+  } catch (e) {
+    return e instanceof Error ? e.message : String(e);
+  }
+}
+
+/**
+ * kubectl's failure as an error. A Secret in the manifest means kubectl's stderr may quote its
+ * data (an invalid value is often echoed), so the snippet is withheld whenever one is present.
+ */
+function kubectlFailure(
+  label: string,
+  code: number,
+  stderr: string,
+  scanned: readonly ScannedObject[],
+): Error {
+  const detail = scanned.some((o) => o.kind === "Secret")
+    ? "(stderr withheld: the manifest holds a Secret)"
+    : stderr.slice(0, 500);
+  return new Error(`${label} exited ${String(code)}: ${detail}`);
+}
+
+/** What a plan's `diff` holds in place of kubectl's when the manifest holds a Secret. */
+export const SECRET_DIFF_WITHHELD = "(diff withheld: the manifest holds a Secret)";
+
+/** The `kubectl ... -o name` resource prefix of each allowlisted kind. */
+const RESOURCE_PREFIX: Readonly<Record<string, string>> = {
+  ConfigMap: "configmap",
+  Secret: "secret",
+  Service: "service",
+  Pod: "pod",
+  ServiceAccount: "serviceaccount",
+  PersistentVolumeClaim: "persistentvolumeclaim",
+  Deployment: "deployment.apps",
+  StatefulSet: "statefulset.apps",
+  DaemonSet: "daemonset.apps",
+  ReplicaSet: "replicaset.apps",
+  Job: "job.batch",
+  CronJob: "cronjob.batch",
+  Ingress: "ingress.networking.k8s.io",
+  NetworkPolicy: "networkpolicy.networking.k8s.io",
+  Role: "role.rbac.authorization.k8s.io",
+  RoleBinding: "rolebinding.rbac.authorization.k8s.io",
+  HorizontalPodAutoscaler: "horizontalpodautoscaler.autoscaling",
+  PodDisruptionBudget: "poddisruptionbudget.policy",
+};
+
+/**
+ * Order by UTF-16 code unit, the same on every machine. Not `localeCompare`: collation can tie two
+ * distinct strings, and these lists are compared element by element.
+ */
+function compareCodeUnits(a: string, b: string): number {
+  if (a < b) return -1;
+  return a > b ? 1 : 0;
+}
+
+/** The sorted `<prefix>/<name>` list the scan expects kubectl to report. */
+function expectedNames(scanned: readonly ScannedObject[]): string[] {
+  return scanned
+    .map((o) => `${RESOURCE_PREFIX[o.kind] ?? o.kind}/${o.name}`)
+    .sort(compareCodeUnits);
+}
+
+/**
+ * Defence in depth behind the scanner: what kubectl itself reports (`-o name`) must be, as a
+ * multiset, exactly what the scan read. A document kubectl reads differently (a List flattened into
+ * its items, a kind the scan mis-paired) shows up here as a different set, before the diff and
+ * before the real apply. Names only, so the message is safe to show.
+ */
+function assertSameObjects(
+  reported: readonly string[],
+  scanned: readonly ScannedObject[],
+  when: string,
+): void {
+  const have = [...reported].sort(compareCodeUnits);
+  const want = expectedNames(scanned);
+  if (have.length !== want.length || have.some((n, i) => n !== want[i])) {
+    throw new Error(
+      `kubectl ${when} reported different objects than the manifest scan (kubectl: ${have.join(", ")}; scan: ${want.join(", ")})`,
+    );
+  }
+}
+
+/** Write the manifest into the call's private scratch directory: exclusive create, owner-only. */
+async function writeManifestFile(dir: string, bytes: Buffer): Promise<string> {
+  const file = join(dir, "manifest.yaml");
+  await writeFile(file, bytes, { flag: "wx", mode: 0o600 });
+  return file;
+}
+
+/** `kubectl apply --server-side --dry-run=server -o name`, cross-checked against the scan. */
+async function serverDryRun(
+  kube: { readonly KUBECONFIG: string },
+  ns: string,
+  file: string,
+  scanned: readonly ScannedObject[],
+): Promise<string[]> {
+  const dry = await runCliCode(
+    [
+      ...kubectlBase(),
+      "apply",
+      "--server-side",
+      "--dry-run=server",
+      "--field-manager=nimbus",
+      "-n",
+      ns,
+      "-f",
+      file,
+      "-o",
+      "name",
+    ],
+    kube,
+  );
+  if (dry.code !== 0) throw kubectlFailure("kubectl", dry.code, dry.stderr, scanned);
+  const objects = objectLines(dry.stdout);
+  assertSameObjects(objects, scanned, "dry run");
+  return objects;
+}
+
+function objectLines(stdout: string): string[] {
+  return stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l !== "");
+}
+
 const optionalNamespaceSchema = z.object({ namespace: cliArg.optional() });
 
 async function k8sListNamespacedResource(p: { namespace?: string | undefined }, resource: string) {
@@ -50,6 +237,8 @@ export const KUBERNETES_TOOL_NAMES = [
   "k8s_rollout_restart",
   "k8s_pod_delete",
   "k8s_deployment_scale",
+  "k8s_manifest_plan",
+  "k8s_manifest_apply",
 ] as const;
 
 export function registerKubernetesTools(
@@ -68,6 +257,16 @@ export function registerKubernetesTools(
     scopeKinds: ["namespace"],
   });
 
+  /**
+   * Prepare tools (shared/prepare-tool-ids.ts) read the state a write is bound to, for the gateway
+   * to call BEFORE the write's approval prompt; they are neither reads nor writes to the kit.
+   */
+  const registerPrepareTool = createPrepareToolRegistrar(server, {
+    connector: "kubernetes",
+    scopeEnv: "NIMBUS_MCP_KUBERNETES_WRITE_SCOPE",
+    scopeKinds: ["namespace"],
+  });
+
   reg(
     "k8s_pod_list",
     "List pods in a namespace (default namespace: default).",
@@ -177,4 +376,134 @@ export function registerKubernetesTools(
       return jsonResult({ ok: true });
     },
   );
+
+  registerPrepareTool(
+    "k8s_manifest_plan",
+    { scopeTargetOf: (p) => ({ kind: "namespace", value: p.namespace }) },
+    "Plan a k8s_manifest_apply: scan the manifest (namespaced kinds from an allowlist only, in the given namespace), then ask the API server for a server-side dry run and a server-side diff. Returns {planSha256, namespace, objects, scanned, diff, hasDifferences}; the apply must be given the same namespace, manifest and planSha256. Changes nothing.",
+    z.object({ namespace: cliArg, manifest: z.string().min(1).max(MANIFEST_MAX_BYTES) }),
+    async (p) => {
+      const { bytes, sha256, scanned } = checkedManifest(p);
+      const ns = p.namespace;
+      const reply = await withScratchDir("nimbus-k8s-", async (dir) => {
+        const file = await writeManifestFile(dir, bytes);
+        return withKube(async (kube) => {
+          // The dry run: the API server validates and admits the manifest and names each object,
+          // and the names must be the ones the scan read (see assertSameObjects).
+          const objects = await serverDryRun(kube, ns, file, scanned);
+
+          // kubectl diff runs the program KUBECTL_EXTERNAL_DIFF names (default `diff -u -N`). The
+          // variable is removed from the child whatever the owner's shell sets, so the diff is
+          // never produced by an arbitrary program. TMPDIR/TMP/TEMP point kubectl's own temp files
+          // (Go reads TMP and TEMP on Windows) into this call's private directory. Exit codes:
+          // https://kubernetes.io/docs/reference/kubectl/generated/kubectl_diff/ (0 no
+          // differences, 1 differences, >1 error). --force-conflicts is never passed.
+          const diff = await runCliCode(
+            [
+              ...kubectlBase(),
+              "diff",
+              "--server-side",
+              "--field-manager=nimbus",
+              "-n",
+              ns,
+              "-f",
+              file,
+            ],
+            {
+              KUBECONFIG: kube.KUBECONFIG,
+              KUBECTL_EXTERNAL_DIFF: undefined,
+              TMPDIR: dir,
+              TMP: dir,
+              TEMP: dir,
+            },
+          );
+          if (diff.code !== 0 && diff.code !== 1) {
+            throw kubectlFailure("kubectl diff", diff.code, diff.stderr, scanned);
+          }
+          if (Buffer.byteLength(diff.stdout, "utf8") > DIFF_MAX_BYTES) {
+            throw new Error(`diff too large (over ${String(DIFF_MAX_BYTES)} bytes)`);
+          }
+          // kubectl masks a Secret's `data`, but the diff's context lines can still carry its
+          // plaintext (a `last-applied-configuration` annotation, `stringData`), so with a Secret
+          // in the manifest only the fact of a difference is returned, never the body.
+          const holdsSecret = scanned.some((o) => o.kind === "Secret");
+          return {
+            planSha256: sha256,
+            namespace: ns,
+            objects,
+            scanned,
+            diff: holdsSecret ? SECRET_DIFF_WITHHELD : diff.stdout,
+            hasDifferences: diff.code === 1,
+          };
+        });
+      });
+      if (Buffer.byteLength(JSON.stringify(reply), "utf8") > PLAN_REPLY_MAX_BYTES) {
+        throw new Error("plan reply too large");
+      }
+      return jsonResult(reply);
+    },
+  );
+
+  registerWriteTool(
+    "k8s_manifest_apply",
+    {
+      mutates: "kubernetes.manifest.apply",
+      // An applied manifest is not undone by this tool; the objects it names are all that remain.
+      recoverable: false,
+      capturePreState: (p) =>
+        Promise.resolve({
+          namespace: p.namespace,
+          planSha256: p.planSha256,
+          objects: checkedManifest(p).scanned,
+        }),
+      scopeTargetOf: (p) => ({ kind: "namespace", value: p.namespace }),
+      // Standalone only: a manifest no consent could make safe is refused before any prompt. The
+      // handler repeats the same checks, because gateway mode registers the raw handler.
+      refuseBefore: (p) => refusalOf(() => approvedManifest(p)),
+    },
+    "Apply a manifest with a server-side apply, in the given namespace. The namespace and manifest must be the ones k8s_manifest_plan planned (planSha256) and the manifest must hold namespaced objects of allowlisted kinds only. Runs a server-side dry run first and applies only if kubectl reports the objects the scan read.",
+    z.object({
+      namespace: cliArg,
+      manifest: z.string().min(1).max(MANIFEST_MAX_BYTES),
+      planSha256: z.string().regex(/^[0-9a-f]{64}$/),
+    }),
+    async (p) => {
+      const { bytes, scanned } = approvedManifest(p);
+      return withScratchDir("nimbus-k8s-", async (dir) => {
+        const file = await writeManifestFile(dir, bytes);
+        return withKube(async (kube) => {
+          // Dry run and cross-check FIRST, so an object kubectl would apply that the scan did not
+          // read stops the call before anything changes.
+          await serverDryRun(kube, p.namespace, file, scanned);
+          // The file the real apply reads must still hold the approved bytes: the dry run was a
+          // child process with the same file, and on Windows the 0600 mode is not enforced.
+          if (!bytes.equals(await readFile(file))) {
+            throw new Error("the manifest file changed before the apply");
+          }
+          const applied = await runCliCode(
+            [
+              ...kubectlBase(),
+              "apply",
+              "--server-side",
+              "--field-manager=nimbus",
+              "-n",
+              p.namespace,
+              "-f",
+              file,
+              "-o",
+              "name",
+            ],
+            kube,
+          );
+          if (applied.code !== 0) {
+            throw kubectlFailure("kubectl", applied.code, applied.stderr, scanned);
+          }
+          const objects = objectLines(applied.stdout);
+          // After the fact: the objects are already applied, so this is reported, not prevented.
+          assertSameObjects(objects, scanned, "applied and");
+          return jsonResult({ ok: true, status: "applied", objects });
+        });
+      });
+    },
+  );
 }

package/connectors/netlify/nimbus.extension.json

@@ -2,14 +2,14 @@
   "id": "com.nimbus.netlify",
   "displayName": "Netlify",
   "version": "0.1.0",
-  "description": "Netlify site connector (read-only). Surfaces site id, name, the production URL + SSL URL, the admin dashboard URL, the linked git repo + branch, and the embedded published-deploy status (state / branch / commit ref / commit URL / deploy preview URL) into the local index as `netlify:site` items — useful for answering \"is the latest deploy live?\" and \"which site shipped this commit?\". Bearer-token (PAT) auth. The SaaS host (api.netlify.com) is fixed. Per-deploy history, forms, functions, env vars, and DNS are deferred follow-ups.",
+  "description": "Netlify site connector. Surfaces site id, name, the production URL + SSL URL, the admin dashboard URL, the linked git repo + branch, and the embedded published-deploy status (state / branch / commit ref / commit URL / deploy preview URL) into the local index as `netlify:site` items — useful for answering \"is the latest deploy live?\" and \"which site shipped this commit?\". Bearer-token (PAT) auth. The SaaS host (api.netlify.com) is fixed. Write tool (needs owner approval): `netlify.build.trigger`; a build with no branch is a PRODUCTION deploy. Forms, functions, env vars, and DNS are deferred follow-ups.",
   "author": "Nimbus",
   "entrypoint": "dist/server.js",
   "runtime": "bun",
   "permissions": {
     "network": ["api.netlify.com"]
   },
-  "hitlRequired": [],
+  "hitlRequired": ["write"],
   "syncInterval": 600,
   "minNimbusVersion": "0.2.0"
 }

package/connectors/netlify/src/server.ts

@@ -1,6 +1,14 @@
-import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CONSENT_SERVER_CAPABILITIES } from "../../../shared/consent-kit.ts";
 import { registerNetlifyTools } from "./tools.ts";
 
-await runReadOnlyMcpConnector("nimbus-netlify", (reg) => {
-  registerNetlifyTools(reg);
-});
+const server = new McpServer(
+  { name: "nimbus-netlify", version: "0.1.0" },
+  { capabilities: CONSENT_SERVER_CAPABILITIES },
+);
+
+registerNetlifyTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/connectors/netlify/src/tools.ts

@@ -1,22 +1,93 @@
 import { z } from "zod";
-import { createJsonGetter, envAuthHeaders } from "../../../shared/env-json-api.ts";
+import { capText } from "../../../shared/cap-text.ts";
+import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createJsonGetter,
+  createJsonSender,
+  envAuthHeaders,
+  type JsonApiConfig,
+} from "../../../shared/env-json-api.ts";
+import { isSafeGitRef } from "../../../shared/github-rest.ts";
 import { matchesResult, searchToolInputSchema } 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 {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
 import { filterNetlifySites } from "./search-filter.ts";
 
 const BASE = "https://api.netlify.com";
 
-const netlifyGet = createJsonGetter({
+const api: JsonApiConfig = {
   base: BASE,
   label: "Netlify",
   headers: envAuthHeaders({ env: "NETLIFY_TOKEN" }),
-});
+};
+
+const netlifyGet = createJsonGetter(api);
+// A mutation's 3xx is refused (never followed), so the token is not replayed anywhere.
+const netlifySend = createJsonSender(api);
 
 /** Tool names exposed by this connector — for contract/introspection tests. */
-export const NETLIFY_TOOL_NAMES = ["netlify_get", "netlify_list", "netlify_search"] as const;
+export const NETLIFY_TOOL_NAMES = [
+  "netlify_list",
+  "netlify_get",
+  "netlify_search",
+  "netlify_deploy_list",
+  "netlify_build_trigger",
+] as const;
+
+/** A site id (a UUID) or name: never `.` or `..` (a URL parser collapses them out of the path). */
+const siteIdArg = z
+  .string()
+  .regex(/^(?!\.{1,2}$)[A-Za-z0-9._-]{1,128}$/, "letters, digits, '.', '_' and '-' only");
+
+type Obj = Record<string, unknown>;
+
+function asObj(v: unknown): Obj {
+  return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Obj) : {};
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v !== "" ? v : undefined;
+}
+
+interface TriggerArgs {
+  readonly siteId: string;
+  readonly branch?: string | undefined;
+  readonly production?: true | undefined;
+  readonly clearCache?: boolean | undefined;
+}
+
+/**
+ * Why a build trigger is refused before anything is sent, or `undefined`. An omitted `branch`
+ * publishes the PRODUCTION site, and the owner's preview shows the input only, so that choice must
+ * be written in the input: `production: true`. Shared by `refuseBefore` (standalone) and the
+ * handler (gateway mode registers the raw handler).
+ */
+function triggerProblem(p: TriggerArgs): string | undefined {
+  if (p.branch !== undefined && p.production === true) {
+    return "give a branch or production: true, not both; nothing was sent";
+  }
+  if (p.branch === undefined && p.production !== true) {
+    return "name a branch, or pass production: true to publish the production site; nothing was sent";
+  }
+  if (p.branch !== undefined && !isSafeGitRef(p.branch)) {
+    return "branch is not a safe git ref; nothing was sent";
+  }
+  return undefined;
+}
+
+export function registerNetlifyTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+  const registerWriteTool = createWriteToolRegistrar(server, {
+    connector: "netlify",
+    scopeEnv: "NIMBUS_MCP_NETLIFY_WRITE_SCOPE",
+    scopeKinds: ["site"],
+  });
 
-export function registerNetlifyTools(reg: ZodToolRegistrar): void {
   reg(
     "netlify_list",
     "List Netlify sites (`GET /api/v1/sites`), capped at `per_page` (default 100). Returns a bare JSON array of site objects, each carrying the embedded `published_deploy` status and `build_settings`.",
@@ -31,7 +102,7 @@ export function registerNetlifyTools(reg: ZodToolRegistrar): void {
 
   reg(
     "netlify_get",
-    "Fetch one Netlify site by its id (`GET /api/v1/sites/{siteId}`). Returns the site object directly. Throws when no match is found.",
+    "Fetch one Netlify site by its id (`GET /api/v1/sites/{siteId}`). Returns the site object directly, including `published_deploy` (the live deploy). Throws when no match is found.",
     z.object({
       siteId: z.string().min(1),
     }),
@@ -50,4 +121,83 @@ export function registerNetlifyTools(reg: ZodToolRegistrar): void {
       return matchesResult(root, filterNetlifySites, p);
     },
   );
+
+  reg(
+    "netlify_deploy_list",
+    "List a Netlify site's most recent deploys (`GET /api/v1/sites/{siteId}/deploys`, newest first), at most `perPage` (default 5, max 10), each projected to `{ id, state, branch, context, commit_ref, created_at, published_at, error_message }`. `context` says whether it was a production deploy.",
+    z.object({
+      siteId: siteIdArg,
+      perPage: z.number().int().min(1).max(10).optional(),
+    }),
+    async (p) => {
+      const search = new URLSearchParams({ per_page: String(p.perPage ?? 5), page: "1" });
+      const root = await netlifyGet(
+        `/api/v1/sites/${encodeURIComponent(p.siteId)}/deploys?${search.toString()}`,
+      );
+      const deploys = Array.isArray(root) ? root : [];
+      return jsonResult(
+        deploys.map((raw) => {
+          const d = asObj(raw);
+          return {
+            id: capText(d["id"]),
+            state: capText(d["state"]),
+            branch: capText(d["branch"]),
+            context: capText(d["context"]),
+            commit_ref: capText(d["commit_ref"]),
+            created_at: capText(d["created_at"]),
+            published_at: capText(d["published_at"]),
+            error_message: capText(d["error_message"]),
+          };
+        }),
+      );
+    },
+  );
+
+  registerWriteTool(
+    "netlify_build_trigger",
+    {
+      mutates: "netlify.build.trigger",
+      // A build adds a deploy; it does not delete one, and a production deploy is replaced by the next one.
+      recoverable: true,
+      scopeTargetOf: (p: { siteId: string }) => ({ kind: "site", value: p.siteId }),
+      refuseBefore: (p: TriggerArgs) => triggerProblem(p),
+    },
+    "Start a Netlify build of a site (`POST /api/v1/sites/{siteId}/builds`, query `branch` and `clear_cache`, NO body). IMPORTANT: Netlify treats a build with no branch as a PRODUCTION deploy and publishes it when it succeeds, so you MUST either name a `branch` (a branch that is not the site's production branch makes a branch deploy) or pass `production: true` to publish the production site on purpose; neither, or both, sends nothing. `clearCache: true` discards the build cache first. The reply is `accepted` with the build id: Netlify builds it afterwards, so check `netlify_deploy_list`.",
+    z.object({
+      siteId: siteIdArg,
+      branch: z.string().min(1).max(255).optional(),
+      production: z.literal(true).optional(),
+      clearCache: z.boolean().optional(),
+    }),
+    async (p) => {
+      const problem = triggerProblem(p);
+      if (problem !== undefined) throw new Error(problem);
+      // Netlify documents these as QUERY parameters, so nothing goes in a body.
+      const search = new URLSearchParams();
+      if (p.branch !== undefined) {
+        search.set("branch", p.branch);
+      }
+      if (p.clearCache === true) {
+        search.set("clear_cache", "true");
+      }
+      const qs = search.toString();
+      const reply = asObj(
+        await netlifySend(
+          "POST",
+          `/api/v1/sites/${encodeURIComponent(p.siteId)}/builds${qs === "" ? "" : `?${qs}`}`,
+          undefined,
+        ),
+      );
+      return jsonResult({
+        ok: true,
+        status: "accepted",
+        siteId: p.siteId,
+        // No branch = a production deploy (documented), and only `production: true` gets here without one.
+        branch: p.branch ?? null,
+        production: p.branch === undefined,
+        buildId: str(reply["id"]) ?? null,
+        deployId: str(reply["deploy_id"]) ?? null,
+      });
+    },
+  );
 }

package/connectors/testflight/nimbus.extension.json

@@ -2,14 +2,14 @@
   "id": "com.nimbus.testflight",
   "displayName": "TestFlight",
   "version": "0.1.0",
-  "description": "TestFlight connector via Apple's App Store Connect API (read-only). Surfaces apps and recent builds (version, processing state, uploaded date, min OS, encryption flag) so the local index can correlate iOS/macOS beta builds back to releases and incidents.",
+  "description": "TestFlight connector via Apple's App Store Connect API. Surfaces apps and recent builds (version, processing state, uploaded date, min OS, encryption flag) so the local index can correlate iOS/macOS beta builds back to releases and incidents. Write tool (needs owner approval): `testflight.build.distribute`, which adds a build to beta groups.",
   "author": "Nimbus",
   "entrypoint": "dist/server.js",
   "runtime": "bun",
   "permissions": {
     "network": ["api.appstoreconnect.apple.com"]
   },
-  "hitlRequired": [],
+  "hitlRequired": ["write"],
   "syncInterval": 600,
   "minNimbusVersion": "0.2.0"
 }

package/connectors/testflight/src/server.ts

@@ -1,6 +1,14 @@
-import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CONSENT_SERVER_CAPABILITIES } from "../../../shared/consent-kit.ts";
 import { registerTestflightTools } from "./tools.ts";
 
-await runReadOnlyMcpConnector("nimbus-testflight", (reg) => {
-  registerTestflightTools(reg);
-});
+const server = new McpServer(
+  { name: "nimbus-testflight", version: "0.1.0" },
+  { capabilities: CONSENT_SERVER_CAPABILITIES },
+);
+
+registerTestflightTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);