@nimbus-dev/connectors 0.2.0 → 0.2.2

package/connectors/protonmail/src/server.ts

@@ -1,26 +1,18 @@
+/**
+ * ProtonMail (via ProtonMail Bridge) connector entry point.
+ *
+ * The Bridge speaks standard IMAP/SMTP on the loopback interface, so the
+ * transport itself is the shared `shared/imapflow-adapter.ts`. What is specific
+ * to ProtonMail is only the configuration below: loopback defaults, STARTTLS
+ * rather than implicit TLS, and a Bridge-generated self-signed certificate.
+ */
+
 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 { optionalEnv } from "../../../shared/env-json-api.ts";
+import { envInt } from "../../../shared/imap-tool-kit.ts";
+import { createImapFlowClient, createNodemailerMailer } from "../../../shared/imapflow-adapter.ts";
 import { requireProcessEnv } from "../../../shared/mcp-tool-kit.ts";
-import {
-  clampLimit,
-  type 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.
@@ -28,204 +20,32 @@ 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).
+ * The Bridge listens on localhost with a self-signed certificate, so chain
+ * verification is disabled and TLS is not implicit. Both are safe here and only
+ * here: 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 BRIDGE_TLS = { secure: false, rejectUnauthorized: false } as const;
 
 const server = new McpServer({ name: "nimbus-protonmail", version: "0.1.0" });
-registerProtonmailTools(server, new BridgeImapClient(), new BridgeMailer());
+
+registerProtonmailTools(
+  server,
+  createImapFlowClient({
+    host: optionalEnv("PROTONMAIL_HOST", DEFAULT_IMAP_HOST),
+    port: envInt("PROTONMAIL_PORT", DEFAULT_IMAP_PORT),
+    user: requireProcessEnv("PROTONMAIL_USERNAME"),
+    pass: requireProcessEnv("PROTONMAIL_PASSWORD"),
+    ...BRIDGE_TLS,
+  }),
+  createNodemailerMailer({
+    host: optionalEnv("PROTONMAIL_SMTP_HOST", DEFAULT_SMTP_HOST),
+    port: envInt("PROTONMAIL_SMTP_PORT", DEFAULT_SMTP_PORT),
+    user: requireProcessEnv("PROTONMAIL_SMTP_USERNAME"),
+    pass: requireProcessEnv("PROTONMAIL_SMTP_PASSWORD"),
+    ...BRIDGE_TLS,
+  }),
+);
 
 await server.connect(new StdioServerTransport());

package/connectors/raindrop/src/server.ts

@@ -1,107 +1,6 @@
-import { z } from "zod";
-import { matchesResult, searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
-import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
 import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
-import { 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)];
-}
+import { registerRaindropTools } from "./tools.ts";
 
 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);
-    },
-  );
+  registerRaindropTools(reg);
 });

package/connectors/raindrop/src/tools.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { createJsonGetter, envAuthHeaders } from "../../../shared/env-json-api.ts";
+import { matchesResult, searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterRaindropBookmarks, filterRaindropCollections } from "./search-filter.ts";
+
+const BASE = "https://api.raindrop.io";
+
+const raindropGet = createJsonGetter({
+  base: BASE,
+  label: "Raindrop",
+  headers: envAuthHeaders({ env: "RAINDROP_TOKEN" }),
+});
+
+/**
+ * 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)];
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const RAINDROP_TOOL_NAMES = [
+  "raindrop_list",
+  "raindrop_get",
+  "raindrop_search",
+  "raindrop_collections_list",
+  "raindrop_collection_get",
+  "raindrop_collections_search",
+] as const;
+
+export function registerRaindropTools(reg: ZodToolRegistrar): void {
+  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/src/server.ts

@@ -1,109 +1,6 @@
-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 : [];
-}
+import { registerRampTools } from "./tools.ts";
 
 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 });
-    },
-  );
+  registerRampTools(reg);
 });

package/connectors/ramp/src/tools.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { createAccessTokenCache } from "../../../shared/access-token-cache.ts";
+import { requiredEnv } from "../../../shared/env-json-api.ts";
+import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
+import {
+  encodeBasicAuthHeader,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
+import type { ZodToolRegistrar } 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";
+
+/** OAuth2 client-credentials against Ramp's token endpoint. */
+const token = createAccessTokenCache({
+  label: "Ramp token exchange",
+  exchange: async () => {
+    const clientId = requiredEnv("RAMP_CLIENT_ID");
+    const clientSecret = requiredEnv("RAMP_CLIENT_SECRET");
+    const body = new URLSearchParams({ grant_type: "client_credentials", scope: TOKEN_SCOPE });
+    const res = await fetch(`${BASE}${TOKEN_PATH}`, {
+      method: "POST",
+      headers: {
+        Authorization: encodeBasicAuthHeader(clientId, clientSecret),
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: body.toString(),
+    });
+    return { ok: res.ok, status: res.status, text: await res.text() };
+  },
+});
+
+/** Forget the exchanged token. Tests only: the cache otherwise outlives the test that filled it. */
+export function __resetRampTokenForTests(): void {
+  token.clear();
+}
+
+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 : [];
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const RAMP_TOOL_NAMES = ["ramp_get", "ramp_list", "ramp_search"] as const;
+
+export function registerRampTools(reg: ZodToolRegistrar): void {
+  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 });
+    },
+  );
+}