@nimbus-dev/connectors 0.2.0 → 0.2.2

package/connectors/azure/src/tools.ts

@@ -0,0 +1,133 @@
+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 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"];
+  return (await runCliJsonThrowing(cmd, azEnv())) ?? {};
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const AZURE_TOOL_NAMES = [
+  "azure_app_service_list",
+  "azure_app_service_restart",
+  "azure_aks_node_pool_scale",
+] as const;
+
+export function registerAzureTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+
+  /**
+   * 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(server, {
+    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) => {
+      await runCliOkThrowing(
+        [
+          "az",
+          "webapp",
+          "restart",
+          "--subscription",
+          p.subscriptionId,
+          "--resource-group",
+          p.resourceGroup,
+          "--name",
+          p.name,
+        ],
+        azEnv(),
+      );
+      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) => {
+      await runCliOkThrowing(
+        [
+          "az",
+          "aks",
+          "nodepool",
+          "scale",
+          "--subscription",
+          p.subscriptionId,
+          "--resource-group",
+          p.resourceGroup,
+          "--cluster-name",
+          p.clusterName,
+          "--name",
+          p.poolName,
+          "--node-count",
+          String(p.nodeCount),
+        ],
+        azEnv(),
+      );
+      return jsonResult({ ok: true });
+    },
+  );
+}

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

@@ -1,22 +1,11 @@
 import {
-  asRecord,
   makeQueryFilter,
+  recordFieldsFromKeys,
   type SearchMatchOptions,
 } from "../../../shared/search-filter.ts";
 
 export type BigeyeSearchMatchOptions = SearchMatchOptions;
 
-function stringAt(row: Record<string, unknown>, key: string): string {
-  const v = row[key];
-  return typeof v === "string" ? v : "";
-}
-
-function fieldsOf(item: unknown): readonly string[] | null {
-  const row = asRecord(item);
-  if (row === undefined) {
-    return null;
-  }
-  return [stringAt(row, "summary"), stringAt(row, "title"), stringAt(row, "description")];
-}
-
-export const filterBigeyeIssues = makeQueryFilter(fieldsOf);
+export const filterBigeyeIssues = makeQueryFilter(
+  recordFieldsFromKeys(["summary", "title", "description"]),
+);

package/connectors/bigeye/src/server.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { cursorListInputSchema } from "../../../shared/cursor-list-tool.ts";
+import { envAuthHeaders, requiredEnv } 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,21 +10,13 @@ import {
 } from "../../../shared/run-read-only-mcp-connector.ts";
 import { filterBigeyeIssues } from "./search-filter.ts";
 
+/** Only ONE trailing slash is dropped here — not `requiredBaseUrl`'s strip-them-all. */
 function apiBase(): string {
-  const v = process.env["BIGEYE_BASE_URL"]?.trim();
-  if (v === undefined || v === "") {
-    throw new Error("BIGEYE_BASE_URL is not set");
-  }
+  const v = requiredEnv("BIGEYE_BASE_URL");
   return v.endsWith("/") ? v.slice(0, -1) : v;
 }
 
-function authHeader(): Record<string, string> {
-  const k = process.env["BIGEYE_API_KEY"]?.trim();
-  if (k === undefined || k === "") {
-    throw new Error("BIGEYE_API_KEY is not set");
-  }
-  return { Authorization: `Bearer ${k}`, Accept: "application/json" };
-}
+const authHeader = envAuthHeaders({ env: "BIGEYE_API_KEY" });
 
 /** One page of issues (`GET /api/v1/issues?limit&offset`), tolerant of array / `{issues}` / `{data}`. */
 async function fetchIssues(limit: number, offset: number): Promise<unknown[]> {
@@ -80,10 +74,7 @@ export function registerBigeyeTools(reg: ZodToolRegistrar, server: unknown): voi
   reg(
     "bigeye_list",
     "List Bigeye data-quality issues (`GET /api/v1/issues`). Paginated: `cursor` (offset) + `limit` (default 200, max 500) → `{ items, nextCursor }`.",
-    z.object({
-      cursor: z.string().nullable().optional(),
-      limit: z.number().int().min(1).max(500).optional(),
-    }),
+    cursorListInputSchema(),
     async (p) => {
       const limit = p.limit ?? 200;
       // null / undefined / "" / non-numeric / negative all clamp to offset 0; fractional truncates.
@@ -121,34 +112,43 @@ export function registerBigeyeTools(reg: ZodToolRegistrar, server: unknown): voi
     },
   );
 
-  registerWriteTool(
+  /**
+   * Acknowledge and resolve are ONE mutation, `updateIssueStatus`, with a different status, so
+   * they share everything except their name, action type, description and that status.
+   */
+  function registerStatusTool(
+    name: string,
+    mutates: string,
+    description: string,
+    status: "ISSUE_STATUS_ACKNOWLEDGED" | "ISSUE_STATUS_CLOSED",
+  ): void {
+    registerWriteTool(
+      name,
+      {
+        mutates,
+        recoverable: true,
+        scopeTargetOf: (p) => ({ kind: "issue", value: p.issueId }),
+      },
+      description,
+      z.object({ issueId: z.string().min(1) }),
+      async (p) => {
+        await updateIssueStatus(p.issueId, status);
+        return jsonResult({ status: "ok", issueId: p.issueId });
+      },
+    );
+  }
+
+  registerStatusTool(
     "bigeye_issue_acknowledge",
-    {
-      mutates: "bigeye.issue.acknowledge",
-      recoverable: true,
-      scopeTargetOf: (p) => ({ kind: "issue", value: p.issueId }),
-    },
+    "bigeye.issue.acknowledge",
     "Acknowledge a Bigeye issue.",
-    z.object({ issueId: z.string().min(1) }),
-    async (p) => {
-      await updateIssueStatus(p.issueId, "ISSUE_STATUS_ACKNOWLEDGED");
-      return jsonResult({ status: "ok", issueId: p.issueId });
-    },
+    "ISSUE_STATUS_ACKNOWLEDGED",
   );
-
-  registerWriteTool(
+  registerStatusTool(
     "bigeye_issue_resolve",
-    {
-      mutates: "bigeye.issue.resolve",
-      recoverable: true,
-      scopeTargetOf: (p) => ({ kind: "issue", value: p.issueId }),
-    },
+    "bigeye.issue.resolve",
     "Resolve (close) a Bigeye issue.",
-    z.object({ issueId: z.string().min(1) }),
-    async (p) => {
-      await updateIssueStatus(p.issueId, "ISSUE_STATUS_CLOSED");
-      return jsonResult({ status: "ok", issueId: p.issueId });
-    },
+    "ISSUE_STATUS_CLOSED",
   );
 }
 

package/connectors/bigquery/src/tools.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { asArray, gcloudEnv, 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";
@@ -23,15 +24,6 @@ function project(explicit?: string): string {
   return p;
 }
 
-function gcloudEnv(): Record<string, string | undefined> {
-  const e = { ...process.env } as Record<string, string | undefined>;
-  const cf = process.env["GOOGLE_APPLICATION_CREDENTIALS"]?.trim();
-  if (cf !== undefined && cf !== "") {
-    e["GOOGLE_APPLICATION_CREDENTIALS"] = cf;
-  }
-  return e;
-}
-
 /** Mint a short-lived access token via `gcloud auth print-access-token`. */
 async function accessToken(): Promise<string> {
   const { code, stdout, stderr } = await nimbusSpawn(
@@ -58,15 +50,6 @@ async function bqGet(token: string, path: string): Promise<unknown> {
   return JSON.parse(text) as unknown;
 }
 
-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 tableMatches(entry: unknown, q: string): boolean {
   if (!isRecord(entry)) {
     return false;
@@ -88,14 +71,6 @@ function datasetMatches(entry: unknown, q: string): boolean {
   return datasetId.toLowerCase().includes(q.toLowerCase());
 }
 
-function asArray(parsed: unknown, key: string): unknown[] {
-  if (!isRecord(parsed)) {
-    return [];
-  }
-  const arr = parsed[key];
-  return Array.isArray(arr) ? arr : [];
-}
-
 /**
  * Register the read-only, metadata-only BigQuery tools onto the given registrar.
  * Shared between `server.ts` (live) and the contract test (introspection).

package/connectors/bitbucket/src/server.ts

@@ -1,252 +1,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
-import { joinApiPath } from "../../../shared/join-api-path.ts";
-import {
-  createRegisterSimpleTool,
-  createZodToolRegistrar,
-  mcpJsonResultIfOk,
-} from "../../../shared/mcp-tool-kit.ts";
-
-const BB_API = "https://api.bitbucket.org/2.0";
-
-function requireUsername(): string {
-  const t = process.env["BITBUCKET_USERNAME"];
-  if (t === undefined || t === "") {
-    throw new Error("BITBUCKET_USERNAME is not set");
-  }
-  return t;
-}
-
-function requireAppPassword(): string {
-  const t = process.env["BITBUCKET_APP_PASSWORD"];
-  if (t === undefined || t === "") {
-    throw new Error("BITBUCKET_APP_PASSWORD is not set");
-  }
-  return t;
-}
-
-function basicAuthHeader(): string {
-  const user = requireUsername();
-  const pass = requireAppPassword();
-  const b = Buffer.from(`${user}:${pass}`, "utf8").toString("base64");
-  return `Basic ${b}`;
-}
-
-function splitRepoFull(full: string): { workspace: string; repoSlug: string } {
-  const i = full.indexOf("/");
-  if (i <= 0 || i === full.length - 1) {
-    throw new Error("repoFull must be workspace/repo_slug");
-  }
-  return { workspace: full.slice(0, i), repoSlug: full.slice(i + 1) };
-}
-
-async function bbFetch(
-  path: string,
-  init?: RequestInit,
-): Promise<{ ok: boolean; status: number; json: unknown; text: string }> {
-  const url = joinApiPath(BB_API, path);
-  const baseHeaders: Record<string, string> = {
-    Authorization: basicAuthHeader(),
-    Accept: "application/json",
-  };
-  const extra = init?.headers as Record<string, string> | undefined;
-  const headers = extra === undefined ? baseHeaders : { ...baseHeaders, ...extra };
-  const res = await fetch(url, {
-    ...init,
-    headers,
-  });
-  const text = await res.text();
-  let json: unknown;
-  try {
-    json = JSON.parse(text) as unknown;
-  } catch {
-    json = null;
-  }
-  return { ok: res.ok, status: res.status, json, text };
-}
+import { registerBitbucketTools } from "./tools.ts";
 
 const server = new McpServer({ name: "nimbus-bitbucket", version: "0.1.0" });
 
-const registerSimpleTool = createRegisterSimpleTool(server);
-const reg = createZodToolRegistrar(registerSimpleTool);
-
-/**
- * Every MUTATING bitbucket 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: "bitbucket",
-  scopeEnv: "NIMBUS_MCP_BITBUCKET_WRITE_SCOPE",
-  scopeKinds: ["repo"],
-});
-
-const repoFullArg = z.object({
-  repoFull: z
-    .string()
-    .min(3)
-    .describe("Repository full name: workspace/repo_slug (e.g. myteam/my-service)"),
-});
-
-const bitbucketRepoListSchema = z.object({
-  pagelen: z.number().int().min(1).max(100).optional(),
-  page: z.string().max(2000).optional().describe("Opaque page URL or token from a prior next link"),
-});
-
-reg(
-  "bitbucket_repo_list",
-  "List repositories where the authenticated user is a member.",
-  bitbucketRepoListSchema,
-  async (parsed) => {
-    if (parsed.page?.startsWith("http")) {
-      const res = await bbFetch(parsed.page);
-      return mcpJsonResultIfOk("Bitbucket", res);
-    }
-    const qs = new URLSearchParams();
-    qs.set("role", "member");
-    qs.set("pagelen", String(parsed.pagelen ?? 30));
-    const res = await bbFetch(`/repositories?${qs.toString()}`);
-    return mcpJsonResultIfOk("Bitbucket", res);
-  },
-);
-
-const bitbucketPrListSchema = repoFullArg.extend({
-  state: z.enum(["OPEN", "MERGED", "DECLINED", "SUPERSEDED"]).optional(),
-  pagelen: z.number().int().min(1).max(100).optional(),
-  page: z.string().max(2000).optional().describe("Opaque next URL from a prior response"),
-});
-
-reg(
-  "bitbucket_pr_list",
-  "List pull requests for a repository.",
-  bitbucketPrListSchema,
-  async (parsed) => {
-    if (parsed.page?.startsWith("http")) {
-      const res = await bbFetch(parsed.page);
-      return mcpJsonResultIfOk("Bitbucket", res);
-    }
-    const { workspace, repoSlug } = splitRepoFull(parsed.repoFull);
-    const base = `/repositories/${encodeURIComponent(workspace)}/${encodeURIComponent(repoSlug)}/pullrequests`;
-    const qs = new URLSearchParams();
-    qs.set("pagelen", String(parsed.pagelen ?? 30));
-    qs.set("sort", "-updated_on");
-    if (parsed.state !== undefined) {
-      qs.set("q", `state="${parsed.state}"`);
-    }
-    const res = await bbFetch(`${base}?${qs.toString()}`);
-    return mcpJsonResultIfOk("Bitbucket", res);
-  },
-);
-
-const bitbucketPrGetSchema = repoFullArg.extend({
-  pullRequestId: z.number().int().min(1),
-});
-
-reg(
-  "bitbucket_pr_get",
-  "Get a single pull request by numeric id.",
-  bitbucketPrGetSchema,
-  async (parsed) => {
-    const { workspace, repoSlug } = splitRepoFull(parsed.repoFull);
-    const path = `/repositories/${encodeURIComponent(workspace)}/${encodeURIComponent(repoSlug)}/pullrequests/${String(parsed.pullRequestId)}`;
-    const res = await bbFetch(path);
-    return mcpJsonResultIfOk("Bitbucket", res);
-  },
-);
-
-const bitbucketPrMergeSchema = repoFullArg.extend({
-  pullRequestId: z.number().int().min(1),
-  mergeStrategy: z.enum(["merge_commit", "squash", "fast_forward"]).optional(),
-  message: z.string().max(32_768).optional(),
-});
-
-registerWriteTool(
-  "bitbucket_pr_merge",
-  {
-    mutates: "bitbucket.pr.merge",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "repo", value: p.repoFull }),
-  },
-  "Merge a pull request.",
-  bitbucketPrMergeSchema,
-  async (parsed) => {
-    const { workspace, repoSlug } = splitRepoFull(parsed.repoFull);
-    const path = `/repositories/${encodeURIComponent(workspace)}/${encodeURIComponent(repoSlug)}/pullrequests/${String(parsed.pullRequestId)}/merge`;
-    const body: Record<string, unknown> = { type: "pullrequest" };
-    if (parsed.mergeStrategy !== undefined) {
-      body["merge_strategy"] = parsed.mergeStrategy;
-    }
-    if (parsed.message !== undefined) {
-      body["message"] = parsed.message;
-    }
-    const res = await bbFetch(path, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body),
-    });
-    return mcpJsonResultIfOk("Bitbucket", res);
-  },
-);
-
-const bitbucketRepoPagedSchema = repoFullArg.extend({
-  pagelen: z.number().int().min(1).max(100).optional(),
-  page: z.string().max(2000).optional(),
-});
-
-reg(
-  "bitbucket_pipeline_list",
-  "List Pipelines runs for a repository.",
-  bitbucketRepoPagedSchema,
-  async (parsed) => {
-    if (parsed.page?.startsWith("http")) {
-      const res = await bbFetch(parsed.page);
-      return mcpJsonResultIfOk("Bitbucket", res);
-    }
-    const { workspace, repoSlug } = splitRepoFull(parsed.repoFull);
-    const base = `/repositories/${encodeURIComponent(workspace)}/${encodeURIComponent(repoSlug)}/pipelines/`;
-    const qs = new URLSearchParams();
-    qs.set("pagelen", String(parsed.pagelen ?? 30));
-    const res = await bbFetch(`${base}?${qs.toString()}`);
-    return mcpJsonResultIfOk("Bitbucket", res);
-  },
-);
-
-const bitbucketPipelineGetSchema = repoFullArg.extend({
-  pipelineUuid: z.string().min(8).max(128),
-});
-
-reg(
-  "bitbucket_pipeline_get",
-  "Get a single pipeline run by UUID.",
-  bitbucketPipelineGetSchema,
-  async (parsed) => {
-    const { workspace, repoSlug } = splitRepoFull(parsed.repoFull);
-    const encUuid = encodeURIComponent(parsed.pipelineUuid);
-    const path = `/repositories/${encodeURIComponent(workspace)}/${encodeURIComponent(repoSlug)}/pipelines/${encUuid}`;
-    const res = await bbFetch(path);
-    return mcpJsonResultIfOk("Bitbucket", res);
-  },
-);
-
-reg(
-  "bitbucket_issue_list",
-  "List issues for a repository (issue tracker must be enabled).",
-  bitbucketRepoPagedSchema,
-  async (parsed) => {
-    if (parsed.page?.startsWith("http")) {
-      const res = await bbFetch(parsed.page);
-      return mcpJsonResultIfOk("Bitbucket", res);
-    }
-    const { workspace, repoSlug } = splitRepoFull(parsed.repoFull);
-    const base = `/repositories/${encodeURIComponent(workspace)}/${encodeURIComponent(repoSlug)}/issues`;
-    const qs = new URLSearchParams();
-    qs.set("pagelen", String(parsed.pagelen ?? 30));
-    const res = await bbFetch(`${base}?${qs.toString()}`);
-    return mcpJsonResultIfOk("Bitbucket", res);
-  },
-);
+registerBitbucketTools(server);
 
 const transport = new StdioServerTransport();
 await server.connect(transport);