@nimbus-dev/connectors 0.1.0

package/connectors/metabase/src/server.ts

@@ -0,0 +1,83 @@
+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 { filterMetabaseDashboards } from "./search-filter.ts";
+
+function trimTrailingSlash(s: string): string {
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+
+function apiBase(): string {
+  const v = process.env["METABASE_URL"]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error("METABASE_URL is not set");
+  }
+  return trimTrailingSlash(v);
+}
+
+function authHeader(): Record<string, string> {
+  const k = process.env["METABASE_API_KEY"]?.trim();
+  if (k === undefined || k === "") {
+    throw new Error("METABASE_API_KEY is not set");
+  }
+  return { "x-api-key": k, Accept: "application/json" };
+}
+
+async function mbGet(path: string): Promise<unknown> {
+  const res = await fetch(`${apiBase()}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Metabase ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function dashboardsFrom(root: unknown): unknown[] {
+  if (Array.isArray(root)) {
+    return root;
+  }
+  const data = (root as { data?: unknown } | null)?.data;
+  return Array.isArray(data) ? data : [];
+}
+
+await runReadOnlyMcpConnector("nimbus-metabase", (reg) => {
+  reg(
+    "metabase_list",
+    "List Metabase dashboards (`GET /api/dashboard`). Metabase returns the full list in one response; `limit` (default 200) caps the returned list client-side.",
+    z.object({
+      limit: z.number().int().min(1).max(500).optional(),
+    }),
+    async (p) => {
+      const root = await mbGet("/api/dashboard");
+      const dashboards = dashboardsFrom(root);
+      const cap = p.limit ?? 200;
+      return jsonResult({ items: dashboards.slice(0, cap) });
+    },
+  );
+
+  reg(
+    "metabase_get",
+    "Fetch one Metabase dashboard by numeric id (`/api/dashboard/{id}`). Throws when no dashboard with that id exists.",
+    z.object({
+      id: z.number().int(),
+    }),
+    async (p) => {
+      return jsonResult(await mbGet(`/api/dashboard/${encodeURIComponent(String(p.id))}`));
+    },
+  );
+
+  reg(
+    "metabase_search",
+    "Substring search across Metabase dashboards. Matches the query (case-insensitive) against dashboard name and description. Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(200),
+    async (p) => {
+      const root = await mbGet("/api/dashboard");
+      const matches = filterMetabaseDashboards(dashboardsFrom(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+});

package/connectors/miro/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.miro",
+  "displayName": "Miro",
+  "version": "0.1.0",
+  "description": "Miro connector (read-only). Surfaces the authenticated user's boards as miro:board items in the local index via GET /v2/boards — the board name, the description, the owner name, the create date, the last-modified timestamp, and the view link. 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.miro.com. The list endpoint paginates by the response cursor query param until absent; the gateway-side syncable walks a single forward pass per cycle, page-capped. Read-only — hitlRequired is intentionally empty. Sparse structured board metadata; the canonical url is the board viewLink.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.miro.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,24 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type MiroSearchMatchOptions = SearchMatchOptions;
+
+/**
+ * Miro board objects are flat — `{ id, name, description, owner: { name }, ... }`.
+ * Match against the board name, description, and owner name (case-insensitive
+ * substring). The owner is itself a nested object.
+ */
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  const owner = asObjectish(row["owner"]) ?? {};
+  return [stringField(row, "name"), stringField(row, "description"), stringField(owner, "name")];
+}
+
+export const filterMiroBoards = makeQueryFilter(fieldsOf);

package/connectors/miro/src/server.ts

@@ -0,0 +1,76 @@
+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 { filterMiroBoards } from "./search-filter.ts";
+
+const BASE = "https://api.miro.com";
+
+function apiToken(): string {
+  const t = process.env["MIRO_TOKEN"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("MIRO_TOKEN is not set");
+  }
+  return t;
+}
+
+function authHeader(): Record<string, string> {
+  return { Authorization: `Bearer ${apiToken()}`, Accept: "application/json" };
+}
+
+async function miroGet(path: string): Promise<unknown> {
+  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Miro ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function boardsFrom(root: unknown): unknown[] {
+  const data = (root as { data?: unknown } | null)?.data;
+  return Array.isArray(data) ? data : [];
+}
+
+await runReadOnlyMcpConnector("nimbus-miro", (reg) => {
+  reg(
+    "miro_list",
+    "List the authenticated user's Miro boards (GET /v2/boards?limit=N&cursor=<cursor>). Returns the { data: [...], cursor?, total, size } envelope — `data` holds the board objects, each shaped { id, name, description, createdAt, modifiedAt, owner: { name }, viewLink, ... }; `cursor` (when present) is the opaque token for the next page. `limit` (default 50, max 50) caps the page_size of the single first-page request.",
+    z.object({
+      limit: z.number().int().min(1).max(50).optional(),
+      cursor: z.string().optional(),
+    }),
+    async (p) => {
+      const params = new URLSearchParams({ limit: String(p.limit ?? 50) });
+      if (p.cursor !== undefined && p.cursor !== "") {
+        params.set("cursor", p.cursor);
+      }
+      return jsonResult(await miroGet(`/v2/boards?${params.toString()}`));
+    },
+  );
+
+  reg(
+    "miro_get",
+    "Fetch one Miro board by its id (GET /v2/boards/{boardId}). Returns the board object directly (NOT wrapped in `data`). Throws when no board with that id exists.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await miroGet(`/v2/boards/${encodeURIComponent(p.id)}`));
+    },
+  );
+
+  reg(
+    "miro_search",
+    "**Substring search over the FIRST PAGE only** (up to 50 most-recently-listed boards) of the authenticated user's Miro boards. This tool fetches GET /v2/boards?limit=50 once and matches the query locally (case-insensitive) against the board name, description, and owner name. **Boards beyond the first page are not searchable here — query the local Nimbus index instead for full coverage.** Returns a { matches: [...] } envelope.",
+    searchToolInputSchema(50),
+    async (p) => {
+      const root = await miroGet("/v2/boards?limit=50");
+      const matches = filterMiroBoards(boardsFrom(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+});

package/connectors/mlflow/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.mlflow",
+  "displayName": "MLflow",
+  "version": "0.1.0",
+  "description": "MLflow connector. Surfaces MLflow registered models — name, description, latest version/stage/status/run, created + updated timestamps, and tags — into the local index as `mlflow:ml_model` items via the Model Registry API (`GET /api/2.0/mlflow/registered-models/search`, token-paginated on `next_page_token`). API-token auth (sent as `Authorization: Bearer <token>`). MLflow has no universal SaaS host: the tracking-server URL is supplied via the `mlflow.host` vault key and added to the sandbox network list at spawn time by `phase3AddMlflowMcp`, so the static manifest network list is intentionally empty. v1 indexes registered models only — experiments, runs, metrics, params, and artifacts are a deferred follow-up. Two HITL-gated write tools transition a model version's stage (`POST /api/2.0/mlflow/model-versions/transition-stage`): `mlflow_model_promote` (promote to Production, HITL `mlflow.model.promote`; `archiveExisting` defaults true) and `mlflow_model_transition_stage` (transition to any stage, HITL `mlflow.model.transition_stage`; `archiveExisting` defaults false). Stage changes are reversible.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": [],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "hitlRequired": ["write"],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,38 @@
+import {
+  asRecord,
+  makeQueryFilter,
+  type SearchMatchOptions,
+} from "../../../shared/search-filter.ts";
+
+export type MlflowSearchMatchOptions = SearchMatchOptions;
+
+function stringAt(row: Record<string, unknown>, key: string): string {
+  const v = row[key];
+  return typeof v === "string" ? v : "";
+}
+
+function tagsHaystack(row: Record<string, unknown>): string {
+  const tags = row["tags"];
+  if (!Array.isArray(tags)) {
+    return "";
+  }
+  const parts: string[] = [];
+  for (const t of tags) {
+    const tag = asRecord(t);
+    if (tag === undefined) {
+      continue;
+    }
+    parts.push(`${stringAt(tag, "key")}=${stringAt(tag, "value")}`);
+  }
+  return parts.join(" ");
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asRecord(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [stringAt(row, "name"), stringAt(row, "description"), tagsHaystack(row)];
+}
+
+export const filterMlflowModels = makeQueryFilter(fieldsOf);

package/connectors/mlflow/src/server.ts

@@ -0,0 +1,167 @@
+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 { filterMlflowModels } from "./search-filter.ts";
+
+function trimTrailingSlash(s: string): string {
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+
+function apiBase(): string {
+  const v = process.env["MLFLOW_HOST"]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error("MLFLOW_HOST is not set");
+  }
+  return trimTrailingSlash(v);
+}
+
+function authHeader(): Record<string, string> {
+  const k = process.env["MLFLOW_TOKEN"]?.trim();
+  if (k === undefined || k === "") {
+    throw new Error("MLFLOW_TOKEN is not set");
+  }
+  return { Authorization: `Bearer ${k}`, Accept: "application/json" };
+}
+
+async function mlflowGet(path: string): Promise<unknown> {
+  const res = await fetchWithTimeout(`${apiBase()}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`MLflow ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+async function mlflowPost(path: string, body: unknown): Promise<unknown> {
+  const res = await fetchWithTimeout(`${apiBase()}${path}`, {
+    method: "POST",
+    headers: { ...authHeader(), "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`MLflow ${path} ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return text === "" ? {} : (JSON.parse(text) as unknown);
+}
+
+const TRANSITION_PATH = "/api/2.0/mlflow/model-versions/transition-stage";
+
+function modelsFrom(root: unknown): unknown[] {
+  const models = (root as { registered_models?: unknown } | null)?.registered_models;
+  return Array.isArray(models) ? models : [];
+}
+
+export function registerMlflowTools(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: "mlflow",
+    scopeEnv: "NIMBUS_MCP_MLFLOW_WRITE_SCOPE",
+    scopeKinds: ["model"],
+  });
+
+  reg(
+    "mlflow_list",
+    "List MLflow registered models (`GET /api/2.0/mlflow/registered-models/search`). Returns a single page; `limit` (1..100, default 100) caps the page size. Returns the raw `{ registered_models, next_page_token }` envelope.",
+    z.object({
+      limit: z.number().int().min(1).max(100).optional(),
+    }),
+    async (p) => {
+      const limit = p.limit ?? 100;
+      const params = new URLSearchParams({ max_results: String(limit) });
+      return jsonResult(
+        await mlflowGet(`/api/2.0/mlflow/registered-models/search?${params.toString()}`),
+      );
+    },
+  );
+
+  reg(
+    "mlflow_get",
+    "Fetch one MLflow registered model by `name` (`GET /api/2.0/mlflow/registered-models/get?name={name}`). Throws when no registered model with that name exists.",
+    z.object({
+      name: z.string().min(1),
+    }),
+    async (p) => {
+      const params = new URLSearchParams({ name: p.name });
+      return jsonResult(
+        await mlflowGet(`/api/2.0/mlflow/registered-models/get?${params.toString()}`),
+      );
+    },
+  );
+
+  reg(
+    "mlflow_search",
+    "Substring search across MLflow registered models. Matches the query (case-insensitive) against the model's `name`, `description`, and flattened `key=value` tags. Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const params = new URLSearchParams({ max_results: "100" });
+      const root = await mlflowGet(`/api/2.0/mlflow/registered-models/search?${params.toString()}`);
+      const matches = filterMlflowModels(modelsFrom(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+
+  registerWriteTool(
+    "mlflow_model_promote",
+    {
+      mutates: "mlflow.model.promote",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "model", value: p.name }),
+    },
+    "Promote a model version to Production (`POST /api/2.0/mlflow/model-versions/transition-stage`, stage=Production; requires HITL mlflow.model.promote). `archiveExisting` (default true) archives other Production versions so this becomes the single active one; pass false to keep them. Archiving is a reversible stage change.",
+    z.object({
+      name: z.string().min(1),
+      version: z.string().min(1),
+      archiveExisting: z.boolean().optional(),
+    }),
+    async (p) => {
+      await mlflowPost(TRANSITION_PATH, {
+        name: p.name,
+        version: p.version,
+        stage: "Production",
+        archive_existing_versions: p.archiveExisting ?? true, // promote defaults to archiving the incumbent
+      });
+      return jsonResult({ status: "ok", name: p.name, version: p.version, stage: "Production" });
+    },
+  );
+
+  registerWriteTool(
+    "mlflow_model_transition_stage",
+    {
+      mutates: "mlflow.model.transition_stage",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "model", value: p.name }),
+    },
+    "Transition a model version to a chosen stage (`POST /api/2.0/mlflow/model-versions/transition-stage`; requires HITL mlflow.model.transition_stage). `archiveExisting` default false.",
+    z.object({
+      name: z.string().min(1),
+      version: z.string().min(1),
+      stage: z.enum(["None", "Staging", "Production", "Archived"]),
+      archiveExisting: z.boolean().optional(),
+    }),
+    async (p) => {
+      await mlflowPost(TRANSITION_PATH, {
+        name: p.name,
+        version: p.version,
+        stage: p.stage,
+        archive_existing_versions: p.archiveExisting ?? false,
+      });
+      return jsonResult({ status: "ok", name: p.name, version: p.version, stage: p.stage });
+    },
+  );
+}
+
+export async function startConnector(): Promise<void> {
+  await runReadOnlyMcpConnector("nimbus-mlflow", registerMlflowTools);
+}
+
+if (import.meta.main) await startConnector();

package/connectors/monte-carlo/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.monte-carlo",
+  "displayName": "Monte Carlo",
+  "version": "0.1.0",
+  "description": "Monte Carlo connector. Indexes Monte Carlo data-quality incidents as `montecarlo:data_quality_test` items in the local index and exposes three read-only tools (`montecarlo_list`, `montecarlo_get`, `montecarlo_search`) plus two HITL-gated write tools (`montecarlo_incident_acknowledge`, `montecarlo_incident_resolve`) to the Nimbus agent. Uses the Monte Carlo GraphQL API at `api.getmontecarlo.com` with API key pair auth (x-mcd-id / x-mcd-token headers). The gateway injects `MONTECARLO_API_ID` and `MONTECARLO_API_TOKEN` at spawn time.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.getmontecarlo.com"],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "hitlRequired": ["write"],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.5.0"
+}

package/connectors/monte-carlo/src/search-filter.ts

@@ -0,0 +1,11 @@
+import {
+  fieldsFromKeys,
+  makeQueryFilter,
+  type SearchMatchOptions,
+} from "../../../shared/search-filter.ts";
+
+export type MonteCarloSearchMatchOptions = SearchMatchOptions;
+
+export const filterMonteCarloIncidents = makeQueryFilter(
+  fieldsFromKeys(["incidentId", "status", "severity", "monitoredTable"]),
+);