@nimbus-dev/connectors 0.2.1 → 0.2.3

package/connectors/cloudwatch/src/tools.ts

@@ -1,18 +1,21 @@
 import { z } from "zod";
+import {
+  asArray,
+  awsCliArg,
+  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 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.
+ * the schema boundary (`awsCliArg`) if it begins with `-` (argv flag smuggling),
+ * contains control characters, or starts with a prefix that makes the CLI read the
+ * value from a file or a URL instead.
  */
-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
@@ -32,40 +35,19 @@ export const CLOUDWATCH_TOOL_NAMES = [
 
 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);
-}
+const logsCli = createCliJsonRunner(
+  {
+    argv: (args) => ["aws", "logs", ...args, "--output", "json"],
+    label: "aws logs",
+    emptyResult: {},
+  },
+  nimbusSpawn,
+);
 
 function groupMatches(entry: unknown, q: string): boolean {
   if (!isRecord(entry)) {
@@ -84,7 +66,7 @@ export function registerCloudwatchTools(reg: ZodToolRegistrar): void {
     "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(),
+      prefix: awsCliArg.optional(),
     }),
     async (p) => {
       const args = ["describe-log-groups", "--limit", LIMIT];
@@ -99,7 +81,7 @@ export function registerCloudwatchTools(reg: ZodToolRegistrar): void {
     "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,
+      logGroupName: awsCliArg,
     }),
     async (p) => {
       const group = await logsCli([

package/connectors/codemagic/src/server.ts

@@ -1,74 +1,6 @@
-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;
-}
+import { registerCodemagicTools } from "./tools.ts";
 
 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);
-    },
-  );
+  registerCodemagicTools(reg);
 });

package/connectors/codemagic/src/tools.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { createJsonGetter, envAuthHeaders } from "../../../shared/env-json-api.ts";
+import { matchesResult } from "../../../shared/mcp-search-tool.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterCodemagicBuilds } from "./search-filter.ts";
+
+const CODEMAGIC_API = "https://api.codemagic.io";
+
+const codemagicGet = createJsonGetter({
+  base: CODEMAGIC_API,
+  label: "Codemagic",
+  headers: envAuthHeaders({ env: "CODEMAGIC_TOKEN", scheme: "", header: "x-auth-token" }),
+});
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const CODEMAGIC_TOOL_NAMES = [
+  "codemagic_list",
+  "codemagic_get",
+  "codemagic_search",
+] as const;
+
+export function registerCodemagicTools(reg: ZodToolRegistrar): void {
+  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/src/server.ts

@@ -1,309 +1,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import {
-  fetchAtlassianBasicAuthJsonText,
-  normalizeRequiredSiteBaseUrl,
-  requireTrimmedEnv,
-} from "../../../shared/atlassian-json-fetch.ts";
-import { joinApiPath } from "../../../shared/join-api-path.ts";
-import { parseCitationsJson } from "../../../shared/kb-markdown.ts";
-import {
-  createRegisterSimpleTool,
-  createZodToolRegistrar,
-  mcpJsonResultFromTextIfOk,
-} from "../../../shared/mcp-tool-kit.ts";
-import { buildConfluenceKbPageBody } from "./kb-append.ts";
-
-function wikiRoot(siteBase: string): string {
-  const b = normalizeRequiredSiteBaseUrl(siteBase, "CONFLUENCE_BASE_URL is empty");
-  return b.endsWith("/wiki") ? b : `${b}/wiki`;
-}
-
-function requireConfluenceConfig(): { wikiApi: string; email: string; token: string } {
-  const baseRaw = requireTrimmedEnv("CONFLUENCE_BASE_URL", "CONFLUENCE_BASE_URL is not set");
-  const email = requireTrimmedEnv("CONFLUENCE_EMAIL", "CONFLUENCE_EMAIL is not set");
-  const token = requireTrimmedEnv("CONFLUENCE_API_TOKEN", "CONFLUENCE_API_TOKEN is not set");
-  return {
-    wikiApi: `${wikiRoot(baseRaw)}/rest/api`,
-    email,
-    token,
-  };
-}
-
-async function confFetch(
-  path: string,
-  init?: RequestInit,
-): Promise<{ ok: boolean; status: number; text: string }> {
-  const { wikiApi, email, token } = requireConfluenceConfig();
-  const url = joinApiPath(wikiApi, path);
-  return fetchAtlassianBasicAuthJsonText(url, email, token, init);
-}
+import { registerConfluenceTools } from "./tools.ts";
 
 const server = new McpServer({ name: "nimbus-confluence", version: "0.1.0" });
 
-const registerSimpleTool = createRegisterSimpleTool(server);
-
-import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
-
-const reg = createZodToolRegistrar(registerSimpleTool);
-
-/**
- * Every MUTATING confluence 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: "confluence",
-  scopeEnv: "NIMBUS_MCP_CONFLUENCE_WRITE_SCOPE",
-  scopeKinds: ["space", "page"],
-});
-
-const confluenceLimitStartSchema = z.object({
-  limit: z.number().int().min(1).max(100).optional(),
-  start: z.number().int().min(0).optional(),
-});
-
-reg(
-  "confluence_space_list",
-  "List Confluence spaces (GET /space).",
-  confluenceLimitStartSchema,
-  async (parsed) => {
-    const qs = new URLSearchParams({
-      limit: String(parsed.limit ?? 25),
-      start: String(parsed.start ?? 0),
-    });
-    const res = await confFetch(`/space?${qs.toString()}`);
-    return mcpJsonResultFromTextIfOk("Confluence", res);
-  },
-);
-
-const confluenceSpaceContentSchema = z.object({
-  spaceKey: z.string().min(1),
-  limit: z.number().int().min(1).max(100).optional(),
-  start: z.number().int().min(0).optional(),
-});
-
-reg(
-  "confluence_page_list",
-  "List pages in a space (GET /content, type=page).",
-  confluenceSpaceContentSchema,
-  async (parsed) => {
-    const qs = new URLSearchParams({
-      type: "page",
-      spaceKey: parsed.spaceKey,
-      limit: String(parsed.limit ?? 50),
-      start: String(parsed.start ?? 0),
-      expand: "history.lastUpdated,version",
-    });
-    const res = await confFetch(`/content?${qs.toString()}`);
-    return mcpJsonResultFromTextIfOk("Confluence", res);
-  },
-);
-
-const confluencePageIdSchema = z.object({ pageId: z.string().min(1) });
-
-reg(
-  "confluence_page_get",
-  "Get a Confluence page with body.storage (GET /content/{id}).",
-  confluencePageIdSchema,
-  async (parsed) => {
-    const id = encodeURIComponent(parsed.pageId);
-    const res = await confFetch(
-      `/content/${id}?expand=body.storage,version,history.lastUpdated,space`,
-    );
-    return mcpJsonResultFromTextIfOk("Confluence", res);
-  },
-);
-
-reg(
-  "confluence_blogpost_list",
-  "List blog posts in a space (GET /content, type=blogpost).",
-  confluenceSpaceContentSchema,
-  async (parsed) => {
-    const qs = new URLSearchParams({
-      type: "blogpost",
-      spaceKey: parsed.spaceKey,
-      limit: String(parsed.limit ?? 25),
-      start: String(parsed.start ?? 0),
-      expand: "history.lastUpdated,version",
-    });
-    const res = await confFetch(`/content?${qs.toString()}`);
-    return mcpJsonResultFromTextIfOk("Confluence", res);
-  },
-);
-
-const confluencePostIdSchema = z.object({ postId: z.string().min(1) });
-
-reg(
-  "confluence_blogpost_get",
-  "Get a blog post by id (GET /content/{id}).",
-  confluencePostIdSchema,
-  async (parsed) => {
-    const id = encodeURIComponent(parsed.postId);
-    const res = await confFetch(
-      `/content/${id}?expand=body.storage,version,history.lastUpdated,space`,
-    );
-    return mcpJsonResultFromTextIfOk("Confluence", res);
-  },
-);
-
-const confluenceCommentListSchema = z.object({
-  pageId: z.string().min(1),
-  limit: z.number().int().min(1).max(100).optional(),
-  start: z.number().int().min(0).optional(),
-});
-
-reg(
-  "confluence_comment_list",
-  "List footer comments on a page (GET /content/{id}/child/comment).",
-  confluenceCommentListSchema,
-  async (parsed) => {
-    const id = encodeURIComponent(parsed.pageId);
-    const qs = new URLSearchParams({
-      limit: String(parsed.limit ?? 50),
-      start: String(parsed.start ?? 0),
-      expand: "body.storage,version",
-    });
-    const res = await confFetch(`/content/${id}/child/comment?${qs.toString()}`);
-    return mcpJsonResultFromTextIfOk("Confluence", res);
-  },
-);
-
-const confluencePageCreateSchema = z.object({
-  spaceKey: z.string().min(1),
-  title: z.string().min(1),
-  storageHtml: z.string().min(1),
-  parentPageId: z.string().min(1).optional(),
-});
-
-registerWriteTool(
-  "confluence_page_create",
-  {
-    mutates: "confluence.page.create",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "space", value: p.spaceKey }),
-  },
-  "Create a page in a space (POST /content). Optional parentPageId.",
-  confluencePageCreateSchema,
-  async (parsed) => {
-    const body: Record<string, unknown> = {
-      type: "page",
-      title: parsed.title,
-      space: { key: parsed.spaceKey },
-      body: {
-        storage: {
-          value: parsed.storageHtml,
-          representation: "storage",
-        },
-      },
-    };
-    if (parsed.parentPageId !== undefined) {
-      body["ancestors"] = [{ id: parsed.parentPageId }];
-    }
-    const res = await confFetch("/content", { method: "POST", body: JSON.stringify(body) });
-    return mcpJsonResultFromTextIfOk("Confluence", res);
-  },
-);
-
-const confluenceKbAppendSchema = z.object({
-  spaceKey: z.string().min(1),
-  parentPageId: z.string().min(1),
-  title: z.string().min(1),
-  bodyMarkdown: z.string().min(1),
-  citationsJson: z.string().optional(),
-});
-
-registerWriteTool(
-  "confluence_kb_append",
-  {
-    mutates: "confluence.knowledge.write",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "space", value: p.spaceKey }),
-  },
-  "Create a knowledge-base page under a parent from simple markdown + citations (POST /content). " +
-    "Used by Nimbus tribal-knowledge capture; the destination space/parent is supplied by the gateway from local config only.",
-  confluenceKbAppendSchema,
-  async (parsed) => {
-    const body = buildConfluenceKbPageBody({
-      spaceKey: parsed.spaceKey,
-      parentPageId: parsed.parentPageId,
-      title: parsed.title,
-      bodyMarkdown: parsed.bodyMarkdown,
-      citations: parseCitationsJson(parsed.citationsJson ?? "[]"),
-    });
-    const res = await confFetch("/content", { method: "POST", body: JSON.stringify(body) });
-    return mcpJsonResultFromTextIfOk("Confluence", res);
-  },
-);
-
-const confluencePageUpdateSchema = z.object({
-  pageId: z.string().min(1),
-  versionNumber: z.number().int().min(1),
-  title: z.string().min(1),
-  storageHtml: z.string().min(1),
-});
-
-registerWriteTool(
-  "confluence_page_update",
-  {
-    mutates: "confluence.page.update",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "page", value: p.pageId }),
-  },
-  "Update page body and bump version (PUT /content/{id}). Pass current version number and title.",
-  confluencePageUpdateSchema,
-  async (parsed) => {
-    const id = encodeURIComponent(parsed.pageId);
-    const body: Record<string, unknown> = {
-      type: "page",
-      title: parsed.title,
-      version: { number: parsed.versionNumber + 1, message: "nimbus" },
-      body: {
-        storage: {
-          value: parsed.storageHtml,
-          representation: "storage",
-        },
-      },
-    };
-    const res = await confFetch(`/content/${id}`, { method: "PUT", body: JSON.stringify(body) });
-    return mcpJsonResultFromTextIfOk("Confluence", res);
-  },
-);
-
-const confluenceCommentAddSchema = z.object({
-  pageId: z.string().min(1),
-  storageHtml: z.string().min(1),
-});
-
-registerWriteTool(
-  "confluence_comment_add",
-  {
-    mutates: "confluence.comment.add",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "page", value: p.pageId }),
-  },
-  "Add a footer comment to a page (POST /content/{id}/child/comment).",
-  confluenceCommentAddSchema,
-  async (parsed) => {
-    const id = encodeURIComponent(parsed.pageId);
-    const body = {
-      type: "comment",
-      container: { id: parsed.pageId, type: "page" },
-      body: {
-        storage: {
-          value: parsed.storageHtml,
-          representation: "storage",
-        },
-      },
-    };
-    const res = await confFetch(`/content/${id}/child/comment`, {
-      method: "POST",
-      body: JSON.stringify(body),
-    });
-    return mcpJsonResultFromTextIfOk("Confluence", res);
-  },
-);
+registerConfluenceTools(server);
 
 const transport = new StdioServerTransport();
 await server.connect(transport);