@nimbus-dev/connectors 0.2.0 → 0.2.2

package/connectors/imap/src/server.ts

@@ -1,232 +1,45 @@
+/**
+ * IMAP/SMTP connector entry point.
+ *
+ * Everything below the config is in `shared/imapflow-adapter.ts`: the imapflow
+ * client and nodemailer mailer used to be written out in full here and in
+ * protonmail's entry point, which made them the most duplicated pair in the repo
+ * and left both files unreachable from a test. This file is now only the
+ * env → config mapping the adapter cannot know.
+ */
+
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { type FetchMessageObject, type FetchQueryObject, ImapFlow } from "imapflow";
-import { createTransport, type Transporter } from "nodemailer";
-import {
-  type BodyStructureNode,
-  extractAttachments,
-  findTextPlainPart,
-} from "../../../shared/imap-bodystructure.ts";
-import { envInt, previewFromParts } from "../../../shared/imap-tool-kit.ts";
+import { envInt } from "../../../shared/imap-tool-kit.ts";
+import { createImapFlowClient, createNodemailerMailer } from "../../../shared/imapflow-adapter.ts";
 import { requireProcessEnv } from "../../../shared/mcp-tool-kit.ts";
-import {
-  clampLimit,
-  type ImapAddress,
-  type ImapClient,
-  type ImapEnvelope,
-  type ImapListOptions,
-  type ImapMessageMeta,
-  type ImapSearchOptions,
-  PREVIEW_FETCH_BYTES,
-  type SendMailInput,
-  type SendMailResult,
-  type SmtpMailer,
-} from "./imap-core.ts";
 import { registerImapTools } from "./tools.ts";
 
 const DEFAULT_IMAP_PORT = 993;
 const DEFAULT_SMTP_PORT = 465;
-const DEFAULT_MAILBOX = "INBOX";
-
-/**
- * Build an {@link ImapAddress} from an imapflow envelope address, omitting
- * `name`/`address` when absent (the interface uses `exactOptionalPropertyTypes`,
- * so an explicit `undefined` is not assignable).
- */
-function toImapAddress(a: { name?: string; address?: string }): ImapAddress {
-  const out: { name?: string; address?: string } = {};
-  if (a.name !== undefined) {
-    out.name = a.name;
-  }
-  if (a.address !== undefined) {
-    out.address = a.address;
-  }
-  return out;
-}
-
-function envelopeFromImap(env: FetchMessageObject["envelope"]): ImapEnvelope {
-  if (env === undefined) {
-    return {};
-  }
-  return {
-    date: env.date ?? null,
-    subject: env.subject ?? null,
-    messageId: env.messageId ?? null,
-    from: (env.from ?? []).map(toImapAddress),
-    to: (env.to ?? []).map(toImapAddress),
-    cc: (env.cc ?? []).map(toImapAddress),
-  };
-}
-
-function toMessageMeta(
-  msg: FetchMessageObject,
-  mailbox: string,
-  uidValidity: string | null,
-): ImapMessageMeta {
-  const structure = (msg.bodyStructure ?? null) as BodyStructureNode | null;
-  const partKey = findTextPlainPart(structure);
-  return {
-    uid: msg.uid,
-    mailbox,
-    uidValidity,
-    envelope: envelopeFromImap(msg.envelope),
-    attachments: extractAttachments(structure),
-    preview: previewFromParts(msg.bodyParts, partKey),
-  };
-}
-
-/**
- * Fetch query that requests ONLY headers + structure + a truncated text body
- * part. There is no `source` / full-body request here by construction.
- */
-function previewFetchQuery(): FetchQueryObject {
-  return {
-    uid: true,
-    envelope: true,
-    bodyStructure: true,
-    internalDate: true,
-    // Two candidate text part keys, each capped to PREVIEW_FETCH_BYTES bytes.
-    bodyParts: [
-      { key: "1", start: 0, maxLength: PREVIEW_FETCH_BYTES },
-      { key: "TEXT", start: 0, maxLength: PREVIEW_FETCH_BYTES },
-    ],
-  };
-}
+/** The port on which SMTP uses implicit TLS; anything else is STARTTLS. */
+const SMTPS_PORT = 465;
 
-/** Real IMAP client over imapflow. Per-call connect/lock/logout keeps it stateless. */
-class ImapFlowClient implements ImapClient {
-  private readonly config: {
-    host: string;
-    port: number;
-    user: string;
-    pass: string;
-  };
-
-  constructor() {
-    this.config = {
-      host: requireProcessEnv("IMAP_HOST"),
-      port: envInt("IMAP_PORT", DEFAULT_IMAP_PORT),
-      user: requireProcessEnv("IMAP_USERNAME"),
-      pass: requireProcessEnv("IMAP_PASSWORD"),
-    };
-  }
-
-  private newClient(): ImapFlow {
-    return new ImapFlow({
-      host: this.config.host,
-      port: this.config.port,
-      secure: true,
-      auth: { user: this.config.user, pass: this.config.pass },
-      logger: false,
-    });
-  }
-
-  private async withMailbox<T>(
-    mailbox: string,
-    fn: (client: ImapFlow, uidValidity: string | null) => Promise<T>,
-  ): Promise<T> {
-    const client = this.newClient();
-    await client.connect();
-    const lock = await client.getMailboxLock(mailbox);
-    try {
-      const mb = client.mailbox;
-      const uidValidity = mb === false ? null : String(mb.uidValidity);
-      return await fn(client, uidValidity);
-    } finally {
-      lock.release();
-      await client.logout();
-    }
-  }
-
-  async list(options: ImapListOptions): Promise<ImapMessageMeta[]> {
-    const mailbox = options.mailbox ?? DEFAULT_MAILBOX;
-    const limit = clampLimit(options.limit);
-    return this.withMailbox(mailbox, async (client, uidValidity) => {
-      const out: ImapMessageMeta[] = [];
-      const status = await client.status(mailbox, { messages: true });
-      const total = status.messages ?? 0;
-      if (total === 0) {
-        return out;
-      }
-      const start = Math.max(1, total - limit + 1);
-      const range = `${start}:${total}`;
-      for await (const msg of client.fetch(range, previewFetchQuery())) {
-        out.push(toMessageMeta(msg, mailbox, uidValidity));
-      }
-      // Most-recent first.
-      out.sort((a, b) => b.uid - a.uid);
-      return out;
-    });
-  }
-
-  async get(uid: number, mailbox?: string): Promise<ImapMessageMeta | null> {
-    const box = mailbox ?? DEFAULT_MAILBOX;
-    return this.withMailbox(box, async (client, uidValidity) => {
-      const msg = await client.fetchOne(String(uid), previewFetchQuery(), { uid: true });
-      return msg === false ? null : toMessageMeta(msg, box, uidValidity);
-    });
-  }
-
-  async search(options: ImapSearchOptions): Promise<ImapMessageMeta[]> {
-    const mailbox = options.mailbox ?? DEFAULT_MAILBOX;
-    const limit = clampLimit(options.limit);
-    const q = options.query;
-    return this.withMailbox(mailbox, async (client, uidValidity) => {
-      const uids = await client.search(
-        { or: [{ subject: q }, { from: q }, { to: q }] },
-        { uid: true },
-      );
-      if (uids === false || uids.length === 0) {
-        return [];
-      }
-      const picked = uids.slice(-limit).sort((a, b) => b - a);
-      const out: ImapMessageMeta[] = [];
-      for await (const msg of client.fetch(picked, previewFetchQuery(), { uid: true })) {
-        out.push(toMessageMeta(msg, mailbox, uidValidity));
-      }
-      out.sort((a, b) => b.uid - a.uid);
-      return out;
-    });
-  }
-}
-
-/** Real SMTP mailer over nodemailer. */
-class NodemailerMailer implements SmtpMailer {
-  private readonly transport: Transporter;
-  private readonly from: string;
-
-  constructor() {
-    const host = requireProcessEnv("IMAP_SMTP_HOST");
-    const port = envInt("IMAP_SMTP_PORT", DEFAULT_SMTP_PORT);
-    const user = requireProcessEnv("IMAP_SMTP_USERNAME");
-    const pass = requireProcessEnv("IMAP_SMTP_PASSWORD");
-    this.from = user;
-    this.transport = createTransport({
-      host,
-      port,
-      secure: port === 465,
-      auth: { user, pass },
-    });
-  }
-
-  async send(input: SendMailInput): Promise<SendMailResult> {
-    const info = await this.transport.sendMail({
-      from: this.from,
-      to: input.to,
-      subject: input.subject,
-      text: input.body,
-      ...(input.cc === undefined ? {} : { cc: input.cc }),
-      ...(input.bcc === undefined ? {} : { bcc: input.bcc }),
-    });
-    return {
-      messageId: info.messageId ?? null,
-      accepted: (info.accepted ?? []).map(String),
-      rejected: (info.rejected ?? []).map(String),
-    };
-  }
-}
+const smtpPort = envInt("IMAP_SMTP_PORT", DEFAULT_SMTP_PORT);
 
 const server = new McpServer({ name: "nimbus-imap", version: "0.1.0" });
-registerImapTools(server, new ImapFlowClient(), new NodemailerMailer());
+
+registerImapTools(
+  server,
+  createImapFlowClient({
+    host: requireProcessEnv("IMAP_HOST"),
+    port: envInt("IMAP_PORT", DEFAULT_IMAP_PORT),
+    user: requireProcessEnv("IMAP_USERNAME"),
+    pass: requireProcessEnv("IMAP_PASSWORD"),
+    secure: true,
+  }),
+  createNodemailerMailer({
+    host: requireProcessEnv("IMAP_SMTP_HOST"),
+    port: smtpPort,
+    user: requireProcessEnv("IMAP_SMTP_USERNAME"),
+    pass: requireProcessEnv("IMAP_SMTP_PASSWORD"),
+    secure: smtpPort === SMTPS_PORT,
+  }),
+);
 
 await server.connect(new StdioServerTransport());

package/connectors/intercom/src/server.ts

@@ -1,65 +1,6 @@
-import { z } from "zod";
-import { matchesResult, searchToolInputSchema } 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 { filterIntercomConversations } from "./search-filter.ts";
-
-const BASE = "https://api.intercom.io";
-
-function apiToken(): string {
-  const t = process.env["INTERCOM_TOKEN"]?.trim();
-  if (t === undefined || t === "") {
-    throw new Error("INTERCOM_TOKEN is not set");
-  }
-  return t;
-}
-
-function authHeader(): Record<string, string> {
-  return {
-    Authorization: `Bearer ${apiToken()}`,
-    "Intercom-Version": "2.11",
-    Accept: "application/json",
-  };
-}
-
-async function intercomGet(path: string): Promise<unknown> {
-  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`Intercom ${String(res.status)}: ${text.slice(0, 400)}`);
-  }
-  return JSON.parse(text) as unknown;
-}
+import { registerIntercomTools } from "./tools.ts";
 
 await runReadOnlyMcpConnector("nimbus-intercom", (reg) => {
-  reg(
-    "intercom_list",
-    'List the user\'s Intercom conversations (`GET /conversations?per_page=150`). Returns the `{ type: "conversation.list", conversations: [...], pages, total_count }` envelope — `conversations` holds the conversation objects.',
-    z.object({}),
-    async () => {
-      return jsonResult(await intercomGet(`/conversations?per_page=150`));
-    },
-  );
-
-  reg(
-    "intercom_get",
-    "Fetch one Intercom conversation by its id (`GET /conversations/{id}` — note the PLURAL `conversations` in the get-by-id path). Returns the conversation object directly. Throws when no match is found.",
-    z.object({
-      id: z.string().min(1),
-    }),
-    async (p) => {
-      return jsonResult(await intercomGet(`/conversations/${encodeURIComponent(p.id)}`));
-    },
-  );
-
-  reg(
-    "intercom_search",
-    "Substring search across the user's Intercom conversations (first page only). Matches the query against the conversation subject, the source message body, the state, the source author name + email, and the tags (case-insensitive). Returns a `{ matches: [...] }` envelope.",
-    searchToolInputSchema(100),
-    async (p) => {
-      const root = await intercomGet(`/conversations?per_page=150`);
-      const conversations = (root as { conversations?: unknown[] } | null)?.conversations;
-      return matchesResult(conversations, filterIntercomConversations, p);
-    },
-  );
+  registerIntercomTools(reg);
 });

package/connectors/intercom/src/tools.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { createJsonGetter, requiredEnv } from "../../../shared/env-json-api.ts";
+import { matchesResult, searchToolInputSchema } 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 { filterIntercomConversations } from "./search-filter.ts";
+
+const BASE = "https://api.intercom.io";
+
+function authHeader(): Record<string, string> {
+  return {
+    Authorization: `Bearer ${requiredEnv("INTERCOM_TOKEN")}`,
+    "Intercom-Version": "2.11",
+    Accept: "application/json",
+  };
+}
+
+const intercomGet = createJsonGetter({
+  base: BASE,
+  label: "Intercom",
+  headers: authHeader,
+});
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const INTERCOM_TOOL_NAMES = ["intercom_get", "intercom_list", "intercom_search"] as const;
+
+export function registerIntercomTools(reg: ZodToolRegistrar): void {
+  reg(
+    "intercom_list",
+    'List the user\'s Intercom conversations (`GET /conversations?per_page=150`). Returns the `{ type: "conversation.list", conversations: [...], pages, total_count }` envelope — `conversations` holds the conversation objects.',
+    z.object({}),
+    async () => {
+      return jsonResult(await intercomGet(`/conversations?per_page=150`));
+    },
+  );
+
+  reg(
+    "intercom_get",
+    "Fetch one Intercom conversation by its id (`GET /conversations/{id}` — note the PLURAL `conversations` in the get-by-id path). Returns the conversation object directly. Throws when no match is found.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await intercomGet(`/conversations/${encodeURIComponent(p.id)}`));
+    },
+  );
+
+  reg(
+    "intercom_search",
+    "Substring search across the user's Intercom conversations (first page only). Matches the query against the conversation subject, the source message body, the state, the source author name + email, and the tags (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const root = await intercomGet(`/conversations?per_page=150`);
+      const conversations = (root as { conversations?: unknown[] } | null)?.conversations;
+      return matchesResult(conversations, filterIntercomConversations, p);
+    },
+  );
+}

package/connectors/jenkins/src/jenkins-api.ts

@@ -1,12 +1,8 @@
+import { requiredBaseUrl } from "../../../shared/env-json-api.ts";
 import { encodeBasicAuthHeader } from "../../../shared/mcp-tool-kit.ts";
-import { stripTrailingSlashes } from "../../../shared/strip-trailing-slashes.ts";
 
 export function jenkinsBaseUrl(): string {
-  const raw = process.env["JENKINS_BASE_URL"]?.trim() ?? "";
-  if (raw === "") {
-    throw new Error("JENKINS_BASE_URL is not set");
-  }
-  return stripTrailingSlashes(raw);
+  return requiredBaseUrl("JENKINS_BASE_URL");
 }
 
 export function jenkinsAuthHeader(): string {

package/connectors/jenkins/src/server.ts

@@ -1,223 +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 {
-  getJenkinsCrumb,
-  jenkinsAuthHeader,
-  jenkinsBaseUrl,
-  jenkinsFetchJson,
-  jenkinsPost,
-  jobApiRoot,
-} from "./jenkins-api.ts";
+import { registerJenkinsTools } from "./tools.ts";
 
 const mcp = new McpServer({ name: "nimbus-jenkins", version: "0.1.0" });
 
-import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
-
-const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
-
-/**
- * Every MUTATING jenkins 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: "jenkins",
-  scopeEnv: "NIMBUS_MCP_JENKINS_WRITE_SCOPE",
-  scopeKinds: ["job"],
-});
-
-const JOBS_TREE =
-  "jobs[name,fullname,url,jobs[name,fullname,url,jobs[name,fullname,url,jobs[name,fullname,url]]]]";
-
-type JobNode = {
-  name?: string;
-  fullName?: string;
-  url?: string;
-  jobs?: JobNode[];
-};
-
-function jenkinsJobNodeDisplayName(n: JobNode): string {
-  if (typeof n.fullName === "string" && n.fullName !== "") {
-    return n.fullName;
-  }
-  if (typeof n.name === "string") {
-    return n.name;
-  }
-  return "";
-}
-
-function flattenJobs(
-  nodes: JobNode[] | undefined,
-  out: { fullName: string; url?: string }[],
-): void {
-  if (nodes === undefined) {
-    return;
-  }
-  for (const n of nodes) {
-    const fn = jenkinsJobNodeDisplayName(n);
-    if (fn !== "") {
-      if (typeof n.url === "string") {
-        out.push({ fullName: fn, url: n.url });
-      } else {
-        out.push({ fullName: fn });
-      }
-    }
-    flattenJobs(n.jobs, out);
-  }
-}
-
-reg(
-  "jenkins_job_list",
-  "List Jenkins jobs (nested folders, limited depth).",
-  z.object({}),
-  async () => {
-    const base = jenkinsBaseUrl();
-    const url = `${base}/api/json?tree=${encodeURIComponent(JOBS_TREE)}`;
-    const root = await jenkinsGetJsonExpectOk(url);
-    if (root === null || typeof root !== "object" || Array.isArray(root)) {
-      throw new Error("Jenkins: invalid jobs response");
-    }
-    const jobsRaw = (root as Record<string, unknown>)["jobs"];
-    const list: { fullName: string; url?: string }[] = [];
-    flattenJobs(Array.isArray(jobsRaw) ? (jobsRaw as JobNode[]) : undefined, list);
-    return jsonResult({ jobs: list });
-  },
-);
-
-async function jenkinsGetJsonExpectOk(url: string): Promise<unknown> {
-  const auth = jenkinsAuthHeader();
-  const res = await jenkinsFetchJson(url, { method: "GET", authHeader: auth });
-  if (!res.ok) {
-    throw new Error(`Jenkins ${String(res.status)}: ${res.text.slice(0, 400)}`);
-  }
-  return res.json;
-}
-
-const jobNameSchema = z.object({
-  jobName: z.string().min(1).describe("Job full name (e.g. folder/sub/job)"),
-});
-
-reg("jenkins_job_get", "Get Jenkins job metadata by full name.", jobNameSchema, async (parsed) => {
-  const base = jenkinsBaseUrl();
-  const root = jobApiRoot(base, parsed.jobName);
-  const url = `${root}/api/json`;
-  return jsonResult(await jenkinsGetJsonExpectOk(url));
-});
-
-reg(
-  "jenkins_build_list",
-  "List recent builds for a job.",
-  z.object({
-    jobName: z.string().min(1),
-    limit: z.number().int().min(1).max(50).optional(),
-  }),
-  async (parsed) => {
-    const base = jenkinsBaseUrl();
-    const lim = parsed.limit ?? 20;
-    const tree = encodeURIComponent(
-      `builds[number,url,result,duration,timestamp,building]{0,${String(lim)}}`,
-    );
-    const url = `${jobApiRoot(base, parsed.jobName)}/api/json?tree=${tree}`;
-    return jsonResult(await jenkinsGetJsonExpectOk(url));
-  },
-);
-
-reg(
-  "jenkins_build_get",
-  "Get a single build by job name and build number.",
-  z.object({
-    jobName: z.string().min(1),
-    buildNumber: z.number().int().min(1),
-  }),
-  async (parsed) => {
-    const base = jenkinsBaseUrl();
-    const url = `${jobApiRoot(base, parsed.jobName)}/${String(parsed.buildNumber)}/api/json`;
-    return jsonResult(await jenkinsGetJsonExpectOk(url));
-  },
-);
-
-registerWriteTool(
-  "jenkins_build_trigger",
-  {
-    mutates: "jenkins.build.trigger",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "job", value: p.jobName }),
-  },
-  "Trigger a new build for a job.",
-  jobNameSchema,
-  async (parsed) => {
-    const base = jenkinsBaseUrl();
-    const auth = jenkinsAuthHeader();
-    const crumb = await getJenkinsCrumb(base, auth);
-    const url = `${jobApiRoot(base, parsed.jobName)}/build`;
-    const res = await jenkinsPost(url, auth, crumb);
-    if (!res.ok) {
-      throw new Error(`Jenkins trigger ${String(res.status)}: ${res.text.slice(0, 400)}`);
-    }
-    return jsonResult({ ok: true, jobName: parsed.jobName });
-  },
-);
-
-registerWriteTool(
-  "jenkins_build_abort",
-  {
-    mutates: "jenkins.build.abort",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "job", value: p.jobName }),
-  },
-  "Abort/stop a running build.",
-  z.object({
-    jobName: z.string().min(1),
-    buildNumber: z.number().int().min(1),
-  }),
-  async (parsed) => {
-    const base = jenkinsBaseUrl();
-    const auth = jenkinsAuthHeader();
-    const crumb = await getJenkinsCrumb(base, auth);
-    const url = `${jobApiRoot(base, parsed.jobName)}/${String(parsed.buildNumber)}/stop`;
-    const res = await jenkinsPost(url, auth, crumb);
-    if (!res.ok) {
-      throw new Error(`Jenkins abort ${String(res.status)}: ${res.text.slice(0, 400)}`);
-    }
-    return jsonResult({ ok: true, jobName: parsed.jobName, buildNumber: parsed.buildNumber });
-  },
-);
-
-reg(
-  "jenkins_build_log_tail",
-  "Fetch console text for a build (full log; tail client-side).",
-  z.object({
-    jobName: z.string().min(1),
-    buildNumber: z.number().int().min(1),
-    maxLines: z.number().int().min(1).max(5000).optional(),
-  }),
-  async (parsed) => {
-    const base = jenkinsBaseUrl();
-    const auth = jenkinsAuthHeader();
-    const url = `${jobApiRoot(base, parsed.jobName)}/${String(parsed.buildNumber)}/consoleText`;
-    const res = await fetch(url, { headers: { Authorization: auth } });
-    const text = await res.text();
-    if (!res.ok) {
-      throw new Error(`Jenkins log ${String(res.status)}: ${text.slice(0, 400)}`);
-    }
-    const maxLines = parsed.maxLines ?? 200;
-    const lines = text.split(/\r?\n/);
-    const tail = lines.slice(Math.max(0, lines.length - maxLines)).join("\n");
-    return jsonResult({
-      jobName: parsed.jobName,
-      buildNumber: parsed.buildNumber,
-      lineCount: lines.length,
-      tail,
-    });
-  },
-);
+registerJenkinsTools(mcp);
 
 const transport = new StdioServerTransport();
 await mcp.connect(transport);