@nimbus-dev/connectors 0.1.0

package/connectors/cloud-logging/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.cloud-logging",
+  "displayName": "GCP Cloud Logging",
+  "version": "0.1.0",
+  "description": "GCP Cloud Logging metadata connector (Tier-3, no-row-data). Indexes log routing SINK configuration metadata only — sink name, destination, filter expression, description, disabled flag, and create/update timestamps — via the gcloud CLI's `gcloud logging sinks list/describe` commands. Never reads log ENTRIES / row data: there is no `gcloud logging read` and no `gcloud logging entries list`. 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": ["logging.googleapis.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/cloud-logging/src/server.ts

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

package/connectors/cloud-logging/src/tools.ts

@@ -0,0 +1,115 @@
+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";
+import { assertSafeCliArg } from "../../../shared/safe-cli-arg.ts";
+
+/**
+ * GCP Cloud Logging (Tier-3, no-row-data) MCP tool surface. ALL tools index log
+ * routing SINK configuration metadata only (sink name, destination, filter
+ * expression, description, disabled flag, create/update timestamps). NONE read
+ * log ENTRIES / row data — there is NO `gcloud logging read`, NO
+ * `gcloud logging entries list`, NO tail. The names are introspected by the
+ * `assertNoRowDataTools` contract test, so they must never contain a row-data
+ * segment (read/entries/events/query/results/scan/tail/…). (`read` is not a
+ * denylisted segment, but the commands the tools shell out to are sinks-only.)
+ */
+export const CLOUD_LOGGING_TOOL_NAMES = [
+  "cloud_logging_list",
+  "cloud_logging_get",
+  "cloud_logging_search",
+] as const;
+
+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 asArray(parsed: unknown): unknown[] {
+  return Array.isArray(parsed) ? parsed : [];
+}
+
+/** The configured GCP project id, if `GOOGLE_CLOUD_PROJECT` is set at spawn. */
+function projectArgs(): string[] {
+  const project = process.env["GOOGLE_CLOUD_PROJECT"]?.trim();
+  return project !== undefined && project !== "" ? ["--project", project] : [];
+}
+
+/**
+ * Run `gcloud logging <args> --format json` and parse stdout. gcloud reads
+ * Application Default Credentials from `GOOGLE_APPLICATION_CREDENTIALS`
+ * natively from the process env injected at spawn time. Throws on non-zero exit.
+ */
+async function gcloudLogging(args: string[]): Promise<unknown> {
+  const { code, stdout, stderr } = await nimbusSpawn(
+    ["gcloud", "logging", ...args, ...projectArgs(), "--format", "json"],
+    {},
+  );
+  const out = stdout.trim();
+  const err = stderr.trim();
+  if (code !== 0) {
+    throw new Error(`gcloud logging ${args[0] ?? ""} failed: ${err.slice(0, 400)}`);
+  }
+  return out === "" ? [] : (JSON.parse(out) as unknown);
+}
+
+function sinkMatches(entry: unknown, q: string): boolean {
+  if (!isRecord(entry)) {
+    return false;
+  }
+  const needle = q.toLowerCase();
+  return (
+    strField(entry, "name").toLowerCase().includes(needle) ||
+    strField(entry, "filter").toLowerCase().includes(needle) ||
+    strField(entry, "destination").toLowerCase().includes(needle)
+  );
+}
+
+/**
+ * Register the read-only, metadata-only Cloud Logging tools onto the given
+ * registrar. Shared between `server.ts` (live) and the contract test
+ * (introspection).
+ */
+export function registerCloudLoggingTools(reg: ZodToolRegistrar): void {
+  reg(
+    "cloud_logging_list",
+    "List GCP Cloud Logging routing SINKS — METADATA ONLY (`gcloud logging sinks list`). Each entry carries `name`, `destination`, `filter`, `description`, `disabled`, `createTime`, and `updateTime`. Never reads log-entry contents / row data.",
+    z.object({}),
+    async () => {
+      return jsonResult(asArray(await gcloudLogging(["sinks", "list"])));
+    },
+  );
+
+  reg(
+    "cloud_logging_get",
+    "Fetch one Cloud Logging routing sink's configuration METADATA (`gcloud logging sinks describe <sink>`). Returns the sink's `name`, `destination`, `filter`, `description`, `disabled` flag, and create/update timestamps. No log-entry contents are returned — metadata only.",
+    z.object({
+      sinkName: z.string().min(1),
+    }),
+    async (p) => {
+      // `sinkName` is a bare positional to `gcloud logging sinks describe`; guard
+      // against argv flag smuggling (a value beginning with "-" would be parsed as
+      // a gcloud flag).
+      return jsonResult(
+        await gcloudLogging(["sinks", "describe", assertSafeCliArg(p.sinkName, "sinkName")]),
+      );
+    },
+  );
+
+  reg(
+    "cloud_logging_search",
+    "Substring search over Cloud Logging routing SINK names, filters, and destinations (case-insensitive) — METADATA ONLY. Returns a `{ matches: [...] }` envelope of `gcloud logging sinks list` metadata entries matching the query. Never reads log-entry contents / row data.",
+    z.object({
+      query: z.string().min(1),
+    }),
+    async (p) => {
+      const sinks = asArray(await gcloudLogging(["sinks", "list"]));
+      const matches = sinks.filter((s) => sinkMatches(s, p.query));
+      return jsonResult({ matches });
+    },
+  );
+}

package/connectors/cloudwatch/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.cloudwatch",
+  "displayName": "Amazon CloudWatch",
+  "version": "0.1.0",
+  "description": "Amazon CloudWatch Logs metadata connector (Tier-3, no-row-data). Indexes log-group metadata only — log-group name, ARN, retention, stored bytes, creation time, metric-filter count, and an optional stream count + last-event timestamp — via the AWS CLI's CloudWatch Logs describe commands. Never fetches log-event contents / row data: there is no get-log-events, no filter-log-events, no start-query, no get-query-results, and no tail. Reuses the existing AWS credentials via the aws CLI. Read-only; no write tools.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["sts.amazonaws.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/cloudwatch/src/server.ts

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

package/connectors/cloudwatch/src/tools.ts

@@ -0,0 +1,144 @@
+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";
+import { isSafeCliArg } from "../../../shared/safe-cli-arg.ts";
+
+/**
+ * A log-group name / prefix passed as a value to the `aws logs` CLI. Rejected at
+ * the schema boundary if it begins with `-` (argv flag smuggling) or contains
+ * control characters.
+ */
+const cliArg = z
+  .string()
+  .min(1)
+  .refine(isSafeCliArg, { message: 'must not start with "-" or contain control characters' });
+
+/**
+ * Amazon CloudWatch Logs (Tier-3, no-row-data) MCP tool surface. ALL tools
+ * index log-GROUP metadata only (group name, ARN, retention, stored bytes,
+ * creation time, metric-filter count) plus optional stream METADATA (stream
+ * name, last-event timestamp, stored bytes). NONE fetch log-event contents /
+ * row data — there is NO `get-log-events`, NO `filter-log-events`, NO
+ * `start-query`, NO `get-query-results`, NO `tail`. The names are introspected
+ * by the `assertNoRowDataTools` contract test, so they must never contain a
+ * row-data segment (events/query/results/scan/tail/…).
+ */
+export const CLOUDWATCH_TOOL_NAMES = [
+  "cloudwatch_list",
+  "cloudwatch_get",
+  "cloudwatch_search",
+] as const;
+
+const LIMIT = "50";
+
+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 asArray(parsed: unknown, key: string): unknown[] {
+  if (!isRecord(parsed)) {
+    return [];
+  }
+  const arr = parsed[key];
+  return Array.isArray(arr) ? arr : [];
+}
+
+/**
+ * Run `aws logs <args> --output json` and parse stdout. The AWS CLI reads
+ * AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_DEFAULT_REGION / AWS_PROFILE
+ * natively from the process env injected at spawn time. Throws on non-zero exit.
+ */
+async function logsCli(args: string[]): Promise<unknown> {
+  const { code, stdout, stderr } = await nimbusSpawn(
+    ["aws", "logs", ...args, "--output", "json"],
+    {},
+  );
+  const out = stdout.trim();
+  const err = stderr.trim();
+  if (code !== 0) {
+    throw new Error(`aws logs ${args[0] ?? ""} failed: ${err.slice(0, 400)}`);
+  }
+  return out === "" ? {} : (JSON.parse(out) as unknown);
+}
+
+function groupMatches(entry: unknown, q: string): boolean {
+  if (!isRecord(entry)) {
+    return false;
+  }
+  return strField(entry, "logGroupName").toLowerCase().includes(q.toLowerCase());
+}
+
+/**
+ * Register the read-only, metadata-only CloudWatch Logs tools onto the given
+ * registrar. Shared between `server.ts` (live) and the contract test
+ * (introspection).
+ */
+export function registerCloudwatchTools(reg: ZodToolRegistrar): void {
+  reg(
+    "cloudwatch_list",
+    "List CloudWatch log GROUPS — METADATA ONLY (`aws logs describe-log-groups`). Each entry carries `logGroupName`, `arn`, `creationTime`, `retentionInDays`, `storedBytes`, and `metricFilterCount`. Optionally filter by a `prefix` on the log-group name. Never fetches log-event contents / row data.",
+    z.object({
+      prefix: cliArg.optional(),
+    }),
+    async (p) => {
+      const args = ["describe-log-groups", "--limit", LIMIT];
+      if (p.prefix !== undefined) {
+        args.push("--log-group-name-prefix", p.prefix);
+      }
+      return jsonResult(await logsCli(args));
+    },
+  );
+
+  reg(
+    "cloudwatch_get",
+    "Fetch one CloudWatch log group's METADATA plus a stream summary. Returns the matching `describe-log-groups` entry (name, ARN, retention, stored bytes, metric-filter count) and the group's `describe-log-streams` METADATA (stream names, last-event timestamps, stored bytes) ordered by last activity. No log-event contents are returned — metadata only.",
+    z.object({
+      logGroupName: cliArg,
+    }),
+    async (p) => {
+      const group = await logsCli([
+        "describe-log-groups",
+        "--log-group-name-prefix",
+        p.logGroupName,
+        "--limit",
+        LIMIT,
+      ]);
+      const match = asArray(group, "logGroups").find(
+        (g) => isRecord(g) && strField(g, "logGroupName") === p.logGroupName,
+      );
+      const streams = await logsCli([
+        "describe-log-streams",
+        "--log-group-name",
+        p.logGroupName,
+        "--order-by",
+        "LastEventTime",
+        "--descending",
+        "--limit",
+        LIMIT,
+      ]);
+      return jsonResult({
+        logGroup: match ?? null,
+        streams: asArray(streams, "logStreams"),
+      });
+    },
+  );
+
+  reg(
+    "cloudwatch_search",
+    "Substring search over CloudWatch log GROUP names (case-insensitive) — METADATA ONLY. Returns a `{ matches: [...] }` envelope of `describe-log-groups` metadata entries whose `logGroupName` contains the query. Never fetches log-event contents / row data.",
+    z.object({
+      query: z.string().min(1),
+    }),
+    async (p) => {
+      const root = await logsCli(["describe-log-groups", "--limit", LIMIT]);
+      const matches = asArray(root, "logGroups").filter((g) => groupMatches(g, p.query));
+      return jsonResult({ matches });
+    },
+  );
+}

package/connectors/codemagic/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.codemagic",
+  "displayName": "Codemagic",
+  "version": "0.1.0",
+  "description": "Codemagic REST connector (mobile CI/CD builds + apps). Read-only; surfaces build status, workflow id, branch and commit so the local index can correlate mobile CI runs back to PRs and incidents.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.codemagic.io"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,11 @@
+import {
+  fieldsFromKeys,
+  makeQueryFilter,
+  type SearchMatchOptions,
+} from "../../../shared/search-filter.ts";
+
+export type CodemagicSearchMatchOptions = SearchMatchOptions;
+
+export const filterCodemagicBuilds = makeQueryFilter(
+  fieldsFromKeys(["branch", "message", "workflowId", "status"]),
+);

package/connectors/codemagic/src/server.ts

@@ -0,0 +1,74 @@
+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 { filterCodemagicBuilds } from "./search-filter.ts";
+
+const CODEMAGIC_API = "https://api.codemagic.io";
+
+function authHeader(): Record<string, string> {
+  const t = process.env["CODEMAGIC_TOKEN"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("CODEMAGIC_TOKEN is not set");
+  }
+  return { "x-auth-token": t, Accept: "application/json" };
+}
+
+async function codemagicGet(path: string): Promise<unknown> {
+  const res = await fetch(`${CODEMAGIC_API}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Codemagic ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+await runReadOnlyMcpConnector("nimbus-codemagic", (reg) => {
+  reg(
+    "codemagic_list",
+    "List Codemagic resources. When `appId` is omitted, returns the user's accessible apps via `/apps`. When `appId` is provided, returns the app's recent builds via `/builds?appId=<id>` (limit optional).",
+    z.object({
+      appId: z.string().min(1).optional(),
+      limit: z.number().int().min(1).max(50).optional(),
+    }),
+    async (p) => {
+      if (p.appId === undefined) {
+        return jsonResult(await codemagicGet("/apps"));
+      }
+      const limit = p.limit ?? 50;
+      return jsonResult(
+        await codemagicGet(`/builds?appId=${encodeURIComponent(p.appId)}&limit=${String(limit)}`),
+      );
+    },
+  );
+
+  reg(
+    "codemagic_get",
+    "Fetch a single Codemagic resource. When `buildId` is provided, returns the build via `/builds/<buildId>`. When omitted, returns the app via `/apps` filtered to `appId`.",
+    z.object({
+      appId: z.string().min(1),
+      buildId: z.string().min(1).optional(),
+    }),
+    async (p) => {
+      if (p.buildId === undefined) {
+        return jsonResult(await codemagicGet("/apps"));
+      }
+      return jsonResult(await codemagicGet(`/builds/${encodeURIComponent(p.buildId)}`));
+    },
+  );
+
+  reg(
+    "codemagic_search",
+    "Substring search across a Codemagic app's recent builds. Matches the query against `branch`, `message`, `workflowId`, and `status` (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(200).optional(),
+    }),
+    async (p) => {
+      const root = await codemagicGet(`/builds?appId=${encodeURIComponent(p.appId)}&limit=50`);
+      const builds = (root as { builds?: unknown[] } | null)?.builds;
+      return matchesResult(builds, filterCodemagicBuilds, p);
+    },
+  );
+});

package/connectors/confluence/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.confluence",
+  "displayName": "Confluence",
+  "version": "0.1.0",
+  "description": "Confluence REST connector (spaces, pages, search). Tenant host (`*.atlassian.net`) comes from confluence.base_url; PR 1 static manifest lists the API gateway only. Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.atlassian.com"]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 300,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,25 @@
+import { type KbCitation, markdownToConfluenceStorage } from "../../../shared/kb-markdown.ts";
+
+export interface ConfluenceKbAppendInput {
+  spaceKey: string;
+  parentPageId: string;
+  title: string;
+  bodyMarkdown: string;
+  citations: readonly KbCitation[];
+}
+
+/** Build the `POST /content` request body for a tribal-knowledge KB page under a parent. */
+export function buildConfluenceKbPageBody(input: ConfluenceKbAppendInput): Record<string, unknown> {
+  return {
+    type: "page",
+    title: input.title,
+    space: { key: input.spaceKey },
+    ancestors: [{ id: input.parentPageId }],
+    body: {
+      storage: {
+        value: markdownToConfluenceStorage(input.bodyMarkdown, input.citations),
+        representation: "storage",
+      },
+    },
+  };
+}