@nimbus-dev/connectors 0.1.0

package/connectors/monte-carlo/src/server.ts

@@ -0,0 +1,241 @@
+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 { filterMonteCarloIncidents } from "./search-filter.ts";
+
+const GRAPHQL_URL = "https://api.getmontecarlo.com/graphql";
+
+/**
+ * Relay-paginated incidents query. `first`/`after` are passed as GraphQL *variables* (never string
+ * interpolation) and `pageInfo` drives the cursor: `endCursor` becomes the next `after` while
+ * `hasNextPage` is true.
+ */
+const GET_INCIDENTS_QUERY = `
+  query NimbusGetIncidents($first: Int!, $after: String) {
+    getIncidents(first: $first, after: $after) {
+      edges {
+        node {
+          incidentId
+          status
+          severity
+          firstSeenAt
+          monitoredTable
+        }
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+    }
+  }
+`.trim();
+
+function requireEnv(name: string): string {
+  const v = process.env[name]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error(`${name} is not set`);
+  }
+  return v;
+}
+
+function asObject(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+/**
+ * Single POST helper for the Monte Carlo GraphQL endpoint. Sends `{ query, variables }` with the
+ * `x-mcd-id`/`x-mcd-token` key-pair auth headers, throws on a non-ok HTTP status or a non-empty
+ * GraphQL `errors` array, and returns the parsed top-level response object. Reused by every read
+ * and write tool so auth + error handling stay in one place.
+ */
+async function mcGraphql(
+  apiId: string,
+  apiToken: string,
+  query: string,
+  variables: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const res = await fetchWithTimeout(GRAPHQL_URL, {
+    method: "POST",
+    headers: {
+      "x-mcd-id": apiId,
+      "x-mcd-token": apiToken,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+    body: JSON.stringify({ query, variables }),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Monte Carlo API error ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  const parsed = asObject(JSON.parse(text) as unknown) ?? {};
+  const errors = parsed["errors"];
+  if (Array.isArray(errors) && errors.length > 0) {
+    const first = asObject(errors[0])?.["message"];
+    const message = typeof first === "string" ? first : JSON.stringify(errors[0]);
+    throw new Error(`Monte Carlo GraphQL error: ${message}`);
+  }
+  return parsed;
+}
+
+interface IncidentsPage {
+  readonly incidents: unknown[];
+  readonly hasNextPage: boolean;
+  readonly endCursor: string | null;
+}
+
+function parseIncidentsPage(parsed: unknown): IncidentsPage {
+  const getIncidents = asObject(asObject(asObject(parsed)?.["data"])?.["getIncidents"]);
+  const edges = Array.isArray(getIncidents?.["edges"]) ? (getIncidents["edges"] as unknown[]) : [];
+  const incidents: unknown[] = [];
+  for (const edge of edges) {
+    const node = asObject(edge)?.["node"];
+    if (node !== undefined) incidents.push(node);
+  }
+  const pageInfo = asObject(getIncidents?.["pageInfo"]);
+  const hasNextPage = pageInfo?.["hasNextPage"] === true;
+  const endCursor = typeof pageInfo?.["endCursor"] === "string" ? pageInfo["endCursor"] : null;
+  return { incidents, hasNextPage, endCursor };
+}
+
+async function fetchIncidentsPage(
+  apiId: string,
+  apiToken: string,
+  first: number,
+  after: string | null,
+): Promise<IncidentsPage> {
+  const parsed = await mcGraphql(apiId, apiToken, GET_INCIDENTS_QUERY, { first, after });
+  return parseIncidentsPage(parsed);
+}
+
+const SET_INCIDENT_FEEDBACK_MUTATION = `
+  mutation NimbusSetIncidentFeedback($incidentId: UUID!, $feedback: IncidentFeedback!) {
+    setIncidentFeedback(input: { incidentId: $incidentId, feedback: $feedback }) {
+      __typename
+    }
+  }
+`.trim();
+
+/** Set the feedback/status on a Monte Carlo incident; throws on a GraphQL/HTTP error. */
+async function setIncidentFeedback(
+  apiId: string,
+  apiToken: string,
+  incidentId: string,
+  feedback: "ACKNOWLEDGED" | "RESOLVED",
+): Promise<void> {
+  await mcGraphql(apiId, apiToken, SET_INCIDENT_FEEDBACK_MUTATION, { incidentId, feedback });
+}
+
+/** One page (up to 500) for `_get`/`_search`, which do not paginate. */
+async function fetchIncidents(apiId: string, apiToken: string): Promise<unknown[]> {
+  const page = await fetchIncidentsPage(apiId, apiToken, 500, null);
+  return page.incidents;
+}
+
+export function registerMonteCarloTools(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: "monte-carlo",
+    scopeEnv: "NIMBUS_MCP_MONTE_CARLO_WRITE_SCOPE",
+    scopeKinds: ["incident"],
+  });
+
+  reg(
+    "montecarlo_list",
+    "List Monte Carlo data-quality incidents (relay GraphQL `getIncidents`). Paginated: `cursor` (the relay `after` token) + `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 apiId = requireEnv("MONTECARLO_API_ID");
+      const apiToken = requireEnv("MONTECARLO_API_TOKEN");
+      const first = p.limit ?? 200;
+      const after = p.cursor === undefined || p.cursor === "" ? null : p.cursor;
+      const page = await fetchIncidentsPage(apiId, apiToken, first, after);
+      const nextCursor = page.hasNextPage ? page.endCursor : null;
+      return jsonResult({ items: page.incidents, nextCursor });
+    },
+  );
+
+  reg(
+    "montecarlo_get",
+    "Fetch one Monte Carlo incident by its id. Throws when the incident is not found.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      const apiId = requireEnv("MONTECARLO_API_ID");
+      const apiToken = requireEnv("MONTECARLO_API_TOKEN");
+      const incidents = await fetchIncidents(apiId, apiToken);
+      const found = incidents.find((inc) => asObject(inc)?.["incidentId"] === p.id);
+      if (found === undefined) {
+        throw new Error(`Monte Carlo incident not found: ${p.id}`);
+      }
+      return jsonResult(found);
+    },
+  );
+
+  reg(
+    "montecarlo_search",
+    "Substring search across Monte Carlo incidents. Matches the query (case-insensitive) against incidentId, status, severity, and monitoredTable. Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(200),
+    async (p) => {
+      const apiId = requireEnv("MONTECARLO_API_ID");
+      const apiToken = requireEnv("MONTECARLO_API_TOKEN");
+      const incidents = await fetchIncidents(apiId, apiToken);
+      const matches = filterMonteCarloIncidents(incidents, { query: p.query, limit: p.limit });
+      return jsonResult({ matches });
+    },
+  );
+
+  registerWriteTool(
+    "montecarlo_incident_acknowledge",
+    {
+      mutates: "montecarlo.incident.acknowledge",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "incident", value: p.incidentId }),
+    },
+    "Acknowledge a Monte Carlo incident.",
+    z.object({ incidentId: z.string().min(1) }),
+    async (p) => {
+      const apiId = requireEnv("MONTECARLO_API_ID");
+      const apiToken = requireEnv("MONTECARLO_API_TOKEN");
+      await setIncidentFeedback(apiId, apiToken, p.incidentId, "ACKNOWLEDGED");
+      return jsonResult({ status: "ok", incidentId: p.incidentId });
+    },
+  );
+
+  registerWriteTool(
+    "montecarlo_incident_resolve",
+    {
+      mutates: "montecarlo.incident.resolve",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "incident", value: p.incidentId }),
+    },
+    "Resolve a Monte Carlo incident.",
+    z.object({ incidentId: z.string().min(1) }),
+    async (p) => {
+      const apiId = requireEnv("MONTECARLO_API_ID");
+      const apiToken = requireEnv("MONTECARLO_API_TOKEN");
+      await setIncidentFeedback(apiId, apiToken, p.incidentId, "RESOLVED");
+      return jsonResult({ status: "ok", incidentId: p.incidentId });
+    },
+  );
+}
+
+// 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-monte-carlo", registerMonteCarloTools);
+}
+
+if (import.meta.main) await startConnector();

package/connectors/netlify/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "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.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.netlify.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,37 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type NetlifySearchMatchOptions = SearchMatchOptions;
+
+function subStringField(row: Record<string, unknown>, key: string, sub: string): string {
+  const obj = row[key];
+  if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
+    return "";
+  }
+  const v = (obj as Record<string, unknown>)[sub];
+  return typeof v === "string" ? v : "";
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [
+    stringField(row, "id"),
+    stringField(row, "name"),
+    stringField(row, "url"),
+    stringField(row, "ssl_url"),
+    subStringField(row, "build_settings", "repo_url"),
+    subStringField(row, "build_settings", "repo_branch"),
+    subStringField(row, "published_deploy", "state"),
+    subStringField(row, "published_deploy", "branch"),
+    subStringField(row, "published_deploy", "commit_ref"),
+  ];
+}
+
+export const filterNetlifySites = makeQueryFilter(fieldsOf);

package/connectors/netlify/src/server.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { matchesResult, 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 { filterNetlifySites } from "./search-filter.ts";
+
+const BASE = "https://api.netlify.com";
+
+function token(): string {
+  const t = process.env["NETLIFY_TOKEN"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("NETLIFY_TOKEN is not set");
+  }
+  return t;
+}
+
+function authHeader(): Record<string, string> {
+  return { Authorization: `Bearer ${token()}`, Accept: "application/json" };
+}
+
+async function netlifyGet(path: string): Promise<unknown> {
+  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Netlify ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+await runReadOnlyMcpConnector("nimbus-netlify", (reg) => {
+  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`.",
+    z.object({
+      per_page: z.number().int().min(1).max(100).optional(),
+    }),
+    async (p) => {
+      const search = new URLSearchParams({ per_page: String(p.per_page ?? 100), page: "1" });
+      return jsonResult(await netlifyGet(`/api/v1/sites?${search.toString()}`));
+    },
+  );
+
+  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.",
+    z.object({
+      siteId: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await netlifyGet(`/api/v1/sites/${encodeURIComponent(p.siteId)}`));
+    },
+  );
+
+  reg(
+    "netlify_search",
+    "Substring search across Netlify sites. Matches the query against id, name, url, ssl_url, the linked git repo + branch, and the published-deploy state / branch / commit ref (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const search = new URLSearchParams({ per_page: "100", page: "1" });
+      const root = await netlifyGet(`/api/v1/sites?${search.toString()}`);
+      return matchesResult(root, filterNetlifySites, p);
+    },
+  );
+});

package/connectors/newrelic/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.newrelic",
+  "displayName": "New Relic",
+  "version": "0.1.0",
+  "description": "New Relic NerdGraph + REST connector (alerts, incidents, dashboards). Read-focused.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.newrelic.com", "api.eu.newrelic.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 300,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/newrelic/src/server.ts

@@ -0,0 +1,48 @@
+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";
+
+function apiKey(): string {
+  const k = process.env["NEW_RELIC_API_KEY"]?.trim();
+  if (k === undefined || k === "") {
+    throw new Error("NEW_RELIC_API_KEY is not set");
+  }
+  return k;
+}
+
+async function nrGet(path: string): Promise<unknown> {
+  const res = await fetch(`https://api.newrelic.com${path}`, {
+    headers: { "X-Api-Key": apiKey(), Accept: "application/json" },
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`New Relic ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+const mcp = new McpServer({ name: "nimbus-newrelic", version: "0.1.0" });
+const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
+
+reg("newrelic_application_list", "List APM applications.", z.object({}), async () =>
+  jsonResult(await nrGet("/v2/applications.json")),
+);
+
+reg(
+  "newrelic_alert_violations",
+  "List recent alert violations.",
+  z.object({ only_open: z.boolean().optional() }),
+  async (p) => {
+    const only = p.only_open === true ? "true" : "false";
+    return jsonResult(await nrGet(`/v2/alerts_violations.json?only_open=${only}`));
+  },
+);
+
+const transport = new StdioServerTransport();
+await mcp.connect(transport);

package/connectors/notion/nimbus.extension.json

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

package/connectors/notion/src/kb-append.ts

@@ -0,0 +1,23 @@
+import { type KbCitation, markdownToNotionBlocks } from "../../../shared/kb-markdown.ts";
+
+export interface NotionKbAppendInput {
+  databaseId: string;
+  title: string;
+  bodyMarkdown: string;
+  citations: readonly KbCitation[];
+  titlePropertyName?: string;
+}
+
+function richText(content: string): Record<string, unknown>[] {
+  return [{ type: "text", text: { content: content.slice(0, 2000) } }];
+}
+
+/** Build the `POST /v1/pages` request body for a tribal-knowledge KB page in a database. */
+export function buildNotionKbPageBody(input: NotionKbAppendInput): Record<string, unknown> {
+  const prop = input.titlePropertyName ?? "Name";
+  return {
+    parent: { database_id: input.databaseId },
+    properties: { [prop]: { title: richText(input.title) } },
+    children: markdownToNotionBlocks(input.bodyMarkdown, input.citations),
+  };
+}