@nimbus-dev/connectors 0.1.0

package/connectors/azure/src/server.ts

@@ -0,0 +1,139 @@
+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 azEnv(): Record<string, string | undefined> {
+  return { ...process.env } as Record<string, string | undefined>;
+}
+
+async function azJson(args: string[]): Promise<unknown> {
+  const cmd = ["az", ...args, "-o", "json"];
+  const r = await runCliJson(cmd, azEnv());
+  if (!r.ok) {
+    throw new Error(r.message);
+  }
+  return r.data ?? {};
+}
+
+const mcp = new McpServer({ name: "nimbus-azure", version: "0.1.0" });
+
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+
+const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
+
+/**
+ * Every MUTATING azure 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: "azure",
+  scopeEnv: "NIMBUS_MCP_AZURE_WRITE_SCOPE",
+  scopeKinds: ["resource_group"],
+});
+
+reg(
+  "azure_app_service_list",
+  "List App Services in a resource group.",
+  z.object({
+    subscriptionId: z.string().min(1),
+    resourceGroup: z.string().min(1),
+  }),
+  async (p) =>
+    jsonResult(
+      await azJson([
+        "webapp",
+        "list",
+        "--subscription",
+        p.subscriptionId,
+        "--resource-group",
+        p.resourceGroup,
+      ]),
+    ),
+);
+
+registerWriteTool(
+  "azure_app_service_restart",
+  {
+    mutates: "azure.app_service.restart",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "resource_group", value: p.resourceGroup }),
+  },
+  "Restart an App Service.",
+  z.object({
+    subscriptionId: z.string().min(1),
+    resourceGroup: z.string().min(1),
+    name: z.string().min(1),
+  }),
+  async (p) => {
+    const r = await runCliOk(
+      [
+        "az",
+        "webapp",
+        "restart",
+        "--subscription",
+        p.subscriptionId,
+        "--resource-group",
+        p.resourceGroup,
+        "--name",
+        p.name,
+      ],
+      azEnv(),
+    );
+    if (!r.ok) {
+      throw new Error(r.message);
+    }
+    return jsonResult({ ok: true });
+  },
+);
+
+registerWriteTool(
+  "azure_aks_node_pool_scale",
+  {
+    mutates: "azure.aks.node_pool.scale",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "resource_group", value: p.resourceGroup }),
+  },
+  "Scale an AKS node pool.",
+  z.object({
+    subscriptionId: z.string().min(1),
+    resourceGroup: z.string().min(1),
+    clusterName: z.string().min(1),
+    poolName: z.string().min(1),
+    nodeCount: z.number().int().min(0),
+  }),
+  async (p) => {
+    const r = await runCliOk(
+      [
+        "az",
+        "aks",
+        "nodepool",
+        "scale",
+        "--subscription",
+        p.subscriptionId,
+        "--resource-group",
+        p.resourceGroup,
+        "--cluster-name",
+        p.clusterName,
+        "--name",
+        p.poolName,
+        "--node-count",
+        String(p.nodeCount),
+      ],
+      azEnv(),
+    );
+    if (!r.ok) {
+      throw new Error(r.message);
+    }
+    return jsonResult({ ok: true });
+  },
+);
+
+const transport = new StdioServerTransport();
+await mcp.connect(transport);

package/connectors/bigeye/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.bigeye",
+  "displayName": "Bigeye",
+  "version": "0.1.0",
+  "description": "Bigeye connector. Indexes Bigeye data-quality issues as `data_quality_test` items in the local index and exposes read tools (`bigeye_list`, `bigeye_get`, `bigeye_search`) plus HITL-gated issue-lifecycle write tools (`bigeye_issue_acknowledge`, `bigeye_issue_resolve`). Uses a Bearer API key against a per-tenant Bigeye instance. The per-tenant host is derived from bigeye.base_url at spawn time (like Looker/Tableau).",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": [],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "hitlRequired": ["write"],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.5.0"
+}

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

@@ -0,0 +1,22 @@
+import {
+  asRecord,
+  makeQueryFilter,
+  type SearchMatchOptions,
+} from "../../../shared/search-filter.ts";
+
+export type BigeyeSearchMatchOptions = SearchMatchOptions;
+
+function stringAt(row: Record<string, unknown>, key: string): string {
+  const v = row[key];
+  return typeof v === "string" ? v : "";
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asRecord(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [stringAt(row, "summary"), stringAt(row, "title"), stringAt(row, "description")];
+}
+
+export const filterBigeyeIssues = makeQueryFilter(fieldsOf);

package/connectors/bigeye/src/server.ts

@@ -0,0 +1,161 @@
+import { z } from "zod";
+import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
+import { fetchWithTimeout, mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import {
+  runReadOnlyMcpConnector,
+  type ZodToolRegistrar,
+} from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterBigeyeIssues } from "./search-filter.ts";
+
+function apiBase(): string {
+  const v = process.env["BIGEYE_BASE_URL"]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error("BIGEYE_BASE_URL is not set");
+  }
+  return v.endsWith("/") ? v.slice(0, -1) : v;
+}
+
+function authHeader(): Record<string, string> {
+  const k = process.env["BIGEYE_API_KEY"]?.trim();
+  if (k === undefined || k === "") {
+    throw new Error("BIGEYE_API_KEY is not set");
+  }
+  return { Authorization: `Bearer ${k}`, Accept: "application/json" };
+}
+
+/** One page of issues (`GET /api/v1/issues?limit&offset`), tolerant of array / `{issues}` / `{data}`. */
+async function fetchIssues(limit: number, offset: number): Promise<unknown[]> {
+  const url = `${apiBase()}/api/v1/issues?limit=${String(limit)}&offset=${String(offset)}`;
+  const res = await fetchWithTimeout(url, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Bigeye ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  const parsed = JSON.parse(text) as unknown;
+  if (Array.isArray(parsed)) {
+    return parsed;
+  }
+  if (parsed !== null && typeof parsed === "object") {
+    const root = parsed as Record<string, unknown>;
+    if (Array.isArray(root["issues"])) return root["issues"];
+    if (Array.isArray(root["data"])) return root["data"];
+  }
+  return [];
+}
+
+function issueId(item: unknown): string {
+  if (item === null || typeof item !== "object" || Array.isArray(item)) return "";
+  const row = item as Record<string, unknown>;
+  const v = row["id"];
+  if (typeof v === "string") return v;
+  if (typeof v === "number") return String(v);
+  return "";
+}
+
+/** Update a Bigeye issue status via `POST /api/v1/issues`. */
+async function updateIssueStatus(issueId: string, status: string): Promise<void> {
+  const base = apiBase();
+  const res = await fetchWithTimeout(`${base}/api/v1/issues`, {
+    method: "POST",
+    headers: { ...authHeader(), "Content-Type": "application/json" },
+    body: JSON.stringify({ issueId, status }),
+  });
+  if (!res.ok) {
+    throw new Error(
+      `Bigeye updateIssue ${String(res.status)}: ${(await res.text()).slice(0, 400)}`,
+    );
+  }
+}
+
+export function registerBigeyeTools(reg: ZodToolRegistrar, server: unknown): void {
+  // Despite the read-only helper's name, this connector exposes write tools. The consent
+  // kit needs the real server, which the helper now passes through as its second argument.
+  const registerWriteTool = createWriteToolRegistrar(server as ConsentServer, {
+    connector: "bigeye",
+    scopeEnv: "NIMBUS_MCP_BIGEYE_WRITE_SCOPE",
+    scopeKinds: ["issue"],
+  });
+
+  reg(
+    "bigeye_list",
+    "List Bigeye data-quality issues (`GET /api/v1/issues`). Paginated: `cursor` (offset) + `limit` (default 200, max 500) → `{ items, nextCursor }`.",
+    z.object({
+      cursor: z.string().nullable().optional(),
+      limit: z.number().int().min(1).max(500).optional(),
+    }),
+    async (p) => {
+      const limit = p.limit ?? 200;
+      // null / undefined / "" / non-numeric / negative all clamp to offset 0; fractional truncates.
+      const offset = Math.max(0, Math.trunc(Number(p.cursor) || 0));
+      const issues = await fetchIssues(limit, offset);
+      const nextCursor = issues.length === limit ? String(offset + limit) : null;
+      return jsonResult({ items: issues, nextCursor });
+    },
+  );
+
+  reg(
+    "bigeye_get",
+    "Fetch one Bigeye data-quality issue by its id. Throws when the issue is not found.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      const issues = await fetchIssues(500, 0);
+      const found = issues.find((item) => issueId(item) === p.id);
+      if (found === undefined) {
+        throw new Error(`Bigeye issue not found: ${p.id}`);
+      }
+      return jsonResult(found);
+    },
+  );
+
+  reg(
+    "bigeye_search",
+    "Substring search across Bigeye data-quality issues. Matches the query (case-insensitive) against issue summary, title, and description. Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(200),
+    async (p) => {
+      const issues = await fetchIssues(500, 0);
+      const matches = filterBigeyeIssues(issues, { query: p.query, limit: p.limit });
+      return jsonResult({ matches });
+    },
+  );
+
+  registerWriteTool(
+    "bigeye_issue_acknowledge",
+    {
+      mutates: "bigeye.issue.acknowledge",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "issue", value: p.issueId }),
+    },
+    "Acknowledge a Bigeye issue.",
+    z.object({ issueId: z.string().min(1) }),
+    async (p) => {
+      await updateIssueStatus(p.issueId, "ISSUE_STATUS_ACKNOWLEDGED");
+      return jsonResult({ status: "ok", issueId: p.issueId });
+    },
+  );
+
+  registerWriteTool(
+    "bigeye_issue_resolve",
+    {
+      mutates: "bigeye.issue.resolve",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "issue", value: p.issueId }),
+    },
+    "Resolve (close) a Bigeye issue.",
+    z.object({ issueId: z.string().min(1) }),
+    async (p) => {
+      await updateIssueStatus(p.issueId, "ISSUE_STATUS_CLOSED");
+      return jsonResult({ status: "ok", issueId: p.issueId });
+    },
+  );
+}
+
+// Exported so the bundled-connector registry can start this server explicitly: `import.meta.main`
+// is false under an import, and the module must stay importable by tests without connecting stdio.
+export async function startConnector(): Promise<void> {
+  await runReadOnlyMcpConnector("nimbus-bigeye", registerBigeyeTools);
+}
+
+if (import.meta.main) await startConnector();

package/connectors/bigquery/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.bigquery",
+  "displayName": "BigQuery",
+  "version": "0.1.0",
+  "description": "Google BigQuery metadata connector (Tier-3, no-row-data). Indexes datasets, tables, and schema field names/types via the BigQuery REST metadata API — never row, cell, or query-result data. Reuses the existing GCP service-account credentials via the gcloud CLI. Read-only; no write tools.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["bigquery.googleapis.com", "oauth2.googleapis.com", "www.googleapis.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/bigquery/src/server.ts

@@ -0,0 +1,6 @@
+import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { registerBigqueryTools } from "./tools.ts";
+
+await runReadOnlyMcpConnector("nimbus-bigquery", (reg) => {
+  registerBigqueryTools(reg);
+});

package/connectors/bigquery/src/tools.ts

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import { nimbusSpawn } from "../../../shared/nimbus-spawn.ts";
+import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+
+/**
+ * BigQuery (Tier-3, metadata-only) MCP tool surface. ALL tools index schema /
+ * METADATA only (datasets, tables, schema field names + types, row COUNTS, byte
+ * sizes, timestamps). NONE fetch row / cell / query-result data — no `bq query`,
+ * no `bq head`, no `tabledata.list`. The names are introspected by the
+ * `assertNoRowDataTools` contract test, so they must never contain a row-data
+ * segment (query/rows/sample/scan/preview/head/export/…).
+ */
+export const BIGQUERY_TOOL_NAMES = ["bigquery_list", "bigquery_get", "bigquery_search"] as const;
+
+const BASE = "https://bigquery.googleapis.com/bigquery/v2";
+
+function project(explicit?: string): string {
+  const p = (explicit ?? process.env["BIGQUERY_PROJECT"])?.trim();
+  if (p === undefined || p === "") {
+    throw new Error("BIGQUERY_PROJECT is not set and no project argument was provided");
+  }
+  return p;
+}
+
+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;
+}
+
+/** Mint a short-lived access token via `gcloud auth print-access-token`. */
+async function accessToken(): Promise<string> {
+  const { code, stdout, stderr } = await nimbusSpawn(
+    ["gcloud", "auth", "print-access-token"],
+    // Restores GOOGLE_APPLICATION_CREDENTIALS when set; nimbusSpawn already merges process.env.
+    gcloudEnv(),
+  );
+  const out = stdout.trim();
+  const err = stderr.trim();
+  if (code !== 0 || out === "") {
+    throw new Error(`gcloud auth print-access-token failed: ${err.slice(0, 300)}`);
+  }
+  return out;
+}
+
+async function bqGet(token: string, path: string): Promise<unknown> {
+  const res = await fetch(`${BASE}${path}`, {
+    headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`BigQuery ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function strField(r: Record<string, unknown>, key: string): string {
+  const v = r[key];
+  return typeof v === "string" ? v : "";
+}
+
+function tableMatches(entry: unknown, q: string): boolean {
+  if (!isRecord(entry)) {
+    return false;
+  }
+  const ref = entry["tableReference"];
+  const datasetId = isRecord(ref) ? strField(ref, "datasetId") : "";
+  const tableId = isRecord(ref) ? strField(ref, "tableId") : "";
+  const friendly = strField(entry, "friendlyName");
+  const hay = `${datasetId}.${tableId} ${friendly}`.toLowerCase();
+  return hay.includes(q.toLowerCase());
+}
+
+function datasetMatches(entry: unknown, q: string): boolean {
+  if (!isRecord(entry)) {
+    return false;
+  }
+  const ref = entry["datasetReference"];
+  const datasetId = isRecord(ref) ? strField(ref, "datasetId") : "";
+  return datasetId.toLowerCase().includes(q.toLowerCase());
+}
+
+function asArray(parsed: unknown, key: string): unknown[] {
+  if (!isRecord(parsed)) {
+    return [];
+  }
+  const arr = parsed[key];
+  return Array.isArray(arr) ? arr : [];
+}
+
+/**
+ * Register the read-only, metadata-only BigQuery tools onto the given registrar.
+ * Shared between `server.ts` (live) and the contract test (introspection).
+ */
+export function registerBigqueryTools(reg: ZodToolRegistrar): void {
+  reg(
+    "bigquery_list",
+    "List BigQuery datasets, or the tables in a dataset — METADATA ONLY. With no `dataset` argument, lists datasets (`GET /projects/<project>/datasets`). With `dataset` set, lists that dataset's tables (`GET /projects/<project>/datasets/<dataset>/tables`) — each entry carries `tableReference`, `type`, and `creationTime`. Never returns row or cell data.",
+    z.object({
+      project: z.string().min(1).optional(),
+      dataset: z.string().min(1).optional(),
+    }),
+    async (p) => {
+      const token = await accessToken();
+      const proj = project(p.project);
+      if (p.dataset === undefined) {
+        return jsonResult(
+          await bqGet(token, `/projects/${encodeURIComponent(proj)}/datasets?maxResults=200`),
+        );
+      }
+      return jsonResult(
+        await bqGet(
+          token,
+          `/projects/${encodeURIComponent(proj)}/datasets/${encodeURIComponent(p.dataset)}/tables?maxResults=200`,
+        ),
+      );
+    },
+  );
+
+  reg(
+    "bigquery_get",
+    "Fetch one BigQuery table's schema + METADATA (`GET /projects/<project>/datasets/<dataset>/tables/<table>`). Returns the table object including `schema.fields` (field names + types only), `numRows`, `numBytes`, `creationTime`, and `lastModifiedTime`. Row COUNTS and byte sizes are metadata, NOT row data; no cell values are returned.",
+    z.object({
+      project: z.string().min(1).optional(),
+      dataset: z.string().min(1),
+      table: z.string().min(1),
+    }),
+    async (p) => {
+      const token = await accessToken();
+      const proj = project(p.project);
+      return jsonResult(
+        await bqGet(
+          token,
+          `/projects/${encodeURIComponent(proj)}/datasets/${encodeURIComponent(p.dataset)}/tables/${encodeURIComponent(p.table)}`,
+        ),
+      );
+    },
+  );
+
+  reg(
+    "bigquery_search",
+    "Substring search over dataset and table NAMES (case-insensitive) — METADATA ONLY. With no `dataset`, searches dataset ids. With `dataset` set, searches that dataset's table ids + friendly names. Returns a `{ matches: [...] }` envelope of metadata entries. Never queries or samples row data.",
+    z.object({
+      project: z.string().min(1).optional(),
+      dataset: z.string().min(1).optional(),
+      query: z.string().min(1),
+    }),
+    async (p) => {
+      const token = await accessToken();
+      const proj = project(p.project);
+      if (p.dataset === undefined) {
+        const root = await bqGet(
+          token,
+          `/projects/${encodeURIComponent(proj)}/datasets?maxResults=200`,
+        );
+        const matches = asArray(root, "datasets").filter((d) => datasetMatches(d, p.query));
+        return jsonResult({ matches });
+      }
+      const root = await bqGet(
+        token,
+        `/projects/${encodeURIComponent(proj)}/datasets/${encodeURIComponent(p.dataset)}/tables?maxResults=200`,
+      );
+      const matches = asArray(root, "tables").filter((t) => tableMatches(t, p.query));
+      return jsonResult({ matches });
+    },
+  );
+}

package/connectors/bitbucket/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.bitbucket",
+  "displayName": "Bitbucket Cloud",
+  "version": "0.1.0",
+  "description": "Bitbucket Cloud REST connector (repositories, pull requests). Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.bitbucket.org", "bitbucket.org"]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 300,
+  "minNimbusVersion": "0.2.0"
+}