@nimbus-dev/connectors 0.2.1 → 0.2.2

package/connectors/argocd/src/server.ts

@@ -1,5 +1,12 @@
 import { z } from "zod";
 import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createJsonGetter,
+  createJsonPoster,
+  envAuthHeaders,
+  type JsonApiConfig,
+  requiredBaseUrl,
+} from "../../../shared/env-json-api.ts";
 import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
 import { fetchWithTimeout, mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
 import {
@@ -8,47 +15,24 @@ import {
 } 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" };
+  return `${requiredBaseUrl("ARGOCD_URL")}/api/v1`;
 }
 
-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;
-}
+/**
+ * One config for reads and the mutating requests alike. `fetchWithTimeout`, not the global
+ * fetch: this is a self-hosted control plane, and one that stops answering must fail the tool
+ * call rather than hang it.
+ */
+const api: JsonApiConfig = {
+  base: apiBase,
+  label: "ArgoCD",
+  headers: envAuthHeaders({ env: "ARGOCD_TOKEN" }),
+  fetch: fetchWithTimeout,
+};
 
-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);
-}
+const agGet = createJsonGetter(api);
+const agPost = createJsonPoster(api);
 
 function applicationsFrom(root: unknown): unknown[] {
   if (Array.isArray(root)) {
@@ -63,7 +47,10 @@ export function registerArgocdTools(reg: ZodToolRegistrar, server: unknown): voi
   // 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",
+    // NIMBUS_MCP_<SERVICE>_WRITE_SCOPE, as docs/configuration.md documents for every connector.
+    // This read NIMBUS_MCP_APP_WRITE_SCOPE (the scope KIND, not the service), so the documented
+    // variable was ignored and every argocd write refused as out of scope.
+    scopeEnv: "NIMBUS_MCP_ARGOCD_WRITE_SCOPE",
     scopeKinds: ["app"],
   });
 

package/connectors/athena/src/tools.ts

@@ -1,18 +1,20 @@
 import { z } from "zod";
+import {
+  asArray,
+  cliArg,
+  createCliJsonRunner,
+  isRecord,
+  strField,
+} from "../../../shared/cli-json-kit.ts";
 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
@@ -27,40 +29,19 @@ export const ATHENA_TOOL_NAMES = ["athena_list", "athena_get", "athena_search"]
 
 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);
-}
+const athenaCli = createCliJsonRunner(
+  {
+    argv: (args) => ["aws", "athena", ...args, "--output", "json"],
+    label: "aws athena",
+    emptyResult: {},
+  },
+  nimbusSpawn,
+);
 
 function catalogMatches(entry: unknown, q: string): boolean {
   if (!isRecord(entry)) {

package/connectors/aws/src/server.ts

@@ -1,191 +1,10 @@
-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 ?? {};
-}
+import { registerAwsTools } from "./tools.ts";
 
 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 });
-  },
-);
+registerAwsTools(mcp);
 
 const transport = new StdioServerTransport();
 await mcp.connect(transport);

package/connectors/aws/src/tools.ts

@@ -0,0 +1,197 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import type { ConsentServer } from "../../../shared/consent-kit.ts";
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
+import { runCliJsonThrowing, runCliOkThrowing } 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"];
+  return (await runCliJsonThrowing(cmd, awsEnv())) ?? {};
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const AWS_TOOL_NAMES = [
+  "aws_ecs_service_list",
+  "aws_lambda_list",
+  "aws_ecs_service_update",
+  "aws_lambda_invoke",
+  "aws_ec2_instance_stop",
+  "aws_ec2_instance_start",
+] as const;
+
+export function registerAwsTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+
+  /**
+   * 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(server, {
+    connector: "aws",
+    scopeEnv: "NIMBUS_MCP_AWS_WRITE_SCOPE",
+    scopeKinds: ["cluster", "function", "instance"],
+  });
+
+  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",
+      ];
+      await runCliOkThrowing(cmd, awsEnv());
+      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) => {
+      // The CLI reads the payload from a file and writes the response to one. Both are the
+      // caller's data, so the directory holding them is removed however the call ends — it used
+      // to be left in the temp dir on every invocation.
+      const dir = mkdtempSync(join(tmpdir(), "nimbus-aws-lambda-"));
+      try {
+        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,
+          ];
+          await runCliOkThrowing(cmd, awsEnv());
+        } else {
+          await runCliOkThrowing(
+            ["aws", "lambda", "invoke", "--function-name", p.functionName, outFile],
+            awsEnv(),
+          );
+        }
+        let body: unknown;
+        try {
+          body = JSON.parse(readFileSync(outFile, "utf8")) as unknown;
+        } catch {
+          body = { ok: true };
+        }
+        return jsonResult(body);
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    },
+  );
+
+  // The two EC2 actions are WRITES. They were registered as reads, which in standalone mode offered
+  // them to every client with no consent prompt, scope check, budget or audit record.
+  registerWriteTool(
+    "aws_ec2_instance_stop",
+    {
+      mutates: "aws.ec2.instance.stop",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "instance", value: p.instanceIds }),
+    },
+    "Stop EC2 instances.",
+    z.object({ instanceIds: z.string().min(1) }),
+    async (p) => {
+      await runCliOkThrowing(
+        ["aws", "ec2", "stop-instances", "--instance-ids", p.instanceIds],
+        awsEnv(),
+      );
+      return jsonResult({ ok: true });
+    },
+  );
+
+  registerWriteTool(
+    "aws_ec2_instance_start",
+    {
+      mutates: "aws.ec2.instance.start",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "instance", value: p.instanceIds }),
+    },
+    "Start EC2 instances.",
+    z.object({ instanceIds: z.string().min(1) }),
+    async (p) => {
+      await runCliOkThrowing(
+        ["aws", "ec2", "start-instances", "--instance-ids", p.instanceIds],
+        awsEnv(),
+      );
+      return jsonResult({ ok: true });
+    },
+  );
+}

package/connectors/azure/src/server.ts

@@ -1,139 +1,10 @@
 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 azEnv(): Record<string, string | undefined> {
-  return { ...process.env } as Record<string, string | undefined>;
-}
-
-async function azJson(args: string[]): Promise<unknown> {
-  const cmd = ["az", ...args, "-o", "json"];
-  const r = await runCliJson(cmd, azEnv());
-  if (!r.ok) {
-    throw new Error(r.message);
-  }
-  return r.data ?? {};
-}
+import { registerAzureTools } from "./tools.ts";
 
 const mcp = new McpServer({ name: "nimbus-azure", version: "0.1.0" });
 
-import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
-
-const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
-
-/**
- * Every MUTATING azure 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: "azure",
-  scopeEnv: "NIMBUS_MCP_AZURE_WRITE_SCOPE",
-  scopeKinds: ["resource_group"],
-});
-
-reg(
-  "azure_app_service_list",
-  "List App Services in a resource group.",
-  z.object({
-    subscriptionId: z.string().min(1),
-    resourceGroup: z.string().min(1),
-  }),
-  async (p) =>
-    jsonResult(
-      await azJson([
-        "webapp",
-        "list",
-        "--subscription",
-        p.subscriptionId,
-        "--resource-group",
-        p.resourceGroup,
-      ]),
-    ),
-);
-
-registerWriteTool(
-  "azure_app_service_restart",
-  {
-    mutates: "azure.app_service.restart",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "resource_group", value: p.resourceGroup }),
-  },
-  "Restart an App Service.",
-  z.object({
-    subscriptionId: z.string().min(1),
-    resourceGroup: z.string().min(1),
-    name: z.string().min(1),
-  }),
-  async (p) => {
-    const r = await runCliOk(
-      [
-        "az",
-        "webapp",
-        "restart",
-        "--subscription",
-        p.subscriptionId,
-        "--resource-group",
-        p.resourceGroup,
-        "--name",
-        p.name,
-      ],
-      azEnv(),
-    );
-    if (!r.ok) {
-      throw new Error(r.message);
-    }
-    return jsonResult({ ok: true });
-  },
-);
-
-registerWriteTool(
-  "azure_aks_node_pool_scale",
-  {
-    mutates: "azure.aks.node_pool.scale",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "resource_group", value: p.resourceGroup }),
-  },
-  "Scale an AKS node pool.",
-  z.object({
-    subscriptionId: z.string().min(1),
-    resourceGroup: z.string().min(1),
-    clusterName: z.string().min(1),
-    poolName: z.string().min(1),
-    nodeCount: z.number().int().min(0),
-  }),
-  async (p) => {
-    const r = await runCliOk(
-      [
-        "az",
-        "aks",
-        "nodepool",
-        "scale",
-        "--subscription",
-        p.subscriptionId,
-        "--resource-group",
-        p.resourceGroup,
-        "--cluster-name",
-        p.clusterName,
-        "--name",
-        p.poolName,
-        "--node-count",
-        String(p.nodeCount),
-      ],
-      azEnv(),
-    );
-    if (!r.ok) {
-      throw new Error(r.message);
-    }
-    return jsonResult({ ok: true });
-  },
-);
+registerAzureTools(mcp);
 
 const transport = new StdioServerTransport();
 await mcp.connect(transport);