@nimbus-dev/connectors 0.2.0 → 0.2.2

package/connectors/fastmail/src/jmap-client.ts

@@ -0,0 +1,202 @@
+/**
+ * The real Fastmail JMAP client over `fetch`.
+ *
+ * Moved out of `server.ts` for the same reason as every other connector's
+ * transport: an entry point that constructs its client at module scope cannot
+ * be imported by a test, so none of the session discovery, capability checks or
+ * request building below was reachable from one.
+ */
+
+import { optionalEnv } from "../../../shared/env-json-api.ts";
+import { requireProcessEnv } from "../../../shared/mcp-tool-kit.ts";
+import {
+  asRecord,
+  asString,
+  buildGetRequest,
+  buildListRequest,
+  buildSearchRequest,
+  CORE_CAPABILITY,
+  extractEmailList,
+  type JmapClient,
+  type JmapEmailView,
+  type JmapSession,
+  MAIL_CAPABILITY,
+  methodResponseArgs,
+  parseSession,
+  type SendMailInput,
+  type SendMailResult,
+  SUBMISSION_CAPABILITY,
+  validateApiUrl,
+  viewEmail,
+} from "./jmap-core.ts";
+
+const DEFAULT_BASE_URL = "https://api.fastmail.com";
+
+/** Parse a comma-separated address list (`Name <a@x>, b@y`) → JMAP address objects. */
+function parseAddressList(raw: string): Array<{ email: string }> {
+  return raw
+    .split(",")
+    .map((part) => {
+      // Extract the address inside `<...>` without a backtracking regex.
+      const open = part.indexOf("<");
+      const close = open === -1 ? -1 : part.indexOf(">", open + 1);
+      const inner = open !== -1 && close !== -1 ? part.slice(open + 1, close) : part;
+      return inner.trim();
+    })
+    .filter((email) => email !== "")
+    .map((email) => ({ email }));
+}
+
+/** Real Fastmail JMAP client over fetch. Discovers the session once, then reuses it. */
+class FetchJmapClient implements JmapClient {
+  private readonly baseUrl: string;
+  private readonly token: string;
+  private session: JmapSession | null = null;
+
+  constructor() {
+    this.token = requireProcessEnv("FASTMAIL_API_TOKEN");
+    // Only ONE trailing slash is dropped here — not `optionalBaseUrl`'s strip-them-all.
+    this.baseUrl = optionalEnv("FASTMAIL_BASE_URL", DEFAULT_BASE_URL).replace(/\/$/, "");
+  }
+
+  private headers(): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.token}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    };
+  }
+
+  private async ensureSession(): Promise<JmapSession> {
+    if (this.session !== null) {
+      return this.session;
+    }
+    const res = await fetch(`${this.baseUrl}/jmap/session`, { headers: this.headers() });
+    if (!res.ok) {
+      throw new Error(`JMAP session failed: HTTP ${String(res.status)}`);
+    }
+    const session = parseSession(await res.json());
+    if (session === null) {
+      throw new Error("JMAP session response missing apiUrl / mail account");
+    }
+    // The apiUrl is server-controlled; pin it to the configured host before any
+    // authenticated POST is sent there (SSRF guard).
+    const validated: JmapSession = {
+      ...session,
+      apiUrl: validateApiUrl(session.apiUrl, this.baseUrl),
+    };
+    this.session = validated;
+    return validated;
+  }
+
+  private async api(body: unknown): Promise<unknown> {
+    const session = await this.ensureSession();
+    const res = await fetch(session.apiUrl, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      throw new Error(`JMAP api failed: HTTP ${String(res.status)}`);
+    }
+    return res.json();
+  }
+
+  private async views(request: unknown): Promise<JmapEmailView[]> {
+    const out: JmapEmailView[] = [];
+    for (const raw of extractEmailList(await this.api(request))) {
+      const v = viewEmail(raw);
+      if (v !== null) {
+        out.push(v);
+      }
+    }
+    return out;
+  }
+
+  async list(limit: number): Promise<JmapEmailView[]> {
+    const session = await this.ensureSession();
+    return this.views(buildListRequest(session.accountId, limit));
+  }
+
+  async search(query: string, limit: number): Promise<JmapEmailView[]> {
+    const session = await this.ensureSession();
+    return this.views(buildSearchRequest(session.accountId, query, limit));
+  }
+
+  async get(id: string): Promise<JmapEmailView | null> {
+    const session = await this.ensureSession();
+    const views = await this.views(buildGetRequest(session.accountId, id));
+    return views[0] ?? null;
+  }
+
+  async send(input: SendMailInput): Promise<SendMailResult> {
+    const session = await this.ensureSession();
+    const { accountId } = session;
+
+    // Round 1: discover the sending identity + the Drafts mailbox.
+    const discovery = await this.api({
+      using: [CORE_CAPABILITY, MAIL_CAPABILITY, SUBMISSION_CAPABILITY],
+      methodCalls: [
+        ["Identity/get", { accountId, ids: null }, "id"],
+        ["Mailbox/query", { accountId, filter: { role: "drafts" } }, "mq"],
+      ],
+    });
+    const identities = methodResponseArgs(discovery, "Identity/get")?.["list"];
+    const identity = Array.isArray(identities) ? asRecord(identities[0]) : null;
+    const identityId = identity === null ? null : asString(identity["id"]);
+    const identityEmail = identity === null ? null : asString(identity["email"]);
+    const mqIds = methodResponseArgs(discovery, "Mailbox/query")?.["ids"];
+    const draftMailboxId = Array.isArray(mqIds) ? asString(mqIds[0]) : null;
+    if (identityId === null || identityEmail === null || draftMailboxId === null) {
+      throw new Error("JMAP send: could not resolve sending identity or Drafts mailbox");
+    }
+
+    // Round 2: create the draft email + submit it.
+    const created = await this.api({
+      using: [CORE_CAPABILITY, MAIL_CAPABILITY, SUBMISSION_CAPABILITY],
+      methodCalls: [
+        [
+          "Email/set",
+          {
+            accountId,
+            create: {
+              draft: {
+                mailboxIds: { [draftMailboxId]: true },
+                keywords: { $draft: true, $seen: true },
+                from: [{ email: identityEmail }],
+                to: parseAddressList(input.to),
+                ...(input.cc === undefined ? {} : { cc: parseAddressList(input.cc) }),
+                ...(input.bcc === undefined ? {} : { bcc: parseAddressList(input.bcc) }),
+                subject: input.subject,
+                bodyStructure: { type: "text/plain", partId: "b" },
+                bodyValues: { b: { value: input.body } },
+              },
+            },
+          },
+          "es",
+        ],
+        [
+          "EmailSubmission/set",
+          {
+            accountId,
+            create: { sub: { emailId: "#draft", identityId } },
+          },
+          "sub",
+        ],
+      ],
+    });
+    const emailCreated = asRecord(methodResponseArgs(created, "Email/set")?.["created"]);
+    const emailId =
+      emailCreated === null ? null : asString(asRecord(emailCreated["draft"])?.["id"]);
+    const subCreated = asRecord(methodResponseArgs(created, "EmailSubmission/set")?.["created"]);
+    const submissionId = subCreated === null ? null : asString(asRecord(subCreated["sub"])?.["id"]);
+    return { emailId, submissionId };
+  }
+}
+
+/** The client the entry point uses. Credentials are read at construction. */
+export function createFetchJmapClient(): JmapClient {
+  return new FetchJmapClient();
+}
+
+export { parseAddressList };

package/connectors/fastmail/src/jmap-core.ts

@@ -17,6 +17,7 @@
  */
 
 import type { JmapEmailView } from "@nimbus-dev/sdk";
+import type { OutgoingMail } from "../../../shared/imap-tool-kit.ts";
 
 export {
   asRecord,
@@ -45,17 +46,14 @@ export {
   viewEmail,
 } from "@nimbus-dev/sdk";
 
-const DEFAULT_LIST_LIMIT = 50;
-const MAX_LIST_LIMIT = 200;
+/**
+ * The list/search limit clamp (default 50, ceiling 200) is the one every mail connector
+ * applies; the tools' own schemas cap `limit` at the same 200.
+ */
+export { clampLimit } from "../../../shared/imap-mail-core.ts";
 
-/** Outgoing message for the SMTP/JMAP submission send tool. */
-export interface SendMailInput {
-  readonly to: string;
-  readonly subject: string;
-  readonly body: string;
-  readonly cc?: string;
-  readonly bcc?: string;
-}
+/** Outgoing message for the JMAP submission send tool — the shared mail-send shape. */
+export type SendMailInput = OutgoingMail;
 
 export interface SendMailResult {
   readonly emailId: string | null;
@@ -73,14 +71,3 @@ export interface JmapClient {
   search(query: string, limit: number): Promise<JmapEmailView[]>;
   send(input: SendMailInput): Promise<SendMailResult>;
 }
-
-export function clampLimit(limit: number | undefined, fallback = DEFAULT_LIST_LIMIT): number {
-  if (limit === undefined || !Number.isFinite(limit)) {
-    return fallback;
-  }
-  const n = Math.trunc(limit);
-  if (n < 1) {
-    return 1;
-  }
-  return Math.min(n, MAX_LIST_LIMIT);
-}

package/connectors/fastmail/src/server.ts

@@ -1,194 +1,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-import { requireProcessEnv } from "../../../shared/mcp-tool-kit.ts";
-import {
-  asRecord,
-  asString,
-  buildGetRequest,
-  buildListRequest,
-  buildSearchRequest,
-  CORE_CAPABILITY,
-  extractEmailList,
-  type JmapClient,
-  type JmapEmailView,
-  type JmapSession,
-  MAIL_CAPABILITY,
-  methodResponseArgs,
-  parseSession,
-  type SendMailInput,
-  type SendMailResult,
-  SUBMISSION_CAPABILITY,
-  validateApiUrl,
-  viewEmail,
-} from "./jmap-core.ts";
+import { createFetchJmapClient } from "./jmap-client.ts";
 import { registerFastmailTools } from "./tools.ts";
 
-const DEFAULT_BASE_URL = "https://api.fastmail.com";
-
-/** Parse a comma-separated address list (`Name <a@x>, b@y`) → JMAP address objects. */
-function parseAddressList(raw: string): Array<{ email: string }> {
-  return raw
-    .split(",")
-    .map((part) => {
-      // Extract the address inside `<...>` without a backtracking regex.
-      const open = part.indexOf("<");
-      const close = open === -1 ? -1 : part.indexOf(">", open + 1);
-      const inner = open !== -1 && close !== -1 ? part.slice(open + 1, close) : part;
-      return inner.trim();
-    })
-    .filter((email) => email !== "")
-    .map((email) => ({ email }));
-}
-
-/** Real Fastmail JMAP client over fetch. Discovers the session once, then reuses it. */
-class FetchJmapClient implements JmapClient {
-  private readonly baseUrl: string;
-  private readonly token: string;
-  private session: JmapSession | null = null;
-
-  constructor() {
-    this.token = requireProcessEnv("FASTMAIL_API_TOKEN");
-    const base = process.env["FASTMAIL_BASE_URL"]?.trim();
-    this.baseUrl = (base === undefined || base === "" ? DEFAULT_BASE_URL : base).replace(/\/$/, "");
-  }
-
-  private headers(): Record<string, string> {
-    return {
-      Authorization: `Bearer ${this.token}`,
-      "Content-Type": "application/json",
-      Accept: "application/json",
-    };
-  }
-
-  private async ensureSession(): Promise<JmapSession> {
-    if (this.session !== null) {
-      return this.session;
-    }
-    const res = await fetch(`${this.baseUrl}/jmap/session`, { headers: this.headers() });
-    if (!res.ok) {
-      throw new Error(`JMAP session failed: HTTP ${String(res.status)}`);
-    }
-    const session = parseSession(await res.json());
-    if (session === null) {
-      throw new Error("JMAP session response missing apiUrl / mail account");
-    }
-    // The apiUrl is server-controlled; pin it to the configured host before any
-    // authenticated POST is sent there (SSRF guard).
-    const validated: JmapSession = {
-      ...session,
-      apiUrl: validateApiUrl(session.apiUrl, this.baseUrl),
-    };
-    this.session = validated;
-    return validated;
-  }
-
-  private async api(body: unknown): Promise<unknown> {
-    const session = await this.ensureSession();
-    const res = await fetch(session.apiUrl, {
-      method: "POST",
-      headers: this.headers(),
-      body: JSON.stringify(body),
-    });
-    if (!res.ok) {
-      throw new Error(`JMAP api failed: HTTP ${String(res.status)}`);
-    }
-    return res.json();
-  }
-
-  private async views(request: unknown): Promise<JmapEmailView[]> {
-    const out: JmapEmailView[] = [];
-    for (const raw of extractEmailList(await this.api(request))) {
-      const v = viewEmail(raw);
-      if (v !== null) {
-        out.push(v);
-      }
-    }
-    return out;
-  }
-
-  async list(limit: number): Promise<JmapEmailView[]> {
-    const session = await this.ensureSession();
-    return this.views(buildListRequest(session.accountId, limit));
-  }
-
-  async search(query: string, limit: number): Promise<JmapEmailView[]> {
-    const session = await this.ensureSession();
-    return this.views(buildSearchRequest(session.accountId, query, limit));
-  }
-
-  async get(id: string): Promise<JmapEmailView | null> {
-    const session = await this.ensureSession();
-    const views = await this.views(buildGetRequest(session.accountId, id));
-    return views[0] ?? null;
-  }
-
-  async send(input: SendMailInput): Promise<SendMailResult> {
-    const session = await this.ensureSession();
-    const { accountId } = session;
-
-    // Round 1: discover the sending identity + the Drafts mailbox.
-    const discovery = await this.api({
-      using: [CORE_CAPABILITY, MAIL_CAPABILITY, SUBMISSION_CAPABILITY],
-      methodCalls: [
-        ["Identity/get", { accountId, ids: null }, "id"],
-        ["Mailbox/query", { accountId, filter: { role: "drafts" } }, "mq"],
-      ],
-    });
-    const identities = methodResponseArgs(discovery, "Identity/get")?.["list"];
-    const identity = Array.isArray(identities) ? asRecord(identities[0]) : null;
-    const identityId = identity === null ? null : asString(identity["id"]);
-    const identityEmail = identity === null ? null : asString(identity["email"]);
-    const mqIds = methodResponseArgs(discovery, "Mailbox/query")?.["ids"];
-    const draftMailboxId = Array.isArray(mqIds) ? asString(mqIds[0]) : null;
-    if (identityId === null || identityEmail === null || draftMailboxId === null) {
-      throw new Error("JMAP send: could not resolve sending identity or Drafts mailbox");
-    }
-
-    // Round 2: create the draft email + submit it.
-    const created = await this.api({
-      using: [CORE_CAPABILITY, MAIL_CAPABILITY, SUBMISSION_CAPABILITY],
-      methodCalls: [
-        [
-          "Email/set",
-          {
-            accountId,
-            create: {
-              draft: {
-                mailboxIds: { [draftMailboxId]: true },
-                keywords: { $draft: true, $seen: true },
-                from: [{ email: identityEmail }],
-                to: parseAddressList(input.to),
-                ...(input.cc === undefined ? {} : { cc: parseAddressList(input.cc) }),
-                ...(input.bcc === undefined ? {} : { bcc: parseAddressList(input.bcc) }),
-                subject: input.subject,
-                bodyStructure: { type: "text/plain", partId: "b" },
-                bodyValues: { b: { value: input.body } },
-              },
-            },
-          },
-          "es",
-        ],
-        [
-          "EmailSubmission/set",
-          {
-            accountId,
-            create: { sub: { emailId: "#draft", identityId } },
-          },
-          "sub",
-        ],
-      ],
-    });
-    const emailCreated = asRecord(methodResponseArgs(created, "Email/set")?.["created"]);
-    const emailId =
-      emailCreated === null ? null : asString(asRecord(emailCreated["draft"])?.["id"]);
-    const subCreated = asRecord(methodResponseArgs(created, "EmailSubmission/set")?.["created"]);
-    const submissionId = subCreated === null ? null : asString(asRecord(subCreated["sub"])?.["id"]);
-    return { emailId, submissionId };
-  }
-}
-
 const server = new McpServer({ name: "nimbus-fastmail", version: "0.1.0" });
-registerFastmailTools(server, new FetchJmapClient());
+registerFastmailTools(server, createFetchJmapClient());
 
 await server.connect(new StdioServerTransport());

package/connectors/fastmail/src/tools.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
 
-import { emailToolSchemas } from "../../../shared/imap-tool-kit.ts";
+import { emailToolSchemas, mailSendConsent, outgoingMail } from "../../../shared/imap-tool-kit.ts";
 import {
   createRegisterSimpleTool,
   type McpListResult,
@@ -105,30 +105,11 @@ export function registerFastmailTools(
 
   registerWriteTool(
     "fastmail_mail_send",
-    {
-      mutates: "fastmail.mail.send",
-      // A sent mail cannot be recalled and nothing remains to query, so the recipient and
-      // subject ARE the pre-state.
-      recoverable: false,
-      capturePreState: (p) => Promise.resolve({ to: p.to, subject: p.subject }),
-      scopeTargetOf: (p) => ({ kind: "recipient", value: p.to }),
-    },
+    mailSendConsent("fastmail.mail.send"),
     "Send a new email via JMAP EmailSubmission.",
     sendArgs,
-    async (parsedData): Promise<McpListResult> => {
-      const parsed = { success: true as const, data: parsedData };
-      const input: { to: string; subject: string; body: string; cc?: string; bcc?: string } = {
-        to: parsed.data.to,
-        subject: parsed.data.subject,
-        body: parsed.data.body,
-      };
-      if (parsed.data.cc !== undefined && parsed.data.cc !== "") {
-        input.cc = parsed.data.cc;
-      }
-      if (parsed.data.bcc !== undefined && parsed.data.bcc !== "") {
-        input.bcc = parsed.data.bcc;
-      }
-      const res = await client.send(input);
+    async (args): Promise<McpListResult> => {
+      const res = await client.send(outgoingMail(args));
       return mcpJsonResult({ emailId: res.emailId, submissionId: res.submissionId });
     },
   );

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

@@ -1,8 +1,7 @@
 import {
-  asObjectish,
+  fieldsFromKeys,
   makeQueryFilter,
   type SearchMatchOptions,
-  stringField,
 } from "../../../shared/search-filter.ts";
 
 export type FigmaSearchMatchOptions = SearchMatchOptions;
@@ -13,12 +12,4 @@ export type FigmaSearchMatchOptions = SearchMatchOptions;
  * a `project_name` label. Match against the file name and the project name
  * (case-insensitive substring).
  */
-function fieldsOf(item: unknown): readonly string[] | null {
-  const row = asObjectish(item);
-  if (row === undefined) {
-    return null;
-  }
-  return [stringField(row, "name"), stringField(row, "project_name")];
-}
-
-export const filterFigmaFiles = makeQueryFilter(fieldsOf);
+export const filterFigmaFiles = makeQueryFilter(fieldsFromKeys(["name", "project_name"]));

package/connectors/figma/src/server.ts

@@ -1,117 +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 { filterFigmaFiles } from "./search-filter.ts";
-
-const BASE = "https://api.figma.com";
-
-function apiToken(): string {
-  const t = process.env["FIGMA_TOKEN"]?.trim();
-  if (t === undefined || t === "") {
-    throw new Error("FIGMA_TOKEN is not set");
-  }
-  return t;
-}
-
-function teamId(): string {
-  const t = process.env["FIGMA_TEAM_ID"]?.trim();
-  if (t === undefined || t === "") {
-    throw new Error("FIGMA_TEAM_ID is not set");
-  }
-  return t;
-}
-
-function authHeader(): Record<string, string> {
-  return { Authorization: `Bearer ${apiToken()}`, Accept: "application/json" };
-}
-
-async function figmaGet(path: string): Promise<unknown> {
-  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`Figma ${String(res.status)}: ${text.slice(0, 400)}`);
-  }
-  return JSON.parse(text) as unknown;
-}
-
-function projectsFrom(root: unknown): Array<{ id: string; name: string }> {
-  const projects = (root as { projects?: unknown } | null)?.projects;
-  if (!Array.isArray(projects)) {
-    return [];
-  }
-  const out: Array<{ id: string; name: string }> = [];
-  for (const p of projects) {
-    const rec = p as { id?: unknown; name?: unknown } | null;
-    const id = rec?.id;
-    if (typeof id === "string" || typeof id === "number") {
-      out.push({
-        id: String(id),
-        name: typeof rec?.name === "string" ? rec.name : "",
-      });
-    }
-  }
-  return out;
-}
-
-function filesFrom(root: unknown): unknown[] {
-  const files = (root as { files?: unknown } | null)?.files;
-  return Array.isArray(files) ? files : [];
-}
-
-/**
- * Flatten the configured team's projects into a single list of files, tagging
- * each file with its `project_name` for searchability. This is the two-level
- * fetch: GET /v1/teams/<team_id>/projects, then GET /v1/projects/<id>/files for
- * each project.
- */
-async function listTeamFiles(): Promise<unknown[]> {
-  const projectsRoot = await figmaGet(`/v1/teams/${encodeURIComponent(teamId())}/projects`);
-  const projects = projectsFrom(projectsRoot);
-  const out: unknown[] = [];
-  for (const project of projects) {
-    const filesRoot = await figmaGet(`/v1/projects/${encodeURIComponent(project.id)}/files`);
-    for (const f of filesFrom(filesRoot)) {
-      const rec = f as Record<string, unknown> | null;
-      out.push({
-        ...rec,
-        project_id: project.id,
-        project_name: project.name,
-      });
-    }
-  }
-  return out;
-}
+import { registerFigmaTools } from "./tools.ts";
 
 await runReadOnlyMcpConnector("nimbus-figma", (reg) => {
-  reg(
-    "figma_list",
-    "List the configured team's Figma files. Two-level fetch: GET /v1/teams/<team_id>/projects (the team id is injected at spawn from the figma.team_id vault key) returns { name, projects: [{ id, name }] }; then for each project GET /v1/projects/<project_id>/files returns { name, files: [{ key, name, thumbnail_url, last_modified }] }. Returns a flattened { files: [...] } envelope where each file is shaped { key, name, thumbnail_url, last_modified, project_id, project_name }. Neither endpoint paginates — each returns the full list.",
-    z.object({}),
-    async () => {
-      return jsonResult({ files: await listTeamFiles() });
-    },
-  );
-
-  reg(
-    "figma_get",
-    "List the files in one Figma project by its id (GET /v1/projects/{projectId}/files). Returns the { name, files: [{ key, name, thumbnail_url, last_modified }] } envelope directly. Throws when no project with that id is accessible.",
-    z.object({
-      projectId: z.string().min(1),
-    }),
-    async (p) => {
-      return jsonResult(await figmaGet(`/v1/projects/${encodeURIComponent(p.projectId)}/files`));
-    },
-  );
-
-  reg(
-    "figma_search",
-    "Substring search across the configured team's Figma files. Runs the same two-level fetch as figma_list (team projects, then files per project), flattens the result, and matches the query locally (case-insensitive) against each file name and its project name. Returns a { matches: [...] } envelope.",
-    searchToolInputSchema(200),
-    async (p) => {
-      const files = await listTeamFiles();
-      const matches = filterFigmaFiles(files, { query: p.query, limit: p.limit });
-      return jsonResult({ matches });
-    },
-  );
+  registerFigmaTools(reg);
 });