@nimbus-dev/connectors 0.1.0

package/connectors/protonmail/src/server.ts

@@ -0,0 +1,231 @@
+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 MailClient,
+  type MailEnvelope,
+  type MailListOptions,
+  type MailMessageMeta,
+  type MailSearchOptions,
+  PREVIEW_FETCH_BYTES,
+  type SendMailInput,
+  type SendMailResult,
+  type SmtpMailer,
+} from "./mail-core.ts";
+import { registerProtonmailTools } from "./tools.ts";
+
+// ProtonMail Bridge loopback defaults.
+const DEFAULT_IMAP_HOST = "127.0.0.1";
+const DEFAULT_IMAP_PORT = 1143;
+const DEFAULT_SMTP_HOST = "127.0.0.1";
+const DEFAULT_SMTP_PORT = 1025;
+const DEFAULT_MAILBOX = "INBOX";
+
+function envStr(name: string, fallback: string): string {
+  const raw = process.env[name]?.trim();
+  return raw === undefined || raw === "" ? fallback : raw;
+}
+
+function envelopeFromImap(env: FetchMessageObject["envelope"]): MailEnvelope {
+  if (env === undefined) {
+    return {};
+  }
+  const toAddr = (a: { name?: string; address?: string }): { name?: string; address?: string } => {
+    const out: { name?: string; address?: string } = {};
+    if (a.name !== undefined) {
+      out.name = a.name;
+    }
+    if (a.address !== undefined) {
+      out.address = a.address;
+    }
+    return out;
+  };
+  return {
+    date: env.date ?? null,
+    subject: env.subject ?? null,
+    messageId: env.messageId ?? null,
+    from: (env.from ?? []).map(toAddr),
+    to: (env.to ?? []).map(toAddr),
+    cc: (env.cc ?? []).map(toAddr),
+  };
+}
+
+function toMessageMeta(
+  msg: FetchMessageObject,
+  mailbox: string,
+  uidValidity: string | null,
+): MailMessageMeta {
+  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),
+  };
+}
+
+function previewFetchQuery(): FetchQueryObject {
+  return {
+    uid: true,
+    envelope: true,
+    bodyStructure: true,
+    internalDate: true,
+    bodyParts: [
+      { key: "1", start: 0, maxLength: PREVIEW_FETCH_BYTES },
+      { key: "TEXT", start: 0, maxLength: PREVIEW_FETCH_BYTES },
+    ],
+  };
+}
+
+/**
+ * Real IMAP client over imapflow, configured for ProtonMail Bridge: a loopback
+ * STARTTLS endpoint with a Bridge-generated self-signed certificate, so
+ * `secure: false` + `tls.rejectUnauthorized: false` (the connection never
+ * leaves 127.0.0.1).
+ */
+class BridgeImapClient implements MailClient {
+  private readonly config: { host: string; port: number; user: string; pass: string };
+
+  constructor() {
+    this.config = {
+      host: envStr("PROTONMAIL_HOST", DEFAULT_IMAP_HOST),
+      port: envInt("PROTONMAIL_PORT", DEFAULT_IMAP_PORT),
+      user: requireProcessEnv("PROTONMAIL_USERNAME"),
+      pass: requireProcessEnv("PROTONMAIL_PASSWORD"),
+    };
+  }
+
+  private newClient(): ImapFlow {
+    return new ImapFlow({
+      host: this.config.host,
+      port: this.config.port,
+      secure: false,
+      auth: { user: this.config.user, pass: this.config.pass },
+      logger: false,
+      // ProtonMail Bridge listens on localhost with a self-signed certificate;
+      // disabling chain verification is required and safe for the loopback bridge.
+      tls: { rejectUnauthorized: 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: MailListOptions): Promise<MailMessageMeta[]> {
+    const mailbox = options.mailbox ?? DEFAULT_MAILBOX;
+    const limit = clampLimit(options.limit);
+    return this.withMailbox(mailbox, async (client, uidValidity) => {
+      const out: MailMessageMeta[] = [];
+      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));
+      }
+      out.sort((a, b) => b.uid - a.uid);
+      return out;
+    });
+  }
+
+  async get(uid: number, mailbox?: string): Promise<MailMessageMeta | 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: MailSearchOptions): Promise<MailMessageMeta[]> {
+    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: MailMessageMeta[] = [];
+      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, configured for the ProtonMail Bridge relay. */
+class BridgeMailer implements SmtpMailer {
+  private readonly transport: Transporter;
+  private readonly from: string;
+
+  constructor() {
+    const host = envStr("PROTONMAIL_SMTP_HOST", DEFAULT_SMTP_HOST);
+    const port = envInt("PROTONMAIL_SMTP_PORT", DEFAULT_SMTP_PORT);
+    const user = requireProcessEnv("PROTONMAIL_SMTP_USERNAME");
+    const pass = requireProcessEnv("PROTONMAIL_SMTP_PASSWORD");
+    this.from = user;
+    this.transport = createTransport({
+      host,
+      port,
+      secure: false,
+      auth: { user, pass },
+      tls: { rejectUnauthorized: false },
+    });
+  }
+
+  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-protonmail", version: "0.1.0" });
+registerProtonmailTools(server, new BridgeImapClient(), new BridgeMailer());
+
+await server.connect(new StdioServerTransport());

package/connectors/protonmail/src/tools.ts

@@ -0,0 +1,45 @@
+import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { registerEmailConnectorTools } from "../../../shared/imap-tool-kit.ts";
+import { formatAddress, type MailClient, type SmtpMailer } from "./mail-core.ts";
+
+/**
+ * Register the ProtonMail (Bridge) 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 registerProtonmailTools(
+  // Widened: the consent kit needs the real server surface, not just the `.tool` shim.
+  server: ConsentServer & { tool: (...args: never) => unknown },
+  client: MailClient,
+  mailer: SmtpMailer,
+): void {
+  const registerWriteTool = createWriteToolRegistrar(server, {
+    connector: "protonmail",
+    scopeEnv: "NIMBUS_MCP_PROTONMAIL_WRITE_SCOPE",
+    scopeKinds: ["recipient"],
+  });
+
+  registerEmailConnectorTools({
+    server,
+    registerWriteTool,
+    toolPrefix: "protonmail",
+    descriptions: {
+      list: "List recent ProtonMail messages (via Bridge) — 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 ProtonMail 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 protonmail_list. Searches headers only; NEVER scans or returns document/body content beyond the capped preview.",
+      send: "Send a new email over the ProtonMail Bridge SMTP relay. Requires Gateway HITL email.send.",
+    },
+    client,
+    mailer,
+    formatAddr: formatAddress,
+  });
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const PROTONMAIL_TOOL_NAMES = [
+  "protonmail_list",
+  "protonmail_get",
+  "protonmail_search",
+  "protonmail_mail_send",
+] as const;

package/connectors/raindrop/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.raindrop",
+  "displayName": "Raindrop",
+  "version": "0.1.0",
+  "description": "Raindrop connector (read-only). Surfaces the user's saved Raindrop.io bookmarks as `raindrop:bookmark` items in the local index — the bookmarked URL, title, the excerpt/description, the user's note, the domain, the item type (link/article/image/video/document/audio), tags, and the parent collection id — plus the collections themselves as `raindrop:collection` items (title, raindrop count, public flag, view, color, sort, parent id), so a bookmark's `collectionId` resolves to a real indexed record. Useful for answering bookmarking questions (\"what did I save about retries?\", \"which shelf is that bookmark on?\") without leaving Nimbus. Bearer API-token auth (`Authorization: Bearer <token>` — a Raindrop.io test token or OAuth access token; never logged). The SaaS host (api.raindrop.io) is fixed. Raindrop paginates the `/rest/v1/raindrops/0` endpoint by page number (0-based, page_size=50), returning the `{ result, items, count }` envelope; collections come from the two UNPAGINATED endpoints `/rest/v1/collections` (root) and `/rest/v1/collections/childrens` (nested). `created` / `lastUpdate` are ISO-8601 (converted to epoch-ms on index). Collection `external_id`s are namespaced `collection/<id>` because Raindrop numbers collections and raindrops in separate id spaces. Highlights and per-collection filtering of bookmarks remain deferred follow-ups.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.raindrop.io"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,20 @@
+import {
+  fieldsFromKeys,
+  makeQueryFilter,
+  type SearchMatchOptions,
+} from "../../../shared/search-filter.ts";
+
+export type RaindropSearchMatchOptions = SearchMatchOptions;
+
+export const filterRaindropBookmarks = makeQueryFilter(
+  fieldsFromKeys(["title", "excerpt", "note", "domain", "link", "type"], { tags: true }),
+);
+
+/**
+ * Collection haystack: the title and the two display fields. The Raindrop
+ * Collection object has no description, and `cover` / `access` / `collaborators`
+ * are noise, so the title carries almost all the signal.
+ */
+export const filterRaindropCollections = makeQueryFilter(
+  fieldsFromKeys(["title", "view", "color"]),
+);

package/connectors/raindrop/src/server.ts

@@ -0,0 +1,107 @@
+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 { filterRaindropBookmarks, filterRaindropCollections } from "./search-filter.ts";
+
+const BASE = "https://api.raindrop.io";
+
+function apiToken(): string {
+  const t = process.env["RAINDROP_TOKEN"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("RAINDROP_TOKEN is not set");
+  }
+  return t;
+}
+
+function authHeader(): Record<string, string> {
+  return { Authorization: `Bearer ${apiToken()}`, Accept: "application/json" };
+}
+
+async function raindropGet(path: string): Promise<unknown> {
+  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Raindrop ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+/**
+ * Raindrop splits collections across two unpaginated endpoints — `/collections`
+ * (root) and `/collections/childrens` (every nested one). "List my collections"
+ * means both, so drain both and concatenate the `items` arrays.
+ */
+async function allCollections(): Promise<unknown[]> {
+  const [root, children] = await Promise.all([
+    raindropGet(`/rest/v1/collections`),
+    raindropGet(`/rest/v1/collections/childrens`),
+  ]);
+  const itemsOf = (envelope: unknown): unknown[] => {
+    const items = (envelope as { items?: unknown } | null)?.items;
+    return Array.isArray(items) ? items : [];
+  };
+  return [...itemsOf(root), ...itemsOf(children)];
+}
+
+await runReadOnlyMcpConnector("nimbus-raindrop", (reg) => {
+  reg(
+    "raindrop_list",
+    'List the user\'s Raindrop bookmarks (`GET /rest/v1/raindrops/0?perpage=50` — collection id `0` is the special "all raindrops" collection). Returns the `{ result, items: [...], count }` envelope — `items` holds the bookmark objects.',
+    z.object({}),
+    async () => {
+      return jsonResult(await raindropGet(`/rest/v1/raindrops/0?perpage=50`));
+    },
+  );
+
+  reg(
+    "raindrop_get",
+    "Fetch one Raindrop bookmark by its id (`GET /rest/v1/raindrop/{id}` — note the SINGULAR `raindrop` in the get-by-id path). Returns the `{ result, item: {...} }` envelope. Throws when no match is found.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await raindropGet(`/rest/v1/raindrop/${encodeURIComponent(p.id)}`));
+    },
+  );
+
+  reg(
+    "raindrop_search",
+    "Substring search across the user's Raindrop bookmarks (first page only). Matches the query against the bookmark title, excerpt, note, domain, link, type, and tags (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const root = await raindropGet(`/rest/v1/raindrops/0?perpage=50`);
+      const items = (root as { items?: unknown[] } | null)?.items;
+      return matchesResult(items, filterRaindropBookmarks, p);
+    },
+  );
+
+  reg(
+    "raindrop_collections_list",
+    "List ALL the user's Raindrop collections — the records a bookmark's `collectionId` points at. Raindrop splits them across two unpaginated endpoints, so this drains BOTH (`GET /rest/v1/collections` for root collections and `GET /rest/v1/collections/childrens` for every nested one) and returns their concatenated `items` as `{ items: [...] }`. A nested collection carries `parent.$id`; a root one does not. Note that collection id `0` — the special \"all raindrops\" collection the bookmark list reads — is NOT returned by either endpoint.",
+    z.object({}),
+    async () => {
+      return jsonResult({ items: await allCollections() });
+    },
+  );
+
+  reg(
+    "raindrop_collection_get",
+    "Fetch one Raindrop collection by its id (`GET /rest/v1/collection/{id}` — note the SINGULAR `collection` in the get-by-id path). The collection id space is SEPARATE from the bookmark id space: pass a bookmark's `collectionId`, not its `_id`. Returns the `{ result, item: {...} }` envelope. Throws when no match is found.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await raindropGet(`/rest/v1/collection/${encodeURIComponent(p.id)}`));
+    },
+  );
+
+  reg(
+    "raindrop_collections_search",
+    "Substring search across ALL the user's Raindrop collections (root + nested). Matches the query against the collection title, view, and color (case-insensitive) — the Raindrop Collection object has no description field. Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      return matchesResult(await allCollections(), filterRaindropCollections, p);
+    },
+  );
+});

package/connectors/ramp/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.ramp",
+  "displayName": "Ramp",
+  "version": "0.1.0",
+  "description": "Ramp connector (read-only). Surfaces the user's Ramp card transactions as ramp:transaction items in the local index — the merchant name, the amount + currency, the card holder's display name and department, the transaction state, the spend category, the transaction time, and a truncated memo. Useful for spend questions (\"what did I spend at AWS last month?\", \"find my transactions in the Engineering department\") without leaving Nimbus. OAuth2 client-credentials auth: the connector exchanges its client id + client secret for a bearer token at POST /developer/v1/token (HTTP Basic auth, transactions:read scope) and caches the token for the process, then calls the data endpoints with Authorization: Bearer. Two required secret credentials (a client id + a client secret) selecting the Ramp developer application. The SaaS host (api.ramp.com) is fixed. The /developer/v1/transactions endpoint paginates by a page.next cursor (a full URL to the next page, or null at the end); the connector walks a single forward pass per cycle, page-capped. No full card numbers or PANs are surfaced — Ramp's API does not return them and only the safe transaction fields are mapped.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.ramp.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,37 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type RampSearchMatchOptions = SearchMatchOptions;
+
+function cardHolderName(row: Record<string, unknown>): string {
+  const holder = asObjectish(row["card_holder"]);
+  if (holder === undefined) {
+    return "";
+  }
+  // stringField already returns "" for missing/non-string fields, so no `?? ""` is needed.
+  const first = stringField(holder, "first_name");
+  const last = stringField(holder, "last_name");
+  const dept = stringField(holder, "department_name");
+  return [first, last, dept].filter((p) => p !== "").join(" ");
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [
+    stringField(row, "merchant_name"),
+    stringField(row, "sk_category_name"),
+    stringField(row, "state"),
+    stringField(row, "currency_code"),
+    stringField(row, "memo"),
+    cardHolderName(row),
+  ];
+}
+
+export const filterRampTransactions = makeQueryFilter(fieldsOf);

package/connectors/ramp/src/server.ts

@@ -0,0 +1,109 @@
+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 { filterRampTransactions } from "./search-filter.ts";
+
+const BASE = "https://api.ramp.com";
+const TOKEN_PATH = "/developer/v1/token";
+const TOKEN_SCOPE = "transactions:read";
+
+function requiredEnv(name: string): string {
+  const v = process.env[name]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error(`${name} is not set`);
+  }
+  return v;
+}
+
+let cachedToken: string | null = null;
+
+async function token(): Promise<string> {
+  if (cachedToken !== null) {
+    return cachedToken;
+  }
+  const clientId = requiredEnv("RAMP_CLIENT_ID");
+  const clientSecret = requiredEnv("RAMP_CLIENT_SECRET");
+  const basic = Buffer.from(`${clientId}:${clientSecret}`, "utf8").toString("base64");
+  const body = new URLSearchParams({ grant_type: "client_credentials", scope: TOKEN_SCOPE });
+  const res = await fetch(`${BASE}${TOKEN_PATH}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${basic}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json",
+    },
+    body: body.toString(),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Ramp token exchange ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  let parsed: { access_token?: unknown };
+  try {
+    parsed = JSON.parse(text) as { access_token?: unknown };
+  } catch {
+    throw new Error("Ramp token exchange: invalid JSON response");
+  }
+  if (typeof parsed.access_token !== "string" || parsed.access_token === "") {
+    throw new Error("Ramp token exchange: no access_token in response");
+  }
+  cachedToken = parsed.access_token;
+  return cachedToken;
+}
+
+async function rampGet(path: string): Promise<unknown> {
+  const t = await token();
+  const res = await fetch(`${BASE}${path}`, {
+    headers: { Authorization: `Bearer ${t}`, Accept: "application/json" },
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Ramp ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function transactionsFrom(root: unknown): unknown[] {
+  const data = (root as { data?: unknown } | null)?.data;
+  return Array.isArray(data) ? data : [];
+}
+
+await runReadOnlyMcpConnector("nimbus-ramp", (reg) => {
+  reg(
+    "ramp_list",
+    "List Ramp card transactions (GET /developer/v1/transactions?page_size=N). The connector exchanges its OAuth2 client-credentials for a bearer token (POST /developer/v1/token, HTTP Basic auth, transactions:read scope) and caches it for the process. `limit` (default 100, max 100) caps page_size of the single first-page request. Returns the `.data` array — each transaction is { id, amount, currency_code, merchant_name, card_holder, state, sk_category_name, user_transaction_time, memo, ... }.",
+    z.object({
+      limit: z.number().int().min(1).max(100).optional(),
+    }),
+    async (p) => {
+      const root = await rampGet(`/developer/v1/transactions?page_size=${String(p.limit ?? 100)}`);
+      return jsonResult(transactionsFrom(root));
+    },
+  );
+
+  reg(
+    "ramp_get",
+    "Fetch one Ramp transaction by its id (GET /developer/v1/transactions/{id}). Returns the transaction object directly. Throws when no transaction with that id exists.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await rampGet(`/developer/v1/transactions/${encodeURIComponent(p.id)}`));
+    },
+  );
+
+  reg(
+    "ramp_search",
+    "Substring search across the first page of Ramp transactions. Matches the query (case-insensitive) against merchant name, category, state, currency, memo, and the card holder name/department. Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const root = await rampGet("/developer/v1/transactions?page_size=100");
+      const matches = filterRampTransactions(transactionsFrom(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+});

package/connectors/readwise/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.readwise",
+  "displayName": "Readwise",
+  "version": "0.1.0",
+  "description": "Readwise connector (read-only). Surfaces the user's saved book/article highlights as `readwise:highlight` items in the local index — the highlighted excerpt text, the user's note, the parent book/article id, the location + location type, the color, tags, and the source article URL (for web highlights) — plus their parent books/articles as `readwise:book` items (title, author, category, source, highlight count, document note, tags, ASIN, source + Readwise book-review URLs), so a highlight's `book_id` resolves to a real indexed record. Useful for answering reading questions (\"what did I highlight about retries?\", \"which book was that note in?\") without leaving Nimbus. Token API-token auth (`Authorization: Token <token>` — Django-REST-Framework token auth, NOT Bearer). The SaaS host (readwise.io) is fixed. Readwise paginates both `/api/v2/highlights/` and `/api/v2/books/` by page number (DRF `{ count, next, previous, results }` envelope, page_size=1000). `highlighted_at` / `last_highlight_at` / `updated` are ISO-8601 (converted to epoch-ms on index). Book `external_id`s are namespaced `book/<id>` because Readwise numbers books and highlights in separate sequences. Documents / daily-review and the Reader v3 API remain deferred follow-ups.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["readwise.io"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,64 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type ReadwiseSearchMatchOptions = SearchMatchOptions;
+
+function tagNames(row: Record<string, unknown>): string {
+  const tags = row["tags"];
+  if (!Array.isArray(tags)) {
+    return "";
+  }
+  const names: string[] = [];
+  for (const t of tags) {
+    if (t !== null && typeof t === "object") {
+      const name = (t as Record<string, unknown>)["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;
+  }
+  return [
+    stringField(row, "text"),
+    stringField(row, "note"),
+    stringField(row, "color"),
+    stringField(row, "location_type"),
+    tagNames(row),
+  ];
+}
+
+export const filterReadwiseHighlights = makeQueryFilter(fieldsOf);
+
+/**
+ * Book haystack: title, author, category, source, the user's document note, and
+ * tag names. `cover_image_url` / `highlights_url` / `source_url` are deliberately
+ * excluded — matching a URL substring is noise, and the highlight filter makes
+ * the same choice for its `url`.
+ */
+function bookFieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [
+    stringField(row, "title"),
+    stringField(row, "author"),
+    stringField(row, "category"),
+    stringField(row, "source"),
+    stringField(row, "document_note"),
+    tagNames(row),
+  ];
+}
+
+export const filterReadwiseBooks = makeQueryFilter(bookFieldsOf);