@nimbus-dev/connectors 0.9.0 → 0.11.0

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);

package/connectors/testflight/src/tools.ts

@@ -1,9 +1,18 @@
 import { signAppStoreConnectJwt } from "@nimbus-dev/sdk";
 import { z } from "zod";
-import { createJsonGetter } 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,
+  type JsonApiConfig,
+} from "../../../shared/env-json-api.ts";
 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 {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
 import { jwtParamsFromEnv } from "./jwt.ts";
 import { filterTestflightBuilds } from "./search-filter.ts";
 
@@ -14,11 +23,15 @@ function authHeader(): Record<string, string> {
   return { Authorization: `Bearer ${token}`, Accept: "application/json" };
 }
 
-const appstoreGet = createJsonGetter({
+const api: JsonApiConfig = {
   base: APPSTORECONNECT_API,
   label: "App Store Connect",
   headers: authHeader,
-});
+};
+
+const appstoreGet = createJsonGetter(api);
+// A mutation's 3xx is refused (never followed), so the token is not replayed anywhere.
+const appstoreSend = createJsonSender(api);
 
 function buildsPath(appId: string, limit: number): string {
   return `/v1/builds?filter[app]=${encodeURIComponent(appId)}&sort=-uploadedDate&limit=${String(limit)}`;
@@ -29,9 +42,92 @@ export const TESTFLIGHT_TOOL_NAMES = [
   "testflight_list",
   "testflight_get",
   "testflight_search",
+  "testflight_build_groups_get",
+  "testflight_beta_groups_list",
+  "testflight_build_distribute",
 ] as const;
 
-export function registerTestflightTools(reg: ZodToolRegistrar): void {
+/** App Store Connect resource ids (UUIDs and numeric app ids); never a dot segment. */
+const idArg = z
+  .string()
+  .regex(/^(?!\.{1,2}$)[A-Za-z0-9._-]{1,64}$/, "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;
+}
+
+/**
+ * The beta groups a build is in, projected to what an approver needs. `publicLinkEnabled` is kept
+ * on purpose: a group with a public link is open to anyone who holds the link, whoever is in it.
+ */
+async function readBuildGroups(buildId: string): Promise<Obj[]> {
+  return projectGroups(
+    await appstoreGet(`/v1/builds/${encodeURIComponent(buildId)}/betaGroups?limit=200`),
+    200,
+  );
+}
+
+/** At most `cap` groups of an App Store Connect list reply, as `{id, name, isInternalGroup, publicLinkEnabled}`. */
+function projectGroups(reply: unknown, cap: number): Obj[] {
+  const data = Array.isArray(asObj(reply)["data"]) ? (asObj(reply)["data"] as unknown[]) : [];
+  return data.slice(0, cap).map((raw) => {
+    const g = asObj(raw);
+    const attrs = asObj(g["attributes"]);
+    return {
+      id: capText(g["id"]),
+      name: capText(attrs["name"]),
+      isInternalGroup: attrs["isInternalGroup"],
+      publicLinkEnabled: attrs["publicLinkEnabled"],
+    };
+  });
+}
+
+/** The ids of the beta groups an app has, from `GET /v1/apps/{appId}/betaGroups`. */
+async function appGroupIds(appId: string): Promise<Set<string>> {
+  const groups = projectGroups(
+    await appstoreGet(`/v1/apps/${encodeURIComponent(appId)}/betaGroups?limit=200`),
+    200,
+  );
+  return new Set(groups.map((g) => g["id"]).filter((id): id is string => typeof id === "string"));
+}
+
+/**
+ * The ids, among `ids`, of beta groups that have a public link right now: one
+ * `GET /v1/betaGroups/{id}` each, read at dispatch so the answer is the group's state at the moment
+ * of the send, not at the time anyone was shown it.
+ */
+async function publicLinkGroupIds(ids: readonly string[]): Promise<string[]> {
+  const open: string[] = [];
+  for (const id of ids) {
+    const root = asObj(await appstoreGet(`/v1/betaGroups/${encodeURIComponent(id)}`));
+    if (asObj(asObj(root["data"])["attributes"])["publicLinkEnabled"] === true) open.push(id);
+  }
+  return open;
+}
+
+/** The app a build belongs to, from `GET /v1/builds/{id}?include=app`. */
+async function appOfBuild(buildId: string): Promise<string | undefined> {
+  const root = asObj(await appstoreGet(`/v1/builds/${encodeURIComponent(buildId)}?include=app`));
+  const rel = asObj(asObj(asObj(root["data"])["relationships"])["app"]);
+  return str(asObj(rel["data"])["id"]);
+}
+
+export function registerTestflightTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+  const registerWriteTool = createWriteToolRegistrar(server, {
+    connector: "testflight",
+    scopeEnv: "NIMBUS_MCP_TESTFLIGHT_WRITE_SCOPE",
+    scopeKinds: ["app"],
+  });
+
   reg(
     "testflight_list",
     "List TestFlight resources via the App Store Connect API. When `appId` is omitted, returns the user's accessible apps via `GET /v1/apps`. When `appId` is provided, returns that app's most-recent builds via `GET /v1/builds?filter[app]=<id>&sort=-uploadedDate` (limit optional).",
@@ -76,4 +172,87 @@ export function registerTestflightTools(reg: ZodToolRegistrar): void {
       return matchesResult(data, filterTestflightBuilds, p);
     },
   );
+
+  reg(
+    "testflight_build_groups_get",
+    "Read the beta groups a TestFlight build is already in (`GET /v1/builds/{buildId}/betaGroups`), projected to `{ groups: [{ id, name, isInternalGroup, publicLinkEnabled }] }`. A group with `publicLinkEnabled: true` is reachable by anyone who has its public link.",
+    z.object({ buildId: idArg }),
+    async (p) => jsonResult({ groups: await readBuildGroups(p.buildId) }),
+  );
+
+  reg(
+    "testflight_beta_groups_list",
+    "List an app's TestFlight beta groups (`GET /v1/apps/{appId}/betaGroups`), at most `limit` (default 100, max 200), projected to `{ groups: [{ id, name, isInternalGroup, publicLinkEnabled }] }`. Read it BEFORE `testflight_build_distribute` to see which target groups are public: a group with `publicLinkEnabled: true` is reachable by anyone who holds its link.",
+    z.object({ appId: idArg, limit: z.number().int().min(1).max(200).optional() }),
+    async (p) => {
+      const search = new URLSearchParams({ limit: String(p.limit ?? 100) });
+      const root = await appstoreGet(
+        `/v1/apps/${encodeURIComponent(p.appId)}/betaGroups?${search.toString()}`,
+      );
+      return jsonResult({ groups: projectGroups(root, p.limit ?? 100) });
+    },
+  );
+
+  registerWriteTool(
+    "testflight_build_distribute",
+    {
+      mutates: "testflight.build.distribute",
+      // Testers who were given the build cannot be un-invited from here; the groups the build was
+      // already in are recorded in the audit pre-state.
+      recoverable: false,
+      capturePreState: async (p: { buildId: string }) => ({
+        buildId: p.buildId,
+        groups: await readBuildGroups(p.buildId),
+      }),
+      scopeTargetOf: (p: { appId: string }) => ({ kind: "app", value: p.appId }),
+    },
+    'Add a TestFlight build to beta groups (`POST /v1/builds/{buildId}/relationships/betaGroups`, body `{ data: [{ type: "betaGroups", id }] }`). The build must belong to `appId`: it is read first (`GET /v1/builds/{buildId}?include=app`) and a build of another app sends nothing. Adding a build to a group makes it available to every tester in it, and a group with a public link reaches anyone holding the link (see `testflight_build_groups_get`): each target group is read (`GET /v1/betaGroups/{id}`) right before the send, and one with `publicLinkEnabled: true` is refused with `testflight_public_link_forbidden` unless `allowPublicLink` is `true` (default false). Apple may refuse (409/422) a build that is not VALID or a external group that has not passed beta review; the body is returned in the error. The reply is `accepted`.',
+    z.object({
+      appId: idArg,
+      buildId: idArg,
+      betaGroupIds: z.array(idArg).min(1).max(20),
+      allowPublicLink: z.boolean().optional(),
+    }),
+    async (p) => {
+      if (new Set(p.betaGroupIds).size !== p.betaGroupIds.length) {
+        throw new Error("betaGroupIds has a duplicate; nothing was sent");
+      }
+      const owner = await appOfBuild(p.buildId);
+      if (owner !== p.appId) {
+        throw new Error(`build ${p.buildId} does not belong to app ${p.appId}; nothing was sent`);
+      }
+      // Every target group must be one of this app's: one GET, and nothing is sent on a mismatch.
+      const known = await appGroupIds(p.appId);
+      const stray = p.betaGroupIds.filter((id) => !known.has(id));
+      if (stray.length > 0) {
+        throw new Error(
+          `beta group(s) ${stray.join(", ")} do not belong to app ${p.appId}; nothing was sent`,
+        );
+      }
+      // A group with a public link reaches anyone who holds the link, so it is distributed to only
+      // when the caller said so. Read now, at dispatch, from each group itself.
+      if (p.allowPublicLink !== true) {
+        const open = await publicLinkGroupIds(p.betaGroupIds);
+        if (open.length > 0) {
+          throw new Error(
+            `testflight_public_link_forbidden: beta group(s) ${open.join(", ")} have a public link; pass allowPublicLink: true to distribute to them; nothing was sent`,
+          );
+        }
+      }
+      await appstoreSend(
+        "POST",
+        `/v1/builds/${encodeURIComponent(p.buildId)}/relationships/betaGroups`,
+        {
+          data: p.betaGroupIds.map((id) => ({ type: "betaGroups", id })),
+        },
+      );
+      return jsonResult({
+        ok: true,
+        status: "accepted",
+        appId: p.appId,
+        buildId: p.buildId,
+        betaGroupIds: p.betaGroupIds,
+      });
+    },
+  );
 }

package/connectors/vercel/nimbus.extension.json

@@ -2,14 +2,14 @@
   "id": "com.nimbus.vercel",
   "displayName": "Vercel",
   "version": "0.1.0",
-  "description": "Vercel deployment connector (read-only). Surfaces deployment uid, project name, state, target (production/staging), the *.vercel.app host, inspector URL, git commit metadata (sha/message/ref/PR id), and creator into the local index as `vercel:deployment` items — useful for correlating deploys with PR / Slack history (\"which deploy shipped this commit?\"). Bearer-token auth. Optional `vercel.team_id` scopes requests to a team. The SaaS host (api.vercel.com) is fixed. Projects / domains / env vars / aliases / logs are deferred follow-ups.",
+  "description": "Vercel deployment connector. Surfaces deployment uid, project name, state, target (production/staging), the *.vercel.app host, inspector URL, git commit metadata (sha/message/ref/PR id), and creator into the local index as `vercel:deployment` items — useful for correlating deploys with PR / Slack history (\"which deploy shipped this commit?\"). Bearer-token auth. Optional `vercel.team_id` scopes requests to a team. The SaaS host (api.vercel.com) is fixed. Write tools (each needs owner approval): `vercel.deployment.redeploy` and `vercel.deployment.promote`. Projects / domains / env vars / aliases / logs are deferred follow-ups.",
   "author": "Nimbus",
   "entrypoint": "dist/server.js",
   "runtime": "bun",
   "permissions": {
     "network": ["api.vercel.com"]
   },
-  "hitlRequired": [],
+  "hitlRequired": ["write"],
   "syncInterval": 600,
   "minNimbusVersion": "0.2.0"
 }

package/connectors/vercel/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 { registerVercelTools } from "./tools.ts";
 
-await runReadOnlyMcpConnector("nimbus-vercel", (reg) => {
-  registerVercelTools(reg);
-});
+const server = new McpServer(
+  { name: "nimbus-vercel", version: "0.1.0" },
+  { capabilities: CONSENT_SERVER_CAPABILITIES },
+);
+
+registerVercelTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);