@nimbus-dev/connectors 0.1.0

package/connectors/fastmail/src/tools.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+
+import { emailToolSchemas } from "../../../shared/imap-tool-kit.ts";
+import {
+  createRegisterSimpleTool,
+  type McpListResult,
+  mcpJsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
+import { clampLimit, type JmapClient, type JmapEmailView } from "./jmap-core.ts";
+
+/** A JMAP email view is already the JSON-safe header/metadata/preview shape. */
+function viewToJson(v: JmapEmailView): Record<string, unknown> {
+  return {
+    id: v.id,
+    messageId: v.messageId,
+    subject: v.subject,
+    from: [...v.from],
+    to: [...v.to],
+    cc: [...v.cc],
+    receivedAt: v.receivedAt,
+    attachments: v.attachments.map((a) => ({
+      filename: a.name,
+      sizeBytes: a.sizeBytes,
+      mimeType: a.mimeType,
+    })),
+    preview: v.preview,
+  };
+}
+
+const listArgs = z.object({
+  limit: z.number().int().min(1).max(200).optional(),
+});
+
+const getArgs = z.object({
+  id: z.string().min(1),
+});
+
+const searchArgs = z.object({
+  query: z.string().min(1).max(500),
+  limit: z.number().int().min(1).max(200).optional(),
+});
+
+/**
+ * Register the Fastmail JMAP read tools + the HITL-gated send tool onto an MCP
+ * server. The JMAP client is injected so tests exercise the tool surface without
+ * opening a real socket.
+ */
+export function registerFastmailTools(
+  // Widened from `{ tool: ... }`: the consent kit needs the real server surface — capabilities,
+  // registerTool, list-changed and logging — not just the deprecated `.tool` shim.
+  server: ConsentServer & { tool: (...args: never) => unknown },
+  client: JmapClient,
+): void {
+  const registerSimpleTool = createRegisterSimpleTool(server);
+  const { sendArgs } = emailToolSchemas;
+
+  registerSimpleTool(
+    "fastmail_list",
+    "List recent mailbox emails — HEADERS + attachment METADATA + a short capped text preview ONLY. Returns subject, from, to/cc, received date, message-id, attachment {filename,size,mimetype}, and a <=2000-char plain-text body preview. NEVER returns attachment bytes or the full message body.",
+    listArgs.shape,
+    async (args: unknown): Promise<McpListResult> => {
+      const parsed = listArgs.safeParse(args);
+      if (!parsed.success) {
+        throw new Error(parsed.error.message);
+      }
+      const items = await client.list(clampLimit(parsed.data.limit));
+      return mcpJsonResult({ items: items.map(viewToJson) });
+    },
+  );
+
+  registerSimpleTool(
+    "fastmail_get",
+    "Fetch one email by JMAP id — HEADERS + attachment METADATA + a short capped text preview ONLY. NEVER returns attachment bytes or the full message body.",
+    getArgs.shape,
+    async (args: unknown): Promise<McpListResult> => {
+      const parsed = getArgs.safeParse(args);
+      if (!parsed.success) {
+        throw new Error(parsed.error.message);
+      }
+      const v = await client.get(parsed.data.id);
+      return mcpJsonResult(v === null ? { item: null } : { item: viewToJson(v) });
+    },
+  );
+
+  registerSimpleTool(
+    "fastmail_search",
+    "Full-text search over emails (JMAP Email/query text filter) — returns the same header + attachment-metadata + preview view as fastmail_list. NEVER returns attachment bytes or the full message body beyond the capped preview.",
+    searchArgs.shape,
+    async (args: unknown): Promise<McpListResult> => {
+      const parsed = searchArgs.safeParse(args);
+      if (!parsed.success) {
+        throw new Error(parsed.error.message);
+      }
+      const items = await client.search(parsed.data.query, clampLimit(parsed.data.limit));
+      return mcpJsonResult({ matches: items.map(viewToJson) });
+    },
+  );
+
+  const registerWriteTool = createWriteToolRegistrar(server, {
+    connector: "fastmail",
+    scopeEnv: "NIMBUS_MCP_FASTMAIL_WRITE_SCOPE",
+    scopeKinds: ["recipient"],
+  });
+
+  registerWriteTool(
+    "fastmail_mail_send",
+    {
+      mutates: "fastmail.mail.send",
+      // A sent mail cannot be recalled and nothing remains to query, so the recipient and
+      // subject ARE the pre-state.
+      recoverable: false,
+      capturePreState: (p) => Promise.resolve({ to: p.to, subject: p.subject }),
+      scopeTargetOf: (p) => ({ kind: "recipient", value: p.to }),
+    },
+    "Send a new email via JMAP EmailSubmission.",
+    sendArgs,
+    async (parsedData): Promise<McpListResult> => {
+      const parsed = { success: true as const, data: parsedData };
+      const input: { to: string; subject: string; body: string; cc?: string; bcc?: string } = {
+        to: parsed.data.to,
+        subject: parsed.data.subject,
+        body: parsed.data.body,
+      };
+      if (parsed.data.cc !== undefined && parsed.data.cc !== "") {
+        input.cc = parsed.data.cc;
+      }
+      if (parsed.data.bcc !== undefined && parsed.data.bcc !== "") {
+        input.bcc = parsed.data.bcc;
+      }
+      const res = await client.send(input);
+      return mcpJsonResult({ emailId: res.emailId, submissionId: res.submissionId });
+    },
+  );
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const FASTMAIL_TOOL_NAMES = [
+  "fastmail_list",
+  "fastmail_get",
+  "fastmail_search",
+  "fastmail_mail_send",
+] as const;

package/connectors/figma/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.figma",
+  "displayName": "Figma",
+  "version": "0.1.0",
+  "description": "Figma connector (read-only). Surfaces the files of a single configured team as figma:file items in the local index via a two-level fetch — GET /v1/teams/<team_id>/projects then GET /v1/projects/<project_id>/files for each project — capturing each file's name, project name, thumbnail url, and last-modified timestamp. Bearer OAuth auth (Authorization: Bearer <token>; short-lived access token refreshed by the Gateway via the 3-legged OAuth authorization-code flow; never logged); fixed SaaS host api.figma.com. Neither endpoint paginates with a cursor (each returns the full list), so the gateway-side syncable walks a single forward pass per cycle, project- and file-capped. Read-only — hitlRequired is intentionally empty. Sparse structured file metadata; the canonical url is constructed from the file key.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.figma.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,24 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type FigmaSearchMatchOptions = SearchMatchOptions;
+
+/**
+ * Figma file objects are flat — `{ key, name, thumbnail_url, last_modified }`.
+ * When flattened by the connector for search, each file additionally carries
+ * a `project_name` label. Match against the file name and the project name
+ * (case-insensitive substring).
+ */
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [stringField(row, "name"), stringField(row, "project_name")];
+}
+
+export const filterFigmaFiles = makeQueryFilter(fieldsOf);

package/connectors/figma/src/server.ts

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterFigmaFiles } from "./search-filter.ts";
+
+const BASE = "https://api.figma.com";
+
+function apiToken(): string {
+  const t = process.env["FIGMA_TOKEN"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("FIGMA_TOKEN is not set");
+  }
+  return t;
+}
+
+function teamId(): string {
+  const t = process.env["FIGMA_TEAM_ID"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("FIGMA_TEAM_ID is not set");
+  }
+  return t;
+}
+
+function authHeader(): Record<string, string> {
+  return { Authorization: `Bearer ${apiToken()}`, Accept: "application/json" };
+}
+
+async function figmaGet(path: string): Promise<unknown> {
+  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Figma ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function projectsFrom(root: unknown): Array<{ id: string; name: string }> {
+  const projects = (root as { projects?: unknown } | null)?.projects;
+  if (!Array.isArray(projects)) {
+    return [];
+  }
+  const out: Array<{ id: string; name: string }> = [];
+  for (const p of projects) {
+    const rec = p as { id?: unknown; name?: unknown } | null;
+    const id = rec?.id;
+    if (typeof id === "string" || typeof id === "number") {
+      out.push({
+        id: String(id),
+        name: typeof rec?.name === "string" ? rec.name : "",
+      });
+    }
+  }
+  return out;
+}
+
+function filesFrom(root: unknown): unknown[] {
+  const files = (root as { files?: unknown } | null)?.files;
+  return Array.isArray(files) ? files : [];
+}
+
+/**
+ * Flatten the configured team's projects into a single list of files, tagging
+ * each file with its `project_name` for searchability. This is the two-level
+ * fetch: GET /v1/teams/<team_id>/projects, then GET /v1/projects/<id>/files for
+ * each project.
+ */
+async function listTeamFiles(): Promise<unknown[]> {
+  const projectsRoot = await figmaGet(`/v1/teams/${encodeURIComponent(teamId())}/projects`);
+  const projects = projectsFrom(projectsRoot);
+  const out: unknown[] = [];
+  for (const project of projects) {
+    const filesRoot = await figmaGet(`/v1/projects/${encodeURIComponent(project.id)}/files`);
+    for (const f of filesFrom(filesRoot)) {
+      const rec = f as Record<string, unknown> | null;
+      out.push({
+        ...rec,
+        project_id: project.id,
+        project_name: project.name,
+      });
+    }
+  }
+  return out;
+}
+
+await runReadOnlyMcpConnector("nimbus-figma", (reg) => {
+  reg(
+    "figma_list",
+    "List the configured team's Figma files. Two-level fetch: GET /v1/teams/<team_id>/projects (the team id is injected at spawn from the figma.team_id vault key) returns { name, projects: [{ id, name }] }; then for each project GET /v1/projects/<project_id>/files returns { name, files: [{ key, name, thumbnail_url, last_modified }] }. Returns a flattened { files: [...] } envelope where each file is shaped { key, name, thumbnail_url, last_modified, project_id, project_name }. Neither endpoint paginates — each returns the full list.",
+    z.object({}),
+    async () => {
+      return jsonResult({ files: await listTeamFiles() });
+    },
+  );
+
+  reg(
+    "figma_get",
+    "List the files in one Figma project by its id (GET /v1/projects/{projectId}/files). Returns the { name, files: [{ key, name, thumbnail_url, last_modified }] } envelope directly. Throws when no project with that id is accessible.",
+    z.object({
+      projectId: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await figmaGet(`/v1/projects/${encodeURIComponent(p.projectId)}/files`));
+    },
+  );
+
+  reg(
+    "figma_search",
+    "Substring search across the configured team's Figma files. Runs the same two-level fetch as figma_list (team projects, then files per project), flattens the result, and matches the query locally (case-insensitive) against each file name and its project name. Returns a { matches: [...] } envelope.",
+    searchToolInputSchema(200),
+    async (p) => {
+      const files = await listTeamFiles();
+      const matches = filterFigmaFiles(files, { query: p.query, limit: p.limit });
+      return jsonResult({ matches });
+    },
+  );
+});

package/connectors/firebase/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.firebase",
+  "displayName": "Firebase App Distribution",
+  "version": "0.1.0",
+  "description": "Firebase App Distribution connector (read-only). Surfaces each configured app's recent releases (display/build version, release notes, create time, console + testing URIs) so the local index can correlate mobile beta releases back to builds and incidents. Binary download links are stored as metadata but never fetched.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["firebaseappdistribution.googleapis.com", "oauth2.googleapis.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,30 @@
+import {
+  asObjectish,
+  type FieldExtractor,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type FirebaseSearchMatchOptions = SearchMatchOptions;
+
+/**
+ * App Distribution `releases[]` resources carry their searchable fields at the
+ * top level, except release notes which nest under `releaseNotes.text`. Project
+ * those up so the shared substring filter can match them.
+ */
+const releaseFields: FieldExtractor = (item: unknown) => {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  const releaseNotes = asObjectish(row["releaseNotes"]) ?? {};
+  return [
+    stringField(row, "displayVersion"),
+    stringField(row, "buildVersion"),
+    stringField(releaseNotes, "text"),
+    stringField(row, "name"),
+  ];
+};
+
+export const filterFirebaseReleases = makeQueryFilter(releaseFields);

package/connectors/firebase/src/server.ts

@@ -0,0 +1,94 @@
+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 { runReadOnlyMcpConnector } 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;
+
+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)}`;
+}
+
+await runReadOnlyMcpConnector("nimbus-firebase", (reg) => {
+  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/firebase/src/token.ts

@@ -0,0 +1,41 @@
+import { type GoogleServiceAccount, parseServiceAccountJson } from "@nimbus-dev/sdk";
+
+/**
+ * Firebase App Distribution credential plumbing.
+ *
+ * The OAuth2 token-mint flow (RS256 JWT-bearer) lives in `@nimbus-dev/sdk`
+ * (`mintGoogleAccessToken`) so the gateway sync and this MCP server share one
+ * signer across the package boundary. This module holds only the connector's
+ * env-specific glue: reading the spawn-injected credentials and deriving the
+ * project number from a Firebase app id.
+ */
+
+/** The project number is the 2nd colon-segment of a Firebase app id. */
+export function projectNumberFromAppId(appId: string): string | null {
+  const segment = appId.split(":")[1];
+  return segment !== undefined && segment !== "" ? segment : null;
+}
+
+/**
+ * Parse the injected `FIREBASE_SERVICE_ACCOUNT_JSON` env into a service account;
+ * throws if unset or malformed. The Gateway sets this at spawn time.
+ */
+export function serviceAccountFromEnv(): GoogleServiceAccount {
+  const json = process.env["FIREBASE_SERVICE_ACCOUNT_JSON"]?.trim();
+  if (json === undefined || json === "") {
+    throw new Error("FIREBASE_SERVICE_ACCOUNT_JSON is not set");
+  }
+  const sa = parseServiceAccountJson(json);
+  if (sa === null) {
+    throw new Error("FIREBASE_SERVICE_ACCOUNT_JSON is not a valid service-account key");
+  }
+  return sa;
+}
+
+/** Parse the injected comma-separated `FIREBASE_APP_IDS` env into a list. */
+export function configuredAppIds(): string[] {
+  return (process.env["FIREBASE_APP_IDS"] ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s !== "");
+}

package/connectors/flagsmith/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.flagsmith",
+  "displayName": "Flagsmith",
+  "version": "0.1.0",
+  "description": "Flagsmith feature-flag connector (read-only). Surfaces feature-flag definitions across all projects — name, type, default-enabled, initial value, description, tags, archived state, owner count, and timestamps — into the local index as `flagsmith:feature_flag` items, useful for incident correlation (\"did this flag exist when the alert fired?\"). Admin-API-token auth (`Authorization: Token <token>`). Regional / self-hosted instances override `flagsmith.api_base` (default https://api.flagsmith.com); the SaaS API host (api.flagsmith.com) is the only one in the static sandbox manifest today. v1 indexes flag definitions only — per-environment on/off state + segments are a deferred follow-up. The `flagsmith.flag.toggle` write tool is a deferred Phase 8 follow-up.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.flagsmith.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,29 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type FlagsmithSearchMatchOptions = SearchMatchOptions;
+
+function tagsString(row: Record<string, unknown>): string {
+  const tags = row["tags"];
+  if (!Array.isArray(tags)) {
+    return "";
+  }
+  return tags
+    .filter((t): t is string | number => typeof t === "string" || typeof t === "number")
+    .map(String)
+    .join(" ");
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [stringField(row, "name"), stringField(row, "description"), tagsString(row)];
+}
+
+export const filterFlagsmithFeatures = makeQueryFilter(fieldsOf);

package/connectors/flagsmith/src/server.ts

@@ -0,0 +1,102 @@
+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 : [];
+}
+
+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 });
+    },
+  );
+});

package/connectors/flux/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.flux",
+  "displayName": "Flux",
+  "version": "0.1.0",
+  "description": "Flux (GitOps Toolkit) connector. Reads Flux Custom Resources directly from the Kubernetes API server — Kustomizations, HelmReleases, sources (GitRepository / OCIRepository / HelmRepository / Bucket), and image-automation objects (ImageRepository / ImagePolicy / ImageUpdateAutomation) — into the local index as a single `flux:resource` item type with a `kind` discriminator in metadata (external_id `<kind>/<namespace>/<name>`). Surfaces the `status.conditions` Ready health (ready_status True/False/Unknown + reason + message), `spec.suspend`, source `url`, kustomization `path`, and `last_applied_revision` / `last_attempted_revision`. Authenticates with a read-only Kubernetes ServiceAccount JWT sent as `Authorization: Bearer <token>`; the API server base is supplied via the `flux.api_url` vault key. Flux has no central API and no SaaS host: the connector is always self-hosted, so the static manifest network list is intentionally empty — `phase3AddFluxMcp` parses the hostname from `flux.api_url` and extends the sandbox network list at spawn time (Grafana pattern). TLS note: Kubernetes API servers commonly present self-signed certificates that Bun's fetch rejects; v1 relies on `flux.api_url` pointing at a CA-trusted endpoint (a TLS-terminating ingress or `kubectl proxy`). Custom-CA / insecure-TLS handling is a deferred follow-up. Two HITL-gated write tools request a reconcile by annotating `reconcile.fluxcd.io/requestedAt` on the CR (PATCH): `flux_kustomization_reconcile` (HITL `flux.kustomization.reconcile`) and `flux_helmrelease_reconcile` (HITL `flux.helmrelease.reconcile`); both are async (verify via the next metadata sync) and require the ServiceAccount's `patch` RBAC verb on the target CR. `flux suspend`/`resume` remain deferred.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": [],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "hitlRequired": ["write"],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}