@nimbus-dev/connectors 0.1.0

package/connectors/imap/src/server.ts

@@ -0,0 +1,232 @@
+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 { 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 },
+    ],
+  };
+}
+
+/** 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 server = new McpServer({ name: "nimbus-imap", version: "0.1.0" });
+registerImapTools(server, new ImapFlowClient(), new NodemailerMailer());
+
+await server.connect(new StdioServerTransport());

package/connectors/imap/src/tools.ts

@@ -0,0 +1,40 @@
+import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { registerEmailConnectorTools } from "../../../shared/imap-tool-kit.ts";
+import { formatAddress, type ImapClient, type SmtpMailer } from "./imap-core.ts";
+
+/**
+ * Register the IMAP read tools + the SMTP send tool onto an MCP server. The
+ * IMAP client and SMTP mailer are injected so tests exercise the tool surface
+ * without opening real sockets.
+ */
+export function registerImapTools(
+  // Widened: the consent kit needs the real server surface, not just the `.tool` shim.
+  server: ConsentServer & { tool: (...args: never) => unknown },
+  client: ImapClient,
+  mailer: SmtpMailer,
+): void {
+  const registerWriteTool = createWriteToolRegistrar(server, {
+    connector: "imap",
+    scopeEnv: "NIMBUS_MCP_IMAP_WRITE_SCOPE",
+    scopeKinds: ["recipient"],
+  });
+
+  registerEmailConnectorTools({
+    server,
+    registerWriteTool,
+    toolPrefix: "imap",
+    descriptions: {
+      list: "List recent mailbox messages — HEADERS + attachment METADATA + a short capped text preview ONLY. Returns subject, from, to/cc, date, message-id, attachment {filename,size,mimetype}, and a <=2000-char plain-text body preview. NEVER returns attachment bytes or the full message body.",
+      get: "Fetch one message by uid — HEADERS + attachment METADATA + a short capped text preview ONLY. NEVER returns attachment bytes or the full message body.",
+      search:
+        "Substring search over message HEADERS (subject/from/to) — returns the same header + attachment-metadata + preview view as imap_list. Searches headers only; NEVER scans or returns document/body content beyond the capped preview.",
+      send: "Send a new email over SMTP.",
+    },
+    client,
+    mailer,
+    formatAddr: formatAddress,
+  });
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const IMAP_TOOL_NAMES = ["imap_list", "imap_get", "imap_search", "imap_mail_send"] as const;

package/connectors/intercom/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.intercom",
+  "displayName": "Intercom",
+  "version": "0.1.0",
+  "description": "Intercom support connector (read-only). Surfaces the user's recent Intercom conversations as `intercom:conversation` items in the local index — the conversation subject/title, state (open/closed/snoozed), priority, the read flag, the source message author + first message body, the linked contact ids, the admin + team assignees, tags, and the created / updated dates. Useful for answering support questions (\"what conversations are still open?\", \"find the thread about the billing bug\") without leaving Nimbus. Bearer access-token auth (`Authorization: Bearer <token>` — an Intercom Access Token; never logged) plus the `Intercom-Version: 2.11` and `Accept: application/json` request headers. The SaaS host (api.intercom.io, US) is fixed — EU/AU regional hosts are a deferred follow-up. Intercom paginates the `/conversations` endpoint with a cursor (`pages.next.starting_after`, per_page=150), returning the `{ type: \"conversation.list\", conversations, pages, total_count }` envelope. `created_at` / `updated_at` are epoch SECONDS (converted to epoch-ms on index). Contacts / companies / tickets / admins-as-items and write tools are deferred follow-ups; v1 indexes conversations only.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.intercom.io"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,46 @@
+import {
+  asObjectish,
+  asRecord,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type IntercomSearchMatchOptions = SearchMatchOptions;
+
+function tagText(row: Record<string, unknown>): string {
+  const tags = asRecord(row["tags"]);
+  const list = tags === undefined ? undefined : tags["tags"];
+  if (!Array.isArray(list)) {
+    return "";
+  }
+  const names: string[] = [];
+  for (const t of list) {
+    const obj = asRecord(t);
+    if (obj === undefined) {
+      continue;
+    }
+    const name = obj["name"];
+    if (typeof name === "string") {
+      names.push(name);
+    }
+  }
+  return names.join(" ");
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  const state = stringField(row, "state");
+  const source = asRecord(row["source"]) ?? {};
+  const subject = stringField(source, "subject");
+  const body = stringField(source, "body");
+  const author = asRecord(source["author"]) ?? {};
+  const authorName = stringField(author, "name");
+  const authorEmail = stringField(author, "email");
+  return [subject, body, state, authorName, authorEmail, tagText(row)];
+}
+
+export const filterIntercomConversations = makeQueryFilter(fieldsOf);

package/connectors/intercom/src/server.ts

@@ -0,0 +1,65 @@
+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;
+}
+
+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);
+    },
+  );
+});

package/connectors/jenkins/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.jenkins",
+  "displayName": "Jenkins",
+  "version": "0.1.0",
+  "description": "Jenkins CI connector (jobs, builds, queue). Always self-hosted — the target host is read from jenkins.base_url at spawn time and merged into permissions.network by the Gateway. Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": []
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 120,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,156 @@
+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);
+}
+
+export function jenkinsAuthHeader(): string {
+  const user = process.env["JENKINS_USERNAME"]?.trim() ?? "";
+  const token = process.env["JENKINS_API_TOKEN"]?.trim() ?? "";
+  if (user === "" || token === "") {
+    throw new Error("JENKINS_USERNAME and JENKINS_API_TOKEN must be set");
+  }
+  return encodeBasicAuthHeader(user, token);
+}
+
+export type JenkinsCrumb = { field: string; value: string };
+
+/** RFC 7230 `token`: the only characters an HTTP header field name may contain. */
+const HEADER_NAME_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+/**
+ * Whether `name` is safe to use as a header field name.
+ *
+ * The crumb field name is chosen by the REMOTE Jenkins (`crumbRequestField` in the crumb-issuer
+ * response), so it is attacker-controlled input on a compromised or hostile server — and it lands
+ * in a computed property write. Two things are refused:
+ *
+ *  - anything that is not an RFC 7230 token, which is what stops a name carrying `:` or CR/LF from
+ *    injecting extra headers into an authenticated POST;
+ *  - `__proto__` / `constructor` / `prototype`, which reach `Object.prototype` through a computed
+ *    assignment rather than creating an own property.
+ *
+ * No real crumb field is named any of those, so nothing legitimate is lost.
+ */
+export function isSafeHeaderName(name: string): boolean {
+  const lower = name.toLowerCase();
+  if (lower === "__proto__" || lower === "constructor" || lower === "prototype") {
+    return false;
+  }
+  return HEADER_NAME_RE.test(name);
+}
+
+let crumbCache: JenkinsCrumb | null | undefined;
+
+export function __resetJenkinsCrumbCacheForTests(): void {
+  crumbCache = undefined;
+}
+
+export async function getJenkinsCrumb(
+  base: string,
+  authHeader: string,
+): Promise<JenkinsCrumb | null> {
+  if (crumbCache !== undefined) {
+    return crumbCache;
+  }
+  const res = await fetch(`${base}/crumbIssuer/api/json`, {
+    headers: { Authorization: authHeader, Accept: "application/json" },
+  });
+  if (!res.ok) {
+    crumbCache = null;
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = (await res.json()) as unknown;
+  } catch {
+    crumbCache = null;
+    return null;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    crumbCache = null;
+    return null;
+  }
+  const o = parsed as Record<string, unknown>;
+  const crumb = typeof o["crumb"] === "string" ? o["crumb"] : "";
+  const field = typeof o["crumbRequestField"] === "string" ? o["crumbRequestField"] : "";
+  // A field name the crumb cannot legally carry is treated exactly like a missing one: no crumb.
+  // The POST then goes out without it and Jenkins answers 403, which is the safe outcome — far
+  // better than letting the server name an arbitrary header on our authenticated request.
+  if (crumb === "" || !isSafeHeaderName(field)) {
+    crumbCache = null;
+    return null;
+  }
+  crumbCache = { field, value: crumb };
+  return crumbCache;
+}
+
+export function jobPathFromFullName(fullName: string): string {
+  const segs = fullName
+    .split("/")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  if (segs.length === 0) {
+    throw new Error("job fullName is empty");
+  }
+  return segs.map((s) => encodeURIComponent(s)).join("/job/");
+}
+
+export function jobApiRoot(base: string, fullName: string): string {
+  return `${base}/job/${jobPathFromFullName(fullName)}`;
+}
+
+export async function jenkinsFetchJson(
+  url: string,
+  init: RequestInit & { authHeader: string },
+): Promise<{ ok: boolean; status: number; text: string; json: unknown }> {
+  const { authHeader, ...rest } = init;
+  const res = await fetch(url, {
+    ...rest,
+    headers: {
+      Authorization: authHeader,
+      Accept: "application/json",
+      ...(rest.headers as Record<string, string>),
+    },
+  });
+  const text = await res.text();
+  let parsedBody: unknown = null;
+  try {
+    parsedBody = JSON.parse(text) as unknown;
+  } catch {
+    parsedBody = null;
+  }
+  return { ok: res.ok, status: res.status, text, json: parsedBody };
+}
+
+export async function jenkinsPost(
+  url: string,
+  authHeader: string,
+  crumb: JenkinsCrumb | null,
+): Promise<{ ok: boolean; status: number; text: string }> {
+  // A `Headers` instance, NOT a plain object with a computed write.
+  //
+  // The crumb field name is chosen by the REMOTE Jenkins, so it is attacker-controlled on a hostile
+  // server. Writing it as `obj[name] = value` on an object literal reaches `Object.prototype`
+  // through the accessor for `__proto__` — the shape `tssecurity:S6109` exists to catch, and which
+  // it still reported against the guarded version of this code because a taint analyser cannot see
+  // that `isSafeHeaderName` sanitises.
+  //
+  // `Headers.set` cannot write a prototype: the name goes into the header map, never onto an
+  // object, so the class of bug is gone by construction rather than by a guard the analyser has to
+  // recognise. It also validates the name itself per RFC 7230 and THROWS on an invalid one, which
+  // is why `isSafeHeaderName` stays in front of it — a hostile crumb should mean "no crumb", not a
+  // thrown TypeError out of `jenkinsPost`.
+  const headers = new Headers({ Authorization: authHeader });
+  if (crumb !== null && isSafeHeaderName(crumb.field)) {
+    headers.set(crumb.field, crumb.value);
+  }
+  const res = await fetch(url, { method: "POST", headers });
+  const text = await res.text();
+  return { ok: res.ok, status: res.status, text };
+}