@nimbus-dev/connectors 0.1.0

package/connectors/dependencytrack/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.dependencytrack",
+  "displayName": "Dependency-Track",
+  "version": "0.1.0",
+  "description": "OWASP Dependency-Track connector (read-only). Surfaces the user's software-supply-chain projects from a self-hosted Dependency-Track instance as `dependencytrack:project` items in the local index — the project name, version, classifier (APPLICATION / LIBRARY / CONTAINER / …), active flag, last BOM-import timestamp, tags, and the embedded vulnerability metrics (critical / high / medium / low counts, total vulnerabilities, and component count). Useful for answering supply-chain questions (\"which projects have critical vulnerabilities?\", \"what's the SBOM coverage for the payment service?\") without leaving Nimbus. Dependency-Track API-key auth (sent as the X-Api-Key request header). Dependency-Track has no universal SaaS host: the server host is supplied via the dependencytrack base-url vault key and added to the sandbox network list at spawn time by phase3AddDependencytrackMcp, so the static manifest network list is intentionally empty. The /api/v1/project endpoint paginates by pageNumber / pageSize (pageSize max 100); the connector walks a single forward page-number pass per cycle, capped. v1 indexes projects only — individual findings and components 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/dependencytrack/src/search-filter.ts

@@ -0,0 +1,24 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+  tagNamesFromObjects,
+} from "../../../shared/search-filter.ts";
+
+export type DependencyTrackSearchMatchOptions = SearchMatchOptions;
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [
+    stringField(row, "name"),
+    stringField(row, "version"),
+    stringField(row, "classifier"),
+    tagNamesFromObjects(row),
+  ];
+}
+
+export const filterDependencyTrackProjects = makeQueryFilter(fieldsOf);

package/connectors/dependencytrack/src/server.ts

@@ -0,0 +1,80 @@
+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 { filterDependencyTrackProjects } from "./search-filter.ts";
+
+function trimTrailingSlash(s: string): string {
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+
+function apiBase(): string {
+  const v = process.env["DEPENDENCYTRACK_URL"]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error("DEPENDENCYTRACK_URL is not set");
+  }
+  return trimTrailingSlash(v);
+}
+
+function authHeader(): Record<string, string> {
+  const k = process.env["DEPENDENCYTRACK_API_KEY"]?.trim();
+  if (k === undefined || k === "") {
+    throw new Error("DEPENDENCYTRACK_API_KEY is not set");
+  }
+  return { "X-Api-Key": k, Accept: "application/json" };
+}
+
+async function dtGet(path: string): Promise<unknown> {
+  const res = await fetch(`${apiBase()}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Dependency-Track ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function projectsFrom(root: unknown): unknown[] {
+  return Array.isArray(root) ? root : [];
+}
+
+await runReadOnlyMcpConnector("nimbus-dependencytrack", (reg) => {
+  reg(
+    "dependencytrack_list",
+    "List Dependency-Track projects (GET /api/v1/project?pageSize=100&pageNumber=1&excludeInactive=false). Dependency-Track returns a JSON array of project objects, each embedding its current vulnerability metrics. The optional pageNumber arg (default 1) selects the page; pageSize is fixed at 100.",
+    z.object({
+      pageNumber: z.number().int().min(1).optional(),
+    }),
+    async (p) => {
+      const page = p.pageNumber ?? 1;
+      const root = await dtGet(
+        `/api/v1/project?pageSize=100&pageNumber=${encodeURIComponent(String(page))}&excludeInactive=false`,
+      );
+      return jsonResult({ items: projectsFrom(root) });
+    },
+  );
+
+  reg(
+    "dependencytrack_get",
+    "Fetch one Dependency-Track project by its UUID (GET /api/v1/project/{uuid}). Returns the project object directly (NOT wrapped in an array). Throws when no project with that UUID exists.",
+    z.object({
+      uuid: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await dtGet(`/api/v1/project/${encodeURIComponent(p.uuid)}`));
+    },
+  );
+
+  reg(
+    "dependencytrack_search",
+    "Substring search across the first page of Dependency-Track projects. Matches the query (case-insensitive) against the project name, version, classifier, and tag names. Returns a matches envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const root = await dtGet("/api/v1/project?pageSize=100&pageNumber=1&excludeInactive=false");
+      const matches = filterDependencyTrackProjects(projectsFrom(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+});

package/connectors/discord/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.discord",
+  "displayName": "Discord",
+  "version": "0.1.0",
+  "description": "Discord opt-in connector (guilds, channels, messages). Disabled by default. Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["discord.com", "gateway.discord.gg", "cdn.discordapp.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 120,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/discord/src/server.ts

@@ -0,0 +1,93 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { createRegisterSimpleTool, createZodToolRegistrar } from "../../../shared/mcp-tool-kit.ts";
+import { makeRestToolRegistrar } from "../../../shared/rest-tool-kit.ts";
+
+const DISCORD_API = "https://discord.com/api/v10";
+
+async function discordFetch(
+  token: string,
+  path: string,
+  init?: RequestInit,
+): Promise<{
+  ok: boolean;
+  status: number;
+  json: unknown;
+  text: string;
+}> {
+  const url = path.startsWith("http") ? path : `${DISCORD_API}${path}`;
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      Authorization: `Bot ${token}`,
+      "User-Agent": "NimbusMCP (https://github.com/nimbus-dev/nimbus)",
+      ...(init?.headers as Record<string, string> | undefined),
+    },
+  });
+  const text = await res.text();
+  let json: unknown;
+  try {
+    json = JSON.parse(text) as unknown;
+  } catch {
+    json = null;
+  }
+  return { ok: res.ok, status: res.status, json, text };
+}
+
+const server = new McpServer({ name: "nimbus-discord", version: "0.1.0" });
+
+const registerSimpleTool = createRegisterSimpleTool(server);
+const reg = createZodToolRegistrar(registerSimpleTool);
+
+/** Standard Discord read tool: token → discordFetch(buildPath) → mcpJsonResultIfOk("Discord"). */
+const registerDiscordTool = makeRestToolRegistrar({
+  registrar: reg,
+  tokenEnv: "DISCORD_BOT_TOKEN",
+  serviceLabel: "Discord",
+  fetch: discordFetch,
+});
+
+registerDiscordTool(
+  "discord_guild_list",
+  "List guilds the bot is a member of.",
+  z.object({}),
+  () => "/users/@me/guilds",
+);
+
+registerDiscordTool(
+  "discord_channel_list",
+  "List channels in a guild (id, type, name).",
+  z.object({ guildId: z.string().min(1) }),
+  (parsed) => `/guilds/${encodeURIComponent(parsed.guildId)}/channels`,
+);
+
+registerDiscordTool(
+  "discord_channel_messages",
+  "List recent messages in a channel (newest first). Optional `after` snowflake for incremental fetch.",
+  z.object({
+    channelId: z.string().min(1),
+    limit: z.number().int().min(1).max(100).optional(),
+    after: z.string().optional(),
+  }),
+  (parsed) => {
+    const lim = parsed.limit ?? 50;
+    const u = new URL(`${DISCORD_API}/channels/${encodeURIComponent(parsed.channelId)}/messages`);
+    u.searchParams.set("limit", String(lim));
+    if (parsed.after !== undefined && parsed.after !== "") {
+      u.searchParams.set("after", parsed.after);
+    }
+    return `${u.pathname}${u.search}`;
+  },
+);
+
+registerDiscordTool(
+  "discord_thread_list",
+  "List active threads in a guild (includes public threads the bot can see).",
+  z.object({ guildId: z.string().min(1) }),
+  (parsed) => `/guilds/${encodeURIComponent(parsed.guildId)}/threads/active`,
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/connectors/elasticsearch/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.elasticsearch",
+  "displayName": "Elasticsearch / Kibana",
+  "version": "0.1.0",
+  "description": "Elasticsearch / Kibana connector (read-only, Tier-3 metadata-only). Surfaces the user's Elasticsearch indices as `elasticsearch:index` items in the local index — the index name, health (green/yellow/red), status (open/close), document COUNT, store size in bytes, primary-shard and replica counts, UUID, and the index's field names + types from its mapping (SCHEMA metadata). Useful for answering operational/schema questions (\"which indices are red?\", \"what fields does the orders index have?\", \"how big is the logs-2026.05 index?\") without leaving Nimbus. This is a NO-ROW-DATA (Tier-3) connector: it indexes index METADATA only and NEVER document contents — it does not call `_search`, `_doc`, `_mget`, `_sql`, `_scroll`, or any endpoint that returns document SOURCE. Elasticsearch API-key auth (sent as the `Authorization: ApiKey <key>` request header). Elasticsearch has no universal SaaS host (self-hosted or Elastic Cloud): the cluster host is supplied via the elasticsearch url vault key and added to the sandbox network list at spawn time by phase3AddElasticsearchMcp, so the static manifest network list is intentionally empty. The connector walks `_cat/indices` for the metadata listing and per-index `_mapping` for field names + types, both capped. ES system indices (names starting with `.`) are skipped by default. 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/elasticsearch/src/server.ts

@@ -0,0 +1,6 @@
+import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { registerElasticsearchTools } from "./tools.ts";
+
+await runReadOnlyMcpConnector("nimbus-elasticsearch", (reg) => {
+  registerElasticsearchTools(reg);
+});

package/connectors/elasticsearch/src/tools.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+
+/**
+ * Elasticsearch / Kibana (Tier-3, metadata-only) MCP tool surface. ALL tools
+ * index schema / METADATA only — index names, health, status, document COUNTS,
+ * store sizes, shard/replica counts, and field names + types from the index
+ * mapping. NONE fetch document / row / hit data: no `_search`, no `_doc`, no
+ * `_mget`, no `_sql`, no `_scroll`. `elasticsearch_search` searches index NAMES,
+ * not document contents. The names are introspected by the `assertNoRowDataTools`
+ * contract test, so they must never contain a row-data segment
+ * (query/rows/sample/scan/preview/head/export/records/event/…).
+ */
+export const ELASTICSEARCH_TOOL_NAMES = [
+  "elasticsearch_list",
+  "elasticsearch_get",
+  "elasticsearch_search",
+] as const;
+
+function trimTrailingSlash(s: string): string {
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+
+function baseUrl(): string {
+  const v = process.env["ELASTICSEARCH_URL"]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error("ELASTICSEARCH_URL is not set");
+  }
+  return trimTrailingSlash(v);
+}
+
+function authHeaders(): Record<string, string> {
+  const k = process.env["ELASTICSEARCH_API_KEY"]?.trim();
+  if (k === undefined || k === "") {
+    throw new Error("ELASTICSEARCH_API_KEY is not set");
+  }
+  return { Authorization: `ApiKey ${k}`, Accept: "application/json" };
+}
+
+async function esGet(path: string): Promise<unknown> {
+  const res = await fetch(`${baseUrl()}${path}`, { headers: authHeaders() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Elasticsearch ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function strField(r: Record<string, unknown>, key: string): string {
+  const v = r[key];
+  return typeof v === "string" ? v : "";
+}
+
+function indexEntries(parsed: unknown): unknown[] {
+  return Array.isArray(parsed) ? parsed : [];
+}
+
+function indexMatches(entry: unknown, q: string): boolean {
+  if (!isRecord(entry)) {
+    return false;
+  }
+  return strField(entry, "index").toLowerCase().includes(q.toLowerCase());
+}
+
+/**
+ * Register the read-only, metadata-only Elasticsearch tools onto the given
+ * registrar. Shared between `server.ts` (live) and the contract test
+ * (introspection).
+ */
+export function registerElasticsearchTools(reg: ZodToolRegistrar): void {
+  reg(
+    "elasticsearch_list",
+    "List Elasticsearch indices — METADATA ONLY (`GET /_cat/indices?format=json&bytes=b`). Each entry carries the index name, `health` (green/yellow/red), `status` (open/close), `docs.count` (a single document COUNT integer — metadata, NOT documents), `store.size` (bytes), primary-shard count `pri`, replica count `rep`, and `uuid`. Never returns document/hit source.",
+    z.object({}),
+    async () => {
+      return jsonResult({ items: indexEntries(await esGet("/_cat/indices?format=json&bytes=b")) });
+    },
+  );
+
+  reg(
+    "elasticsearch_get",
+    "Fetch one index's field MAPPING (schema) — METADATA ONLY (`GET /<index>/_mapping`). Returns the mapping object `{ <index>: { mappings: { properties: { <field>: { type } } } } }` — field names + types only, NO document values. The index name is URL-path-encoded.",
+    z.object({
+      index: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await esGet(`/${encodeURIComponent(p.index)}/_mapping`));
+    },
+  );
+
+  reg(
+    "elasticsearch_search",
+    "Substring search over index NAMES (case-insensitive) — METADATA ONLY. Lists indices via `GET /_cat/indices?format=json&bytes=b` and filters by name. Returns a `{ matches: [...] }` envelope of index metadata entries. This searches index names/metadata only and NEVER document contents — it does not run a query against documents.",
+    z.object({
+      query: z.string().min(1),
+      limit: z.number().int().min(1).max(500).optional(),
+    }),
+    async (p) => {
+      const all = indexEntries(await esGet("/_cat/indices?format=json&bytes=b"));
+      const filtered = all.filter((e) => indexMatches(e, p.query));
+      const matches = p.limit === undefined ? filtered : filtered.slice(0, p.limit);
+      return jsonResult({ matches });
+    },
+  );
+}

package/connectors/fastmail/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.fastmail",
+  "displayName": "Fastmail (JMAP)",
+  "version": "0.1.0",
+  "description": "Fastmail email connector over native JMAP (Tier-4 EMAIL class). Indexes the user's Fastmail mailbox as `fastmail:email` items — message HEADERS (subject, from, to/cc, received date, message-id), a short capped plain-text body PREVIEW (~2 KB / 2000 chars), and attachment METADATA only (filename, size, mimetype). It NEVER downloads or parses attachment bytes and never fetches the full message body: the JMAP `Email/get` calls request `maxBodyValueBytes` so the server truncates the body value before it crosses the wire, and only the `attachments` body-part metadata is read — the `blobId` download URL is never dereferenced. Read tools (`fastmail_list`, `fastmail_get`, `fastmail_search`) plus one HITL-gated write tool (`fastmail_mail_send`) that submits a new email via JMAP EmailSubmission. Auth is a single Fastmail API token, injected as the scoped environment variable FASTMAIL_API_TOKEN at spawn time (with an optional FASTMAIL_BASE_URL override) — the connector never reads the vault. JMAP is pure HTTPS to api.fastmail.com (the session, api, and any upload/download endpoints are all under that host), so the sandbox network allow-list is a single static 443 host.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.fastmail.com"],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "hitlRequired": ["write"],
+  "syncInterval": 300,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,86 @@
+/**
+ * JMAP connector core — transport-agnostic logic for the Fastmail read tools
+ * (`fastmail_list`, `fastmail_get`, `fastmail_search`) and the HITL-gated send
+ * tool (`fastmail_mail_send`).
+ *
+ * HARD SCOPE CONSTRAINT (security): this connector indexes/returns HEADERS + a
+ * short capped plain-text body PREVIEW + attachment METADATA only. The JMAP
+ * `Email/get` calls request `maxBodyValueBytes` (the server truncates the body
+ * value, so a full body never crosses the wire) and store only the `attachments`
+ * body-part METADATA (name/size/type) — the `blobId` download URL is NEVER
+ * dereferenced. There is no surface to fetch attachment bytes or a full body.
+ *
+ * The JMAP transport (real over `fetch`) is injected so tests never open a socket.
+ *
+ * Pure JMAP parsing and request-building is provided by `@nimbus-dev/sdk`
+ * (gateway ↔ mcp boundary — neither package can import the other).
+ */
+
+import type { JmapEmailView } from "@nimbus-dev/sdk";
+
+export {
+  asRecord,
+  asString,
+  buildGetRequest,
+  buildListRequest,
+  buildSearchRequest,
+  CORE_CAPABILITY,
+  capPreview,
+  EMAIL_PROPERTIES,
+  extractAttachments,
+  extractEmailList,
+  formatAddress,
+  formatAddresses,
+  type JmapAttachmentMeta,
+  type JmapEmailView,
+  type JmapSession,
+  MAIL_CAPABILITY,
+  MAX_BODY_VALUE_BYTES,
+  methodResponseArgs,
+  PREVIEW_MAX_CHARS,
+  parseSession,
+  previewFor,
+  SUBMISSION_CAPABILITY,
+  validateApiUrl,
+  viewEmail,
+} from "@nimbus-dev/sdk";
+
+const DEFAULT_LIST_LIMIT = 50;
+const MAX_LIST_LIMIT = 200;
+
+/** 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;
+}
+
+export interface SendMailResult {
+  readonly emailId: string | null;
+  readonly submissionId: string | null;
+}
+
+/**
+ * Minimal Fastmail/JMAP client surface the tools depend on. Implemented for real
+ * by the fetch adapter in `server.ts` and by a fake in tests. Deliberately
+ * exposes ONLY header/attachment-metadata + capped-preview reads + a send.
+ */
+export interface JmapClient {
+  list(limit: number): Promise<JmapEmailView[]>;
+  get(id: string): Promise<JmapEmailView | null>;
+  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

@@ -0,0 +1,194 @@
+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 { 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());
+
+await server.connect(new StdioServerTransport());