@nimbus-dev/connectors 0.1.0

package/NOTICE

@@ -0,0 +1,40 @@
+Nimbus first-party MCP connectors
+Copyright (C) Nimbus contributors
+Licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only).
+
+SECURITY TIERING — please preserve this notice.
+
+Run STANDALONE (outside the Nimbus gateway), these connectors provide:
+
+  * consent for every mutating tool, via MCP elicitation, rendered by YOUR MCP
+    client;
+  * a server-enforced write-scope allow-list and a per-session mutation budget,
+    which hold regardless of client behaviour;
+  * a local, hash-chained, append-only audit log.
+
+Run standalone, they DO NOT provide:
+
+  * the process sandbox (network allow-list and filesystem confinement) — this
+    is a property of how the Nimbus gateway spawns a connector, and no package
+    can supply it;
+  * OS-keychain credential storage — standalone credentials come from
+    environment variables supplied by whoever configures the MCP client;
+  * the egress ledger — the tamper-evident record of every outbound action;
+  * owner-controlled consent — standalone consent is mediated by your MCP
+    client, which may be configured to answer automatically.
+
+Those four require the Nimbus gateway:
+
+    https://github.com/nimbus-agent/Nimbus
+
+If a client does not advertise the MCP `elicitation` capability, mutating tools
+are NOT REGISTERED AT ALL. That is deliberate, not a defect: a tool the model
+cannot see is a tool it cannot call without a human.
+
+Connectors whose mutating tools have not yet been routed through the consent
+kit refuse to start standalone. They remain fully available through the
+gateway, which gates them.
+
+"Nimbus" is a trademark of the Nimbus project. This licence grants no trademark
+rights; a modified version that removes these protections must not be described
+as Nimbus-grade or imply endorsement by the Nimbus project.

package/README.md

@@ -0,0 +1,111 @@
+# Nimbus MCP Servers
+
+Standalone, MCP-standard [**Nimbus**](https://github.com/nimbus-agent/Nimbus) connectors — usable by
+**any** MCP client (Claude Code, Cursor, Claude Desktop, …), not just the Nimbus gateway.
+
+All **94** connectors ship in one package, `@nimbus-dev/connectors`, each runnable standalone over
+stdio with credentials supplied from the environment.
+
+```bash
+npx @nimbus-dev/connectors github
+```
+
+## What you get, and what you do not
+
+Run standalone, a connector gives you:
+
+- **Consent before every mutation.** A write tool asks your MCP client to put the exact operation and
+  parameters in front of you, and does nothing unless you approve.
+- **A write-scope allow-list**, enforced by the server and unreachable by the model.
+- **A mutation budget** per session, which caps a runaway agent loop.
+- **A local, hash-chained, append-only audit log**, when `NIMBUS_MCP_AUDIT_LOG` is set.
+
+It does **not** give you the process sandbox, OS-keychain credential storage, the egress ledger, or
+owner-controlled consent. Those are properties of the Nimbus gateway and no published package can
+supply them. [`NOTICE`](./NOTICE) states the tiering that notice asks you to preserve.
+
+## Writes depend on your client
+
+Reads work everywhere. **Writes require your client to implement the MCP `elicitation` capability**,
+because that is the only way a server can put a consent prompt in front of you. Without it, write
+tools are **not registered at all** rather than offered ungated — deliberate, not a defect: a tool
+the model cannot see is one it cannot call without a human.
+
+**Claude Desktop does not implement elicitation today**, so you get reads only there. Claude Code and
+Cursor do, per their vendor docs.
+
+Checking your own client takes one query: ask it to list the connector's tools. If the write tools are
+absent, your client does not implement elicitation.
+
+Full matrix, versions tested, and the provenance of each claim:
+[Client support](./docs/client-support.md).
+
+## Configuration
+
+```json
+{
+  "mcpServers": {
+    "nimbus-github": {
+      "command": "npx",
+      "args": ["-y", "@nimbus-dev/connectors", "github"],
+      "env": {
+        "GITHUB_PAT": "ghp_...",
+        "NIMBUS_MCP_GITHUB_WRITE_SCOPE": "repo:acme/api",
+        "NIMBUS_MCP_AUDIT_LOG": "/absolute/path/to/nimbus-mcp-audit.jsonl"
+      }
+    }
+  }
+}
+```
+
+Credentials come from the environment. There is no Vault outside the gateway, so whoever writes this
+config holds the secret. Every variable, and the two behaviours that look like bugs and are not, are
+in [Configuration](./docs/configuration.md).
+
+Each connector documents its own tools and credentials at `connectors/<id>/README.md`.
+
+## Documentation
+
+| Page | Read it when |
+| --- | --- |
+| [Architecture](./docs/architecture.md) | You want the layout, or how a connector is put together. |
+| [Client support](./docs/client-support.md) | Write tools are missing, or you need to know if your client can approve a mutation. |
+| [Configuration](./docs/configuration.md) | You are wiring a connector into a client. |
+| [Standalone launcher](./docs/standalone-launcher.md) | You want `nimbus-connector`: eligibility, exit codes, refusals. |
+| [Adding a connector](./docs/adding-a-connector.md) | You are writing or changing a connector. |
+| [Publishing](./docs/publishing.md) | You are cutting a release. |
+
+## Development
+
+```bash
+bun install
+bun run check   # lint, typecheck, consent audit, full suite
+```
+
+CI runs those four on Ubuntu, macOS and Windows — platform equality is a Nimbus non-negotiable.
+
+## Relationship to the Nimbus monorepo
+
+The connectors are developed here and consumed by the gateway from npm. The gateway's per-connector
+**sync and indexing** intelligence stays in
+[nimbus-agent/Nimbus](https://github.com/nimbus-agent/Nimbus) — this repo holds the MCP tool surface,
+which is the part that is useful without a gateway. Adding a connector therefore touches both repos.
+
+Not to be confused with [`nimbus-mcp`](https://github.com/nimbus-agent/nimbus-mcp), which exposes
+your local Nimbus **index and agents** to an MCP client. This repo is the other direction: the
+connectors that reach your tools.
+
+## History
+
+This repo was a scaffold from 2026-06-18 until the connectors landed. Its original README posed three
+"decisions to make first" — share-vs-vendor-vs-fork, the credential model outside the Vault, and the
+AGPL implications for downstream clients. All three were answered before the move: the connectors are
+consent-gated standalone, credentials come from the environment, and `NOTICE` states the tiering. It
+also proposed a package per connector; one package was chosen instead, because 94 packages means 94
+releases and forces `shared/` to become a versioned dependency that 190 files import by relative path.
+
+## License
+
+[AGPL-3.0-only](./LICENSE), and [`NOTICE`](./NOTICE) records the security tiering — please preserve
+it. "Nimbus" is a trademark of the Nimbus project; this licence grants no trademark rights, and a
+modified version that removes these protections must not be described as Nimbus-grade.

package/connectors/airflow/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.airflow",
+  "displayName": "Apache Airflow",
+  "version": "0.1.0",
+  "description": "Apache Airflow connector (read-only). Surfaces the user's data-orchestration DAGs from a self-hosted Airflow instance as `airflow:dag` items in the local index — the dag_id, paused/active flags, owners, description, schedule interval, tags, source file location, next scheduled run, and last-parsed timestamp. Useful for answering orchestration questions (\"which DAGs are paused?\", \"what's the schedule for the nightly ETL?\") without leaving Nimbus. Airflow HTTP Basic auth (username + password). Airflow has no universal SaaS host: the server host is supplied via the airflow base-url vault key and added to the sandbox network list at spawn time by phase3AddAirflowMcp, so the static manifest network list is intentionally empty. The stable REST API v1 /api/v1/dags endpoint paginates by limit / offset with a total_entries count in the response body; the connector walks a single forward offset pass per cycle, capped. v1 indexes DAG definitions only — individual DAG runs and task instances are a deferred follow-up. No write tools.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": [],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,38 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+  tagNamesFromObjects,
+} from "../../../shared/search-filter.ts";
+
+export type AirflowSearchMatchOptions = SearchMatchOptions;
+
+function ownerNames(row: Record<string, unknown>): string {
+  const owners = row["owners"];
+  if (!Array.isArray(owners)) {
+    return "";
+  }
+  const names: string[] = [];
+  for (const o of owners) {
+    if (typeof o === "string" && o !== "") {
+      names.push(o);
+    }
+  }
+  return names.join(" ");
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [
+    stringField(row, "dag_id"),
+    stringField(row, "description"),
+    ownerNames(row),
+    tagNamesFromObjects(row),
+  ];
+}
+
+export const filterAirflowDags = makeQueryFilter(fieldsOf);

package/connectors/airflow/src/server.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { 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 { filterAirflowDags } from "./search-filter.ts";
+
+function trimTrailingSlash(s: string): string {
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+
+function apiBase(): string {
+  const v = process.env["AIRFLOW_URL"]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error("AIRFLOW_URL is not set");
+  }
+  return trimTrailingSlash(v);
+}
+
+function authHeader(): Record<string, string> {
+  const user = process.env["AIRFLOW_USERNAME"]?.trim();
+  if (user === undefined || user === "") {
+    throw new Error("AIRFLOW_USERNAME is not set");
+  }
+  const password = process.env["AIRFLOW_PASSWORD"]?.trim();
+  if (password === undefined || password === "") {
+    throw new Error("AIRFLOW_PASSWORD is not set");
+  }
+  return {
+    Authorization: encodeBasicAuthHeader(user, password),
+    Accept: "application/json",
+  };
+}
+
+async function airflowGet(path: string): Promise<unknown> {
+  const res = await fetch(`${apiBase()}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Airflow ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function dagsFrom(root: unknown): unknown[] {
+  const dags = (root as { dags?: unknown } | null)?.dags;
+  return Array.isArray(dags) ? dags : [];
+}
+
+await runReadOnlyMcpConnector("nimbus-airflow", (reg) => {
+  reg(
+    "airflow_list",
+    "List Airflow DAGs (GET /api/v1/dags?limit=100&offset=<n>). The Airflow stable REST API v1 returns the envelope { dags: [...], total_entries: <int> } — `dags` holds the DAG objects, `total_entries` the total across all pages. The optional offset arg (default 0) selects the page start; limit is fixed at 100.",
+    z.object({
+      offset: z.number().int().min(0).optional(),
+    }),
+    async (p) => {
+      const offset = p.offset ?? 0;
+      const root = await airflowGet(
+        `/api/v1/dags?limit=100&offset=${encodeURIComponent(String(offset))}`,
+      );
+      return jsonResult({ items: dagsFrom(root) });
+    },
+  );
+
+  reg(
+    "airflow_get",
+    "Fetch one Airflow DAG by its dag_id (GET /api/v1/dags/{dag_id}). Returns the DAG object directly (NOT wrapped in an envelope). Throws when no DAG with that id exists.",
+    z.object({
+      dag_id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await airflowGet(`/api/v1/dags/${encodeURIComponent(p.dag_id)}`));
+    },
+  );
+
+  reg(
+    "airflow_search",
+    "Substring search across the first page of Airflow DAGs. Matches the query (case-insensitive) against the dag_id, description, owners, and tag names. Returns a matches envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const root = await airflowGet("/api/v1/dags?limit=100&offset=0");
+      const matches = filterAirflowDags(dagsFrom(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+});

package/connectors/apple/nimbus.extension.json

@@ -0,0 +1,40 @@
+{
+  "id": "com.nimbus.apple",
+  "displayName": "iCloud Mail + Calendar",
+  "version": "0.1.0",
+  "description": "iCloud Mail (IMAP/SMTP) + iCloud Calendar (CalDAV) connector. Indexes iCloud Mail as `apple: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). Indexes iCloud Calendar as `apple:event` items — summary, start/end, location, organizer, status, recurrence, attendee emails, and a ≤2000-char notes preview. It NEVER downloads attachment bytes, never fetches full message bodies, and never returns full event descriptions beyond the capped preview. Read tools: `apple_list`, `apple_get`, `apple_search` (mail) and `apple_calendar_list` (calendar). Four HITL-gated write tools: `apple_mail_send` (SMTP), `apple_mail_draft_create` (IMAP APPEND to Drafts), `apple_calendar_event_create` (CalDAV PUT), `apple_calendar_event_delete` (CalDAV DELETE). Credentials are a single Apple ID email + app-specific password authenticating IMAP (imap.mail.me.com:993 TLS), SMTP (smtp.mail.me.com:587 STARTTLS), and CalDAV (caldav.icloud.com). The sender From address is always pinned to the authenticated icloud_email (callers cannot override it). Credentials arrive as scoped environment variables injected at spawn time (APPLE_ICLOUD_EMAIL, APPLE_ICLOUD_APP_PASSWORD) — the connector never reads the vault.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": [
+      "imap.mail.me.com:993",
+      "smtp.mail.me.com:587",
+      "caldav.icloud.com:443",
+      "p01-caldav.icloud.com:443",
+      "p02-caldav.icloud.com:443",
+      "p03-caldav.icloud.com:443",
+      "p04-caldav.icloud.com:443",
+      "p05-caldav.icloud.com:443",
+      "p06-caldav.icloud.com:443",
+      "p07-caldav.icloud.com:443",
+      "p08-caldav.icloud.com:443",
+      "p09-caldav.icloud.com:443",
+      "p10-caldav.icloud.com:443"
+    ],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "tools": {
+    "apple_list": { "hitl": false },
+    "apple_get": { "hitl": false },
+    "apple_search": { "hitl": false },
+    "apple_mail_send": { "hitl": true, "hitlAction": "email.send" },
+    "apple_mail_draft_create": { "hitl": true, "hitlAction": "email.draft.create" },
+    "apple_calendar_list": { "hitl": false },
+    "apple_calendar_event_create": { "hitl": true, "hitlAction": "calendar.event.create" },
+    "apple_calendar_event_delete": { "hitl": true, "hitlAction": "calendar.event.delete" }
+  },
+  "hitlRequired": ["write"],
+  "syncInterval": 300,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/apple/src/apple-mail-core.ts

@@ -0,0 +1,43 @@
+/**
+ * Mail-layer re-exports + Drafts-append interface for the iCloud Mail connector.
+ *
+ * Helpers + client/mailer types come ONLY from the shared connector toolkit
+ * (shared/*) — NEVER cross-import a sibling connector's
+ * src (e.g. ../../imap/src/...): that breaks per-workspace tsc/bundling output.
+ *
+ * The shared kit already defines the structural client/mailer/message contracts
+ * the connector must satisfy (EmailReadClient/EmailSendMailer/EmailMessageMeta).
+ */
+
+export {
+  capPreview,
+  clampLimit,
+  formatAddress,
+  PREVIEW_FETCH_BYTES,
+  PREVIEW_MAX_CHARS,
+} from "../../../shared/imap-mail-core.ts";
+
+// The shared kit already defines the structural client/mailer/message contracts
+// the connector must satisfy (EmailReadClient/EmailSendMailer/EmailMessageMeta).
+export type {
+  EmailMessageMeta,
+  EmailReadClient,
+  EmailSendMailer,
+} from "../../../shared/imap-tool-kit.ts";
+
+export interface DraftInput {
+  readonly to: string;
+  readonly subject: string;
+  readonly body: string;
+  readonly cc?: string;
+  readonly bcc?: string;
+}
+
+export interface DraftResult {
+  readonly uid: number | null;
+  readonly mailbox: string;
+}
+
+export interface DraftAppender {
+  appendDraft(input: DraftInput): Promise<DraftResult>;
+}

package/connectors/apple/src/caldav-core.ts

@@ -0,0 +1,116 @@
+/**
+ * CalDAV client interface + pure calendar selection/normalization helpers
+ * for the iCloud Calendar connector.
+ *
+ * Design: the CalDavClient interface is the injectable seam — the real (network)
+ * implementation lives in server.ts (coverage-excluded). Pure helpers are
+ * separately tested here.
+ */
+
+import type { ParsedEvent } from "@nimbus-dev/sdk";
+
+// ---------------------------------------------------------------------------
+// CalendarRef — a discovered calendar
+// ---------------------------------------------------------------------------
+
+export interface CalendarRef {
+  readonly url: string;
+  readonly displayName: string;
+}
+
+// ---------------------------------------------------------------------------
+// EventWindow — a UTC time range for fetching events
+// ---------------------------------------------------------------------------
+
+export interface EventWindow {
+  readonly startUtc: string;
+  readonly endUtc: string;
+}
+
+// ---------------------------------------------------------------------------
+// CalDavClient — injectable transport interface
+// ---------------------------------------------------------------------------
+
+export interface CalDavClient {
+  listCalendars(): Promise<CalendarRef[]>;
+  listEvents(
+    cal: CalendarRef,
+    window: EventWindow,
+  ): Promise<{ href: string; event: ParsedEvent }[]>;
+  putEvent(cal: CalendarRef, uid: string, ics: string): Promise<{ href: string }>;
+  deleteEvent(href: string): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// selectCalendars — pure calendar filter helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Filter the full list of calendars by include/exclude display-name lists.
+ *
+ * Rules (in priority order):
+ * 1. If `include` is non-empty, return only calendars whose `displayName`
+ *    appears in the include list (exact match).
+ * 2. Else if `exclude` is non-empty, return all calendars whose `displayName`
+ *    does NOT appear in the exclude list.
+ * 3. Both empty (or both absent) → return all calendars.
+ */
+export function selectCalendars(
+  all: CalendarRef[],
+  cfg: { include?: readonly string[] | undefined; exclude?: readonly string[] | undefined },
+): CalendarRef[] {
+  const include = cfg.include ?? [];
+  const exclude = cfg.exclude ?? [];
+
+  if (include.length > 0) {
+    const includeSet = new Set(include);
+    return all.filter((c) => includeSet.has(c.displayName));
+  }
+
+  if (exclude.length > 0) {
+    const excludeSet = new Set(exclude);
+    return all.filter((c) => !excludeSet.has(c.displayName));
+  }
+
+  return all;
+}
+
+// ---------------------------------------------------------------------------
+// clampInstances — cap the number of events returned per calendar
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the first `max` elements from `rows`. When `rows.length <= max`,
+ * returns the original array reference unchanged (zero allocation).
+ */
+export function clampInstances<T>(rows: readonly T[], max: number): T[] {
+  // A non-positive cap (e.g. when an earlier calendar already filled the budget)
+  // means "take nothing" — `slice(0, -n)` would otherwise drop from the end.
+  if (max <= 0) {
+    return [];
+  }
+  if (rows.length <= max) {
+    return rows as T[];
+  }
+  return rows.slice(0, max);
+}
+
+// ---------------------------------------------------------------------------
+// caldavObjectFilename — derive a URL-path-safe .ics filename from a UID
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a CalDAV object filename (`<safe-uid>.ics`) from an event UID.
+ *
+ * The UID is embedded verbatim into the CalDAV object URL path segment, so any
+ * character that is unsafe in a path segment — `/`, `\`, `?`, `#`, `%`, `:`,
+ * whitespace, control chars — must be stripped to avoid a malformed/ambiguous
+ * URL (e.g. a summary-derived UID containing `/` would split the path) or path
+ * traversal (`../`). Allowed: URL-unreserved chars plus `@` (RFC 3986 §2.3 +
+ * the common `uid@host` form). A UID that sanitizes to empty falls back to
+ * `event` so a usable filename is always produced.
+ */
+export function caldavObjectFilename(uid: string): string {
+  const safe = uid.replace(/[^A-Za-z0-9\-_.~@]/g, "");
+  return `${safe === "" ? "event" : safe}.ics`;
+}