@nimbus-dev/connectors 0.1.0

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

@@ -0,0 +1,24 @@
+import {
+  asRecord,
+  makeQueryFilter,
+  nestedString,
+  type SearchMatchOptions,
+} from "../../../shared/search-filter.ts";
+
+export type ArgocdSearchMatchOptions = SearchMatchOptions;
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asRecord(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [
+    nestedString(row, ["metadata", "name"]),
+    nestedString(row, ["spec", "project"]),
+    nestedString(row, ["spec", "source", "repoURL"]),
+    nestedString(row, ["status", "sync", "status"]),
+    nestedString(row, ["status", "health", "status"]),
+  ];
+}
+
+export const filterArgocdApplications = makeQueryFilter(fieldsOf);

package/connectors/argocd/src/server.ts

@@ -0,0 +1,158 @@
+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 { filterArgocdApplications } from "./search-filter.ts";
+
+function trimTrailingSlash(s: string): string {
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+
+function apiBase(): string {
+  const v = process.env["ARGOCD_URL"]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error("ARGOCD_URL is not set");
+  }
+  return `${trimTrailingSlash(v)}/api/v1`;
+}
+
+function authHeader(): Record<string, string> {
+  const t = process.env["ARGOCD_TOKEN"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("ARGOCD_TOKEN is not set");
+  }
+  return { Authorization: `Bearer ${t}`, Accept: "application/json" };
+}
+
+async function agGet(path: string): Promise<unknown> {
+  const res = await fetchWithTimeout(`${apiBase()}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`ArgoCD ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+async function agPost(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(`ArgoCD ${path} ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return text === "" ? {} : (JSON.parse(text) as unknown);
+}
+
+function applicationsFrom(root: unknown): unknown[] {
+  if (Array.isArray(root)) {
+    return root;
+  }
+  const items = (root as { items?: unknown } | null)?.items;
+  return Array.isArray(items) ? items : [];
+}
+
+export function registerArgocdTools(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: "argocd",
+    scopeEnv: "NIMBUS_MCP_APP_WRITE_SCOPE",
+    scopeKinds: ["app"],
+  });
+
+  reg(
+    "argocd_list",
+    "List ArgoCD applications. Optionally filter by `project` (passes `?projects=<project>` to the API). ArgoCD returns the full list in one response; `limit` (default 200) caps the returned `items` client-side.",
+    z.object({
+      project: z.string().optional(),
+      limit: z.number().int().min(1).max(500).optional(),
+    }),
+    async (p) => {
+      const search = new URLSearchParams();
+      if (p.project !== undefined && p.project !== "") {
+        search.set("projects", p.project);
+      }
+      const qs = search.toString();
+      const queryPart = qs === "" ? "" : `?${qs}`;
+      const root = await agGet(`/applications${queryPart}`);
+      const apps = applicationsFrom(root);
+      const cap = p.limit ?? 200;
+      return jsonResult({ items: apps.slice(0, cap) });
+    },
+  );
+
+  reg(
+    "argocd_get",
+    "Fetch one ArgoCD application by name (`/applications/{name}`). Throws when no application with that name exists.",
+    z.object({
+      name: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await agGet(`/applications/${encodeURIComponent(p.name)}`));
+    },
+  );
+
+  reg(
+    "argocd_search",
+    "Substring search across ArgoCD applications. Matches the query (case-insensitive) against application name, project, source repo URL, sync status, and health status. Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(200),
+    async (p) => {
+      const root = await agGet("/applications");
+      const matches = filterArgocdApplications(applicationsFrom(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+
+  registerWriteTool(
+    "argocd_app_sync",
+    {
+      mutates: "argocd.app.sync",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "app", value: p.name }),
+    },
+    "Trigger a sync for an ArgoCD application (`POST /api/v1/applications/{name}/sync`, requires HITL argocd.app.sync). Async — the sync is requested; verify via the next metadata sync (sync_status/health_status). Recommend /schedule to re-check.",
+    z.object({
+      name: z.string().min(1),
+      prune: z.boolean().optional(),
+      revision: z.string().optional(),
+    }),
+    async (p) => {
+      await agPost(`/applications/${encodeURIComponent(p.name)}/sync`, {
+        ...(p.prune === undefined ? {} : { prune: p.prune }),
+        ...(p.revision === undefined ? {} : { revision: p.revision }),
+      });
+      return jsonResult({ status: "requested", name: p.name });
+    },
+  );
+
+  registerWriteTool(
+    "argocd_app_rollback",
+    {
+      mutates: "argocd.app.rollback",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "app", value: p.name }),
+    },
+    "Roll back an ArgoCD application to a prior deployment history id (`POST /api/v1/applications/{name}/rollback`, requires HITL argocd.app.rollback). Async — verify via the next metadata sync.",
+    z.object({ name: z.string().min(1), id: z.number().int().nonnegative() }),
+    async (p) => {
+      await agPost(`/applications/${encodeURIComponent(p.name)}/rollback`, { id: p.id });
+      return jsonResult({ status: "requested", name: p.name });
+    },
+  );
+}
+
+export async function startConnector(): Promise<void> {
+  await runReadOnlyMcpConnector("nimbus-argocd", registerArgocdTools);
+}
+
+if (import.meta.main) await startConnector();

package/connectors/athena/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.athena",
+  "displayName": "Amazon Athena",
+  "version": "0.1.0",
+  "description": "Amazon Athena metadata connector (Tier-3, no-row-data). Indexes data catalogs, databases, and table metadata — table names, types, column names/types, partition keys, parameters, and timestamps — via the AWS CLI's Athena metadata commands. Never runs a query or fetches row, cell, or query-result data. 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/athena/src/server.ts

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

package/connectors/athena/src/tools.ts

@@ -0,0 +1,181 @@
+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 catalog / database / table name passed as a value to the `aws athena` 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 Athena (Tier-3, metadata-only) MCP tool surface. ALL tools index
+ * catalog / database / TABLE-metadata only (data catalogs, databases, table
+ * names, table types, column names + types, partition keys, parameters,
+ * timestamps). NONE fetch row / cell / query-result data — there is NO
+ * `start-query-execution`, NO `get-query-results`, NO `get-query-execution`.
+ * The names are introspected by the `assertNoRowDataTools` contract test, so
+ * they must never contain a row-data segment (query/rows/results/scan/…).
+ */
+export const ATHENA_TOOL_NAMES = ["athena_list", "athena_get", "athena_search"] as const;
+
+const PAGE = "200";
+
+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 athena <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 athenaCli(args: string[]): Promise<unknown> {
+  const { code, stdout, stderr } = await nimbusSpawn(
+    ["aws", "athena", ...args, "--output", "json"],
+    {},
+  );
+  const out = stdout.trim();
+  const err = stderr.trim();
+  if (code !== 0) {
+    throw new Error(`aws athena ${args[0] ?? ""} failed: ${err.slice(0, 400)}`);
+  }
+  return out === "" ? {} : (JSON.parse(out) as unknown);
+}
+
+function catalogMatches(entry: unknown, q: string): boolean {
+  if (!isRecord(entry)) {
+    return false;
+  }
+  return strField(entry, "CatalogName").toLowerCase().includes(q.toLowerCase());
+}
+
+function nameMatches(entry: unknown, q: string): boolean {
+  if (!isRecord(entry)) {
+    return false;
+  }
+  return strField(entry, "Name").toLowerCase().includes(q.toLowerCase());
+}
+
+// Databases and tables are both matched on their `Name` field.
+const databaseMatches = nameMatches;
+const tableMatches = nameMatches;
+
+/**
+ * Register the read-only, metadata-only Athena tools onto the given registrar.
+ * Shared between `server.ts` (live) and the contract test (introspection).
+ */
+export function registerAthenaTools(reg: ZodToolRegistrar): void {
+  reg(
+    "athena_list",
+    "List Athena data catalogs, the databases in a catalog, or the tables in a database — METADATA ONLY. With no arguments, lists data catalogs (`aws athena list-data-catalogs`). With `catalog` set, lists that catalog's databases (`aws athena list-databases`). With `catalog` + `database` set, lists that database's table metadata (`aws athena list-table-metadata`) — each entry carries `Name`, `TableType`, `Columns`, and `PartitionKeys`. Never runs a query or returns row/cell data.",
+    z.object({
+      catalog: cliArg.optional(),
+      database: cliArg.optional(),
+    }),
+    async (p) => {
+      if (p.catalog === undefined) {
+        return jsonResult(await athenaCli(["list-data-catalogs", "--max-results", PAGE]));
+      }
+      if (p.database === undefined) {
+        return jsonResult(
+          await athenaCli(["list-databases", "--catalog-name", p.catalog, "--max-results", PAGE]),
+        );
+      }
+      return jsonResult(
+        await athenaCli([
+          "list-table-metadata",
+          "--catalog-name",
+          p.catalog,
+          "--database-name",
+          p.database,
+          "--max-results",
+          PAGE,
+        ]),
+      );
+    },
+  );
+
+  reg(
+    "athena_get",
+    "Fetch one Athena table's schema + METADATA (`aws athena get-table-metadata`). Returns the table object including `Columns` (column names + types only), `PartitionKeys`, `TableType`, `Parameters`, and timestamps. No cell values or query results are returned — schema/metadata only.",
+    z.object({
+      catalog: cliArg,
+      database: cliArg,
+      table: cliArg,
+    }),
+    async (p) => {
+      return jsonResult(
+        await athenaCli([
+          "get-table-metadata",
+          "--catalog-name",
+          p.catalog,
+          "--database-name",
+          p.database,
+          "--table-name",
+          p.table,
+        ]),
+      );
+    },
+  );
+
+  reg(
+    "athena_search",
+    "Substring search over Athena catalog, database, and table NAMES (case-insensitive) — METADATA ONLY. With no `catalog`, searches data-catalog names. With `catalog` set (no `database`), searches that catalog's database names. With `catalog` + `database` set, searches that database's table names. Returns a `{ matches: [...] }` envelope of metadata entries. Never runs a query or samples row data.",
+    z.object({
+      catalog: cliArg.optional(),
+      database: cliArg.optional(),
+      query: z.string().min(1),
+    }),
+    async (p) => {
+      if (p.catalog === undefined) {
+        const root = await athenaCli(["list-data-catalogs", "--max-results", PAGE]);
+        const matches = asArray(root, "DataCatalogsSummary").filter((c) =>
+          catalogMatches(c, p.query),
+        );
+        return jsonResult({ matches });
+      }
+      if (p.database === undefined) {
+        const root = await athenaCli([
+          "list-databases",
+          "--catalog-name",
+          p.catalog,
+          "--max-results",
+          PAGE,
+        ]);
+        const matches = asArray(root, "DatabaseList").filter((d) => databaseMatches(d, p.query));
+        return jsonResult({ matches });
+      }
+      const root = await athenaCli([
+        "list-table-metadata",
+        "--catalog-name",
+        p.catalog,
+        "--database-name",
+        p.database,
+        "--max-results",
+        PAGE,
+      ]);
+      const matches = asArray(root, "TableMetadataList").filter((t) => tableMatches(t, p.query));
+      return jsonResult({ matches });
+    },
+  );
+}

package/connectors/aws/nimbus.extension.json

@@ -0,0 +1,21 @@
+{
+  "id": "com.nimbus.aws",
+  "displayName": "AWS",
+  "version": "0.1.0",
+  "description": "AWS CLI connector (region-agnostic control plane). Non-default regions / data-plane hosts are a known Task 14 follow-up. Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": [
+      "sts.amazonaws.com",
+      "iam.amazonaws.com",
+      "s3.amazonaws.com",
+      "ec2.amazonaws.com",
+      "cloudfront.amazonaws.com"
+    ]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/aws/src/server.ts

@@ -0,0 +1,191 @@
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+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 awsEnv(): Record<string, string | undefined> {
+  const e = { ...process.env } as Record<string, string | undefined>;
+  const ak = process.env["AWS_ACCESS_KEY_ID"]?.trim();
+  const sk = process.env["AWS_SECRET_ACCESS_KEY"]?.trim();
+  const rg = process.env["AWS_DEFAULT_REGION"]?.trim();
+  const profile = process.env["AWS_PROFILE"]?.trim();
+  if (ak !== undefined && ak !== "") {
+    e["AWS_ACCESS_KEY_ID"] = ak;
+  }
+  if (sk !== undefined && sk !== "") {
+    e["AWS_SECRET_ACCESS_KEY"] = sk;
+  }
+  if (rg !== undefined && rg !== "") {
+    e["AWS_DEFAULT_REGION"] = rg;
+  }
+  if (profile !== undefined && profile !== "") {
+    e["AWS_PROFILE"] = profile;
+  }
+  return e;
+}
+
+async function awsJson(args: string[]): Promise<unknown> {
+  const cmd = ["aws", ...args, "--output", "json"];
+  const r = await runCliJson(cmd, awsEnv());
+  if (!r.ok) {
+    throw new Error(r.message);
+  }
+  return r.data ?? {};
+}
+
+const mcp = new McpServer({ name: "nimbus-aws", version: "0.1.0" });
+
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+
+const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
+
+/**
+ * Every MUTATING aws 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: "aws",
+  scopeEnv: "NIMBUS_MCP_AWS_WRITE_SCOPE",
+  scopeKinds: ["cluster", "function"],
+});
+
+reg(
+  "aws_ecs_service_list",
+  "List ECS services in a cluster.",
+  z.object({ cluster: z.string().min(1) }),
+  async (p) => jsonResult(await awsJson(["ecs", "list-services", "--cluster", p.cluster])),
+);
+
+reg("aws_lambda_list", "List Lambda functions (first page).", z.object({}), async () =>
+  jsonResult(await awsJson(["lambda", "list-functions"])),
+);
+
+registerWriteTool(
+  "aws_ecs_service_update",
+  {
+    mutates: "aws.ecs.service.update",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "cluster", value: p.cluster }),
+  },
+  "Update ECS service (e.g. new task definition).",
+  z.object({
+    cluster: z.string().min(1),
+    service: z.string().min(1),
+    taskDefinition: z.string().min(1),
+  }),
+  async (p) => {
+    const cmd = [
+      "aws",
+      "ecs",
+      "update-service",
+      "--cluster",
+      p.cluster,
+      "--service",
+      p.service,
+      "--task-definition",
+      p.taskDefinition,
+      "--force-new-deployment",
+    ];
+    const r = await runCliOk(cmd, awsEnv());
+    if (!r.ok) {
+      throw new Error(r.message);
+    }
+    return jsonResult({ ok: true });
+  },
+);
+
+registerWriteTool(
+  "aws_lambda_invoke",
+  {
+    mutates: "aws.lambda.invoke",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "function", value: p.functionName }),
+  },
+  "Invoke a Lambda function.",
+  z.object({
+    functionName: z.string().min(1),
+    payloadJson: z.string().optional(),
+  }),
+  async (p) => {
+    const dir = mkdtempSync(join(tmpdir(), "nimbus-aws-lambda-"));
+    const outFile = join(dir, "response.json");
+    if (p.payloadJson !== undefined && p.payloadJson !== "") {
+      const pf = join(dir, "payload.json");
+      writeFileSync(pf, p.payloadJson, "utf8");
+      const cmd = [
+        "aws",
+        "lambda",
+        "invoke",
+        "--function-name",
+        p.functionName,
+        "--payload",
+        `file://${pf}`,
+        outFile,
+      ];
+      const r = await runCliOk(cmd, awsEnv());
+      if (!r.ok) {
+        throw new Error(r.message);
+      }
+    } else {
+      const r = await runCliOk(
+        ["aws", "lambda", "invoke", "--function-name", p.functionName, outFile],
+        awsEnv(),
+      );
+      if (!r.ok) {
+        throw new Error(r.message);
+      }
+    }
+    let body: unknown;
+    try {
+      body = JSON.parse(readFileSync(outFile, "utf8")) as unknown;
+    } catch {
+      body = { ok: true };
+    }
+    return jsonResult(body);
+  },
+);
+
+reg(
+  "aws_ec2_instance_stop",
+  "Stop EC2 instances. HITL.",
+  z.object({ instanceIds: z.string().min(1) }),
+  async (p) => {
+    const r = await runCliOk(
+      ["aws", "ec2", "stop-instances", "--instance-ids", p.instanceIds],
+      awsEnv(),
+    );
+    if (!r.ok) {
+      throw new Error(r.message);
+    }
+    return jsonResult({ ok: true });
+  },
+);
+
+reg(
+  "aws_ec2_instance_start",
+  "Start EC2 instances. HITL.",
+  z.object({ instanceIds: z.string().min(1) }),
+  async (p) => {
+    const r = await runCliOk(
+      ["aws", "ec2", "start-instances", "--instance-ids", p.instanceIds],
+      awsEnv(),
+    );
+    if (!r.ok) {
+      throw new Error(r.message);
+    }
+    return jsonResult({ ok: true });
+  },
+);
+
+const transport = new StdioServerTransport();
+await mcp.connect(transport);

package/connectors/azure/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.azure",
+  "displayName": "Azure",
+  "version": "0.1.0",
+  "description": "Azure CLI connector (ARM control plane + AAD OAuth). Data-plane hostnames are a known Task 14 follow-up. Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["management.azure.com", "login.microsoftonline.com"]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}