@nimbus-dev/connectors 0.1.0

package/connectors/kubernetes/src/server.ts

@@ -0,0 +1,163 @@
+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 requireKubeconfigPath(): string {
+  const p = process.env["KUBECONFIG"]?.trim();
+  if (p === undefined || p === "") {
+    throw new Error("KUBECONFIG env must be set to a kubeconfig file path");
+  }
+  return p;
+}
+
+function kubectlBase(): string[] {
+  const args = ["kubectl"];
+  const ctx = process.env["KUBE_CONTEXT"]?.trim();
+  if (ctx !== undefined && ctx !== "") {
+    args.push("--context", ctx);
+  }
+  return args;
+}
+
+function kubeEnv(): Record<string, string | undefined> {
+  return { KUBECONFIG: requireKubeconfigPath() };
+}
+
+async function kubectlJson(rest: string[]): Promise<unknown> {
+  const cmd = [...kubectlBase(), ...rest, "-o", "json"];
+  const r = await runCliJson(cmd, kubeEnv());
+  if (!r.ok) {
+    throw new Error(r.message);
+  }
+  return r.data;
+}
+
+const optionalNamespaceSchema = z.object({ namespace: z.string().min(1).optional() });
+
+async function k8sListNamespacedResource(p: { namespace?: string | undefined }, resource: string) {
+  const ns = p.namespace ?? "default";
+  const data = await kubectlJson(["get", resource, "-n", ns]);
+  return jsonResult(data ?? {});
+}
+
+const mcp = new McpServer({ name: "nimbus-kubernetes", version: "0.1.0" });
+
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+
+const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
+
+/**
+ * Every MUTATING kubernetes 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: "kubernetes",
+  scopeEnv: "NIMBUS_MCP_KUBERNETES_WRITE_SCOPE",
+  scopeKinds: ["namespace"],
+});
+
+reg(
+  "k8s_pod_list",
+  "List pods in a namespace (default namespace: default).",
+  optionalNamespaceSchema,
+  (p) => k8sListNamespacedResource(p, "pods"),
+);
+
+reg("k8s_deployment_list", "List deployments in a namespace.", optionalNamespaceSchema, (p) =>
+  k8sListNamespacedResource(p, "deployments"),
+);
+
+reg("k8s_event_list", "List events in a namespace.", optionalNamespaceSchema, (p) =>
+  k8sListNamespacedResource(p, "events"),
+);
+
+registerWriteTool(
+  "k8s_rollout_restart",
+  {
+    mutates: "kubernetes.rollout.restart",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "namespace", value: p.namespace ?? "default" }),
+  },
+  "Restart a rollout (e.g. deployment).",
+  z.object({
+    namespace: z.string().min(1).optional(),
+    resourceType: z.string().min(1),
+    name: z.string().min(1),
+  }),
+  async (p) => {
+    const ns = p.namespace ?? "default";
+    const cmd = [...kubectlBase(), "rollout", "restart", p.resourceType, p.name, "-n", ns];
+    const r = await runCliOk(cmd, kubeEnv());
+    if (!r.ok) {
+      throw new Error(r.message);
+    }
+    return jsonResult({ ok: true });
+  },
+);
+
+registerWriteTool(
+  "k8s_pod_delete",
+  {
+    mutates: "kubernetes.pod.delete",
+    // A deleted pod is not restorable; its identity is all that remains to record.
+    recoverable: false,
+    capturePreState: (p) => Promise.resolve({ namespace: p.namespace, podName: p.podName }),
+    scopeTargetOf: (p) => ({ kind: "namespace", value: p.namespace ?? "default" }),
+  },
+  "Delete a pod.",
+  z.object({
+    namespace: z.string().min(1).optional(),
+    podName: z.string().min(1),
+  }),
+  async (p) => {
+    const ns = p.namespace ?? "default";
+    const cmd = [...kubectlBase(), "delete", "pod", p.podName, "-n", ns];
+    const r = await runCliOk(cmd, kubeEnv());
+    if (!r.ok) {
+      throw new Error(r.message);
+    }
+    return jsonResult({ ok: true });
+  },
+);
+
+registerWriteTool(
+  "k8s_deployment_scale",
+  {
+    mutates: "kubernetes.deployment.scale",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "namespace", value: p.namespace ?? "default" }),
+  },
+  "Scale a deployment.",
+  z.object({
+    namespace: z.string().min(1).optional(),
+    deploymentName: z.string().min(1),
+    replicas: z.number().int().min(0),
+  }),
+  async (p) => {
+    const ns = p.namespace ?? "default";
+    const cmd = [
+      ...kubectlBase(),
+      "scale",
+      "deployment",
+      p.deploymentName,
+      `-n`,
+      ns,
+      `--replicas=${String(p.replicas)}`,
+    ];
+    const r = await runCliOk(cmd, kubeEnv());
+    if (!r.ok) {
+      throw new Error(r.message);
+    }
+    return jsonResult({ ok: true });
+  },
+);
+
+const transport = new StdioServerTransport();
+await mcp.connect(transport);

package/connectors/launchdarkly/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.launchdarkly",
+  "displayName": "LaunchDarkly",
+  "version": "0.1.0",
+  "description": "LaunchDarkly feature-flag connector (read-only). Surfaces flag key, name, kind, tags, per-environment on/off state, maintainer, and timestamps into the local index as `launchdarkly:feature_flag` items — useful for incident correlation (\"was this flag enabled when the alert fired?\"). API-token auth. Regional / federal instances override `launchdarkly.base_url`; the SaaS host (app.launchdarkly.com) is the only one in the static sandbox manifest today (Task 14 runtime-merge follow-up). The `launchdarkly.flag.toggle` write tool is a deferred Phase 8 follow-up.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["app.launchdarkly.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

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

package/connectors/launchdarkly/src/server.ts

@@ -0,0 +1,79 @@
+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 { filterLaunchDarklyFlags } from "./search-filter.ts";
+
+const DEFAULT_BASE = "https://app.launchdarkly.com";
+
+function baseUrl(): string {
+  const v = process.env["LAUNCHDARKLY_BASE_URL"]?.trim();
+  return v === undefined || v === "" ? DEFAULT_BASE : v;
+}
+
+function authHeader(): Record<string, string> {
+  const t = process.env["LAUNCHDARKLY_TOKEN"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("LAUNCHDARKLY_TOKEN is not set");
+  }
+  return { Authorization: t, Accept: "application/json" };
+}
+
+async function ldGet(path: string): Promise<unknown> {
+  const res = await fetch(`${baseUrl()}/api/v2${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`LaunchDarkly ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+await runReadOnlyMcpConnector("nimbus-launchdarkly", (reg) => {
+  reg(
+    "launchdarkly_list",
+    "List LaunchDarkly projects, or feature flags for a project. Without `projectKey`, returns the account's projects (`/projects`). With `projectKey`, returns that project's flags (`/flags/{projectKey}`), capped at `limit` (default 100).",
+    z.object({
+      projectKey: z.string().min(1).optional(),
+      limit: z.number().int().min(1).max(500).optional(),
+    }),
+    async (p) => {
+      if (p.projectKey === undefined) {
+        return jsonResult(await ldGet("/projects"));
+      }
+      const search = new URLSearchParams({ summary: "true", limit: String(p.limit ?? 100) });
+      return jsonResult(
+        await ldGet(`/flags/${encodeURIComponent(p.projectKey)}?${search.toString()}`),
+      );
+    },
+  );
+
+  reg(
+    "launchdarkly_get",
+    "Fetch one LaunchDarkly feature flag by project key + flag key. Throws when no match is found.",
+    z.object({
+      projectKey: z.string().min(1),
+      flagKey: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(
+        await ldGet(`/flags/${encodeURIComponent(p.projectKey)}/${encodeURIComponent(p.flagKey)}`),
+      );
+    },
+  );
+
+  reg(
+    "launchdarkly_search",
+    "Substring search across a project's feature flags. Matches the query against flag key, name, description, and tags (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    z.object({
+      projectKey: z.string().min(1),
+      query: z.string().min(1),
+      limit: z.number().int().min(1).max(200).optional(),
+    }),
+    async (p) => {
+      const search = new URLSearchParams({ summary: "true", limit: "500" });
+      const root = await ldGet(`/flags/${encodeURIComponent(p.projectKey)}?${search.toString()}`);
+      const flags = (root as { items?: unknown[] } | null)?.items;
+      return matchesResult(flags, filterLaunchDarklyFlags, p);
+    },
+  );
+});

package/connectors/lever/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.lever",
+  "displayName": "Lever",
+  "version": "0.1.0",
+  "description": "Lever connector (read-only). Surfaces the company's published Lever job postings as `lever:posting` items in the local index — the posting title, the team/department/location/commitment/level categories, the workflow state, tags, the hosted job-page URL and apply URL, and the requisition code. Useful for answering recruiting questions (\"which backend roles are open?\", \"find the posting for the staff SRE position\") without leaving Nimbus. HTTP Basic auth where the Lever API key is the username and the password is empty (`Authorization: Basic base64(<api_key>:)` — the trailing colon is the empty password; never logged). The SaaS host (api.lever.co) is fixed. Lever paginates `/v1/postings` with a `hasNext` flag plus a `next` offset cursor, returning the `{ data, hasNext, next }` envelope. `createdAt` / `updatedAt` are epoch MILLISECONDS (passed through verbatim on index — NO parse, NO ×1000). Opportunities / candidates are deliberately deferred (candidate PII; out of scope for v1) — v1 indexes job postings only.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.lever.co"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,35 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+  tagText,
+} from "../../../shared/search-filter.ts";
+
+export type LeverSearchMatchOptions = SearchMatchOptions;
+
+function categoryField(row: Record<string, unknown>, key: string): string {
+  const cats = row["categories"];
+  if (cats === null || typeof cats !== "object" || Array.isArray(cats)) {
+    return "";
+  }
+  const v = (cats as Record<string, unknown>)[key];
+  return typeof v === "string" ? v : "";
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [
+    stringField(row, "text"),
+    stringField(row, "state"),
+    categoryField(row, "team"),
+    categoryField(row, "department"),
+    categoryField(row, "location"),
+    tagText(row),
+  ];
+}
+
+export const filterLeverPostings = makeQueryFilter(fieldsOf);

package/connectors/lever/src/server.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { matchesResult, searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
+import {
+  encodeBasicAuthHeader,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
+import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterLeverPostings } from "./search-filter.ts";
+
+const BASE = "https://api.lever.co";
+
+function apiKey(): string {
+  const t = process.env["LEVER_API_KEY"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("LEVER_API_KEY is not set");
+  }
+  return t;
+}
+
+function authHeader(): Record<string, string> {
+  return { Authorization: encodeBasicAuthHeader(apiKey(), ""), Accept: "application/json" };
+}
+
+async function leverGet(path: string): Promise<unknown> {
+  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Lever ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+await runReadOnlyMcpConnector("nimbus-lever", (reg) => {
+  reg(
+    "lever_list",
+    "List the company's published Lever job postings (`GET /v1/postings?limit=100`). Returns the offset-cursor envelope `{ data: [...], hasNext: boolean, next?: string }` — `data` holds the posting objects.",
+    z.object({}),
+    async () => {
+      return jsonResult(await leverGet(`/v1/postings?limit=100`));
+    },
+  );
+
+  reg(
+    "lever_get",
+    "Fetch one Lever job posting by its id (`GET /v1/postings/{id}`). Returns the `{ data: {...} }` envelope. Throws when no match is found.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await leverGet(`/v1/postings/${encodeURIComponent(p.id)}`));
+    },
+  );
+
+  reg(
+    "lever_search",
+    "Substring search across the company's Lever job postings (first page only). Matches the query against the posting text (title), state, and the team/department/location categories and tags (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const root = await leverGet(`/v1/postings?limit=100`);
+      const data = (root as { data?: unknown[] } | null)?.data;
+      return matchesResult(data, filterLeverPostings, p);
+    },
+  );
+});

package/connectors/linear/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.linear",
+  "displayName": "Linear",
+  "version": "0.1.0",
+  "description": "Linear GraphQL connector (issues, projects, cycles). Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.linear.app"]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 300,
+  "minNimbusVersion": "0.2.0"
+}