@nimbus-dev/connectors 0.1.0

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

@@ -0,0 +1,65 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type GreenhouseSearchMatchOptions = SearchMatchOptions;
+
+function namedArrayText(row: Record<string, unknown>, key: string): string {
+  const arr = row[key];
+  if (!Array.isArray(arr)) {
+    return "";
+  }
+  const names: string[] = [];
+  for (const e of arr) {
+    if (e === null || typeof e !== "object" || Array.isArray(e)) {
+      continue;
+    }
+    const name = (e as Record<string, unknown>)["name"];
+    if (typeof name === "string") {
+      names.push(name);
+    }
+  }
+  return names.join(" ");
+}
+
+function officeLocationText(row: Record<string, unknown>): string {
+  const arr = row["offices"];
+  if (!Array.isArray(arr)) {
+    return "";
+  }
+  const locs: string[] = [];
+  for (const e of arr) {
+    if (e === null || typeof e !== "object" || Array.isArray(e)) {
+      continue;
+    }
+    const loc = (e as Record<string, unknown>)["location"];
+    if (loc === null || typeof loc !== "object" || Array.isArray(loc)) {
+      continue;
+    }
+    const name = (loc as Record<string, unknown>)["name"];
+    if (typeof name === "string") {
+      locs.push(name);
+    }
+  }
+  return locs.join(" ");
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [
+    stringField(row, "name"),
+    stringField(row, "status"),
+    stringField(row, "requisition_id"),
+    namedArrayText(row, "departments"),
+    namedArrayText(row, "offices"),
+    officeLocationText(row),
+  ];
+}
+
+export const filterGreenhouseJobs = makeQueryFilter(fieldsOf);

package/connectors/greenhouse/src/server.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { matchesResult, searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
+import {
+  encodeBasicAuthHeader,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
+import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterGreenhouseJobs } from "./search-filter.ts";
+
+const BASE = "https://harvest.greenhouse.io";
+
+function apiKey(): string {
+  const t = process.env["GREENHOUSE_API_KEY"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("GREENHOUSE_API_KEY is not set");
+  }
+  return t;
+}
+
+function authHeader(): Record<string, string> {
+  return { Authorization: encodeBasicAuthHeader(apiKey(), ""), Accept: "application/json" };
+}
+
+async function greenhouseGet(path: string): Promise<unknown> {
+  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Greenhouse ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+await runReadOnlyMcpConnector("nimbus-greenhouse", (reg) => {
+  reg(
+    "greenhouse_list",
+    "List the company's Greenhouse Harvest job openings (`GET /v1/jobs?per_page=100`). Returns a bare JSON array of job objects (NOT an envelope), each carrying the name, status, requisition id, departments, and offices.",
+    z.object({
+      per_page: z.number().int().min(1).max(100).optional(),
+    }),
+    async (p) => {
+      const search = new URLSearchParams({ per_page: String(p.per_page ?? 100), page: "1" });
+      return jsonResult(await greenhouseGet(`/v1/jobs?${search.toString()}`));
+    },
+  );
+
+  reg(
+    "greenhouse_get",
+    "Fetch one Greenhouse job by its id (`GET /v1/jobs/{id}`). Returns the job object directly. Throws when no match is found.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await greenhouseGet(`/v1/jobs/${encodeURIComponent(p.id)}`));
+    },
+  );
+
+  reg(
+    "greenhouse_search",
+    "Substring search across the company's Greenhouse job openings (first page only). Matches the query against the job name, status, requisition id, the department names, and the office names + locations (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const search = new URLSearchParams({ per_page: "100", page: "1" });
+      const root = await greenhouseGet(`/v1/jobs?${search.toString()}`);
+      return matchesResult(root, filterGreenhouseJobs, p);
+    },
+  );
+});

package/connectors/hubspot/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.hubspot",
+  "displayName": "HubSpot",
+  "version": "0.1.0",
+  "description": "HubSpot CRM connector (read-only). Surfaces the authenticated portal's deals as hubspot:deal items in the local index via GET /crm/v3/objects/deals — the deal name, the amount, the deal stage, the pipeline, the close date, the create date, and the last-modified timestamp. Bearer OAuth auth (Authorization: Bearer <token>; short-lived access token refreshed by the Gateway via the 3-legged OAuth authorization-code flow; never logged); fixed SaaS host api.hubapi.com. The list endpoint paginates by the paging.next.after cursor until absent; the gateway-side syncable walks a single forward pass per cycle, page-capped. Read-only — hitlRequired is intentionally empty. Sparse structured pipeline/spend metadata; deal URLs require a portal id the API does not return, so url/canonical_url are null.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.hubapi.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,28 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type HubspotSearchMatchOptions = SearchMatchOptions;
+
+/**
+ * HubSpot deal objects nest their searchable text under a `properties` map:
+ * `{ id, properties: { dealname, dealstage, pipeline, ... } }`. Match against the
+ * deal name, stage, and pipeline (case-insensitive substring).
+ */
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  const props = asObjectish(row["properties"]) ?? {};
+  return [
+    stringField(props, "dealname"),
+    stringField(props, "dealstage"),
+    stringField(props, "pipeline"),
+  ];
+}
+
+export const filterHubspotDeals = makeQueryFilter(fieldsOf);

package/connectors/hubspot/src/server.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { 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 { filterHubspotDeals } from "./search-filter.ts";
+
+const BASE = "https://api.hubapi.com";
+const DEAL_PROPERTIES =
+  "dealname,amount,dealstage,pipeline,closedate,createdate,hs_lastmodifieddate";
+
+function apiToken(): string {
+  const t = process.env["HUBSPOT_TOKEN"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("HUBSPOT_TOKEN is not set");
+  }
+  return t;
+}
+
+function authHeader(): Record<string, string> {
+  return { Authorization: `Bearer ${apiToken()}`, Accept: "application/json" };
+}
+
+async function hubspotGet(path: string): Promise<unknown> {
+  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`HubSpot ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function dealsFrom(root: unknown): unknown[] {
+  const results = (root as { results?: unknown } | null)?.results;
+  return Array.isArray(results) ? results : [];
+}
+
+await runReadOnlyMcpConnector("nimbus-hubspot", (reg) => {
+  reg(
+    "hubspot_list",
+    "List the authenticated portal's HubSpot deals (GET /crm/v3/objects/deals?limit=N&properties=dealname,amount,dealstage,pipeline,closedate,createdate,hs_lastmodifieddate). Returns the { results: [...], paging?: { next?: { after } } } envelope — `results` holds the deal objects, each shaped { id, properties: { dealname, amount, dealstage, pipeline, closedate, createdate, hs_lastmodifieddate }, createdAt, updatedAt }. `limit` (default 100, max 100) caps page_size of the single first-page request.",
+    z.object({
+      limit: z.number().int().min(1).max(100).optional(),
+    }),
+    async (p) => {
+      const params = new URLSearchParams({
+        limit: String(p.limit ?? 100),
+        properties: DEAL_PROPERTIES,
+      });
+      return jsonResult(await hubspotGet(`/crm/v3/objects/deals?${params.toString()}`));
+    },
+  );
+
+  reg(
+    "hubspot_get",
+    "Fetch one HubSpot deal by its id (GET /crm/v3/objects/deals/{dealId}?properties=dealname,amount,dealstage,pipeline,closedate,createdate,hs_lastmodifieddate). Returns the deal object directly (NOT wrapped in `results`). Throws when no deal with that id exists.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      const params = new URLSearchParams({ properties: DEAL_PROPERTIES });
+      return jsonResult(
+        await hubspotGet(`/crm/v3/objects/deals/${encodeURIComponent(p.id)}?${params.toString()}`),
+      );
+    },
+  );
+
+  reg(
+    "hubspot_search",
+    "**Substring search over the FIRST PAGE only** (up to 100 most-recently-listed deals) of the authenticated portal's HubSpot deals. This tool fetches GET /crm/v3/objects/deals?limit=100 once and matches the query locally (case-insensitive) against the deal name, deal stage, and pipeline. **Deals beyond the first page are not searchable here — query the local Nimbus index instead for full coverage.** Returns a { matches: [...] } envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const params = new URLSearchParams({ limit: "100", properties: DEAL_PROPERTIES });
+      const root = await hubspotGet(`/crm/v3/objects/deals?${params.toString()}`);
+      const matches = filterHubspotDeals(dealsFrom(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+});

package/connectors/iac/nimbus.extension.json

@@ -0,0 +1,14 @@
+{
+  "id": "com.nimbus.iac",
+  "displayName": "Infrastructure-as-Code",
+  "version": "0.1.0",
+  "description": "Terraform / Pulumi / OpenTofu CLI helpers. The connector itself opens no sockets; CLI subprocesses' network access is sandbox-bounded. Workspace paths are tool-call scoped (workingDirectory argument), not baked into the manifest. Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": []
+  },
+  "hitlRequired": ["write", "delete"],
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/iac/src/server.ts

@@ -0,0 +1,145 @@
+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 { runCliOkThrowing } from "../../../shared/run-cli-json.ts";
+
+const mcp = new McpServer({ name: "nimbus-iac", version: "0.1.0" });
+
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+
+const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
+
+/**
+ * Every MUTATING iac 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: "iac",
+  scopeEnv: "NIMBUS_MCP_IAC_WRITE_SCOPE",
+  scopeKinds: ["dir", "stack"],
+});
+
+const processEnv = process.env as Record<string, string | undefined>;
+
+reg(
+  "iac_terraform_plan",
+  "Run terraform plan in a directory.",
+  z.object({ workingDirectory: z.string().min(1) }),
+  async (p) => {
+    await runCliOkThrowing(["terraform", "-chdir", p.workingDirectory, "plan", "-input=false"], {
+      ...processEnv,
+    });
+    return jsonResult({ ok: true });
+  },
+);
+
+registerWriteTool(
+  "iac_terraform_apply",
+  {
+    mutates: "iac.terraform.apply",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "dir", value: p.workingDirectory }),
+  },
+  "Run terraform apply.",
+  z.object({ workingDirectory: z.string().min(1) }),
+  async (p) => {
+    await runCliOkThrowing(
+      ["terraform", "-chdir", p.workingDirectory, "apply", "-auto-approve", "-input=false"],
+      { ...processEnv },
+    );
+    return jsonResult({ ok: true });
+  },
+);
+
+registerWriteTool(
+  "iac_terraform_destroy",
+  {
+    mutates: "iac.terraform.destroy",
+    // Destroying infrastructure cannot be undone from its own result, and there is nothing
+    // queryable to snapshot, so the identifying parameters ARE the pre-state: a record naming
+    // WHICH directory was destroyed still beats silence.
+    recoverable: false,
+    capturePreState: (p) => Promise.resolve({ workingDirectory: p.workingDirectory }),
+    scopeTargetOf: (p) => ({ kind: "dir", value: p.workingDirectory }),
+  },
+  "Run terraform destroy.",
+  z.object({ workingDirectory: z.string().min(1) }),
+  async (p) => {
+    await runCliOkThrowing(
+      ["terraform", "-chdir", p.workingDirectory, "destroy", "-auto-approve", "-input=false"],
+      { ...processEnv },
+    );
+    return jsonResult({ ok: true });
+  },
+);
+
+registerWriteTool(
+  "iac_cloudformation_deploy",
+  {
+    mutates: "iac.cloudformation.deploy",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "stack", value: p.stackName }),
+  },
+  "Deploy a CloudFormation stack via AWS CLI.",
+  z.object({
+    stackName: z.string().min(1),
+    templateBody: z.string().min(1),
+  }),
+  async (p) => {
+    await runCliOkThrowing(
+      [
+        "aws",
+        "cloudformation",
+        "deploy",
+        "--stack-name",
+        p.stackName,
+        "--template-body",
+        p.templateBody,
+        "--capabilities",
+        "CAPABILITY_IAM",
+      ],
+      { ...processEnv },
+    );
+    return jsonResult({ ok: true });
+  },
+);
+
+reg(
+  "iac_pulumi_preview",
+  "Run pulumi preview in a stack directory.",
+  z.object({ workingDirectory: z.string().min(1) }),
+  async (p) => {
+    await runCliOkThrowing(
+      ["pulumi", "preview", "--cwd", p.workingDirectory, "--non-interactive"],
+      { ...processEnv },
+    );
+    return jsonResult({ ok: true });
+  },
+);
+
+registerWriteTool(
+  "iac_pulumi_up",
+  {
+    mutates: "iac.pulumi.up",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "dir", value: p.workingDirectory }),
+  },
+  "Run pulumi up.",
+  z.object({ workingDirectory: z.string().min(1) }),
+  async (p) => {
+    await runCliOkThrowing(
+      ["pulumi", "up", "--yes", "--cwd", p.workingDirectory, "--non-interactive"],
+      { ...processEnv },
+    );
+    return jsonResult({ ok: true });
+  },
+);
+
+const transport = new StdioServerTransport();
+await mcp.connect(transport);

package/connectors/imap/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.imap",
+  "displayName": "IMAP / SMTP Email",
+  "version": "0.1.0",
+  "description": "Generic IMAP/SMTP email connector (Tier-4 EMAIL class). Indexes the user's mailbox over raw IMAP as `imap:email` items — message HEADERS (subject, from, to/cc, date, message-id), a short capped plain-text body PREVIEW (~2 KB / 2000 chars), and attachment METADATA only (filename, size, mimetype). It NEVER downloads or parses attachment bytes and never fetches the full message body: it uses the IMAP ENVELOPE + BODYSTRUCTURE for headers and attachment metadata, and fetches only a truncated text/plain body part for the preview. Read tools (`imap_list`, `imap_get`, `imap_search`) plus one HITL-gated write tool (`imap_mail_send`) that sends mail over SMTP via nodemailer. IMAP/SMTP credentials are per-tenant (host, port, username, password) and arrive as scoped environment variables injected at spawn time (IMAP_HOST/IMAP_PORT/IMAP_USERNAME/IMAP_PASSWORD and IMAP_SMTP_*) — the connector never reads the vault. Because the IMAP/SMTP hosts are user-configured and non-443 (IMAP 993, SMTP 465/587), the static manifest network list is intentionally empty: the concrete <imap.host>:993 + <smtp.host>:<port> host:port entries are added to the sandbox network allow-list at spawn time by phase3AddImapMcp via manifestWithExtraNetworkHosts.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": [],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "hitlRequired": ["write"],
+  "syncInterval": 300,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/imap/src/imap-core.ts

@@ -0,0 +1,110 @@
+/**
+ * IMAP/SMTP connector core — transport-agnostic logic for the read tools
+ * (`imap_list`, `imap_get`, `imap_search`) and the HITL-gated send tool
+ * (`imap_mail_send`).
+ *
+ * HARD SCOPE CONSTRAINT (security): this connector indexes HEADERS + a short
+ * capped plain-text body PREVIEW + attachment METADATA only. It NEVER downloads
+ * or parses attachment bytes and never fetches the full message body. The IMAP
+ * client interface below deliberately exposes only `envelope` + `bodyStructure`
+ * (headers / attachment metadata) and a single truncated text body part for the
+ * preview — there is no surface to request `BODY[]` or an attachment part.
+ *
+ * The IMAP client and SMTP mailer are injected so tests never open real sockets.
+ */
+
+import type { MailAddress } from "../../../shared/imap-mail-core.ts";
+
+export {
+  capPreview,
+  clampLimit,
+  formatAddress,
+  PREVIEW_FETCH_BYTES,
+  PREVIEW_MAX_CHARS,
+} from "../../../shared/imap-mail-core.ts";
+
+/** One parsed address (name optional). */
+export type ImapAddress = MailAddress;
+
+/** Message ENVELOPE — RFC 2822 header fields only. */
+export interface ImapEnvelope {
+  readonly date?: Date | string | null;
+  readonly subject?: string | null;
+  readonly messageId?: string | null;
+  readonly from?: readonly ImapAddress[];
+  readonly to?: readonly ImapAddress[];
+  readonly cc?: readonly ImapAddress[];
+}
+
+/**
+ * Attachment METADATA only — filename, size, mimetype. NEVER the bytes.
+ * Derived from BODYSTRUCTURE.
+ */
+export interface ImapAttachmentMeta {
+  readonly filename: string | null;
+  readonly sizeBytes: number | null;
+  readonly mimeType: string | null;
+}
+
+/**
+ * A single mailbox message reduced to header + attachment-metadata + a capped
+ * text preview. This is the ONLY shape the connector ever materializes; it has
+ * no field that could carry attachment content or a full body.
+ */
+export interface ImapMessageMeta {
+  readonly uid: number;
+  readonly mailbox: string;
+  readonly uidValidity: string | null;
+  readonly envelope: ImapEnvelope;
+  readonly attachments: readonly ImapAttachmentMeta[];
+  /** Plain-text body preview, already capped to {@link PREVIEW_MAX_CHARS}. */
+  readonly preview: string;
+}
+
+/** Listing options. */
+export interface ImapListOptions {
+  readonly mailbox?: string;
+  readonly limit?: number;
+}
+
+/** Search options — searches header/envelope fields, never document/body content scans. */
+export interface ImapSearchOptions {
+  readonly query: string;
+  readonly mailbox?: string;
+  readonly limit?: number;
+}
+
+/**
+ * Minimal IMAP client surface the connector depends on. Implemented for real by
+ * the imapflow adapter in `server.ts` and by a fake in tests. Deliberately
+ * exposes ONLY header/attachment-metadata + capped-preview reads.
+ */
+export interface ImapClient {
+  /** List the most recent messages (header + attachment metadata + preview). */
+  list(options: ImapListOptions): Promise<ImapMessageMeta[]>;
+  /** Fetch one message's header + attachment metadata + preview by uid. */
+  get(uid: number, mailbox?: string): Promise<ImapMessageMeta | null>;
+  /** Search by subject/from/to substring; returns matching message metas. */
+  search(options: ImapSearchOptions): Promise<ImapMessageMeta[]>;
+}
+
+/** Outgoing message for the SMTP send tool. */
+export interface SendMailInput {
+  readonly to: string;
+  readonly subject: string;
+  readonly body: string;
+  readonly cc?: string;
+  readonly bcc?: string;
+}
+
+/** Result of a send (message id assigned by the SMTP server, if any). */
+export interface SendMailResult {
+  readonly messageId: string | null;
+  readonly accepted: readonly string[];
+  readonly rejected: readonly string[];
+}
+
+/** Minimal SMTP mailer surface; implemented for real over nodemailer. */
+export interface SmtpMailer {
+  send(input: SendMailInput): Promise<SendMailResult>;
+}