carlyemail-toolkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SWH Labs LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# carlyemail-toolkit
+
+CarlyEmail's email tools for the Vercel AI SDK, LangChain, and any other agent
+framework. A real inbox your agent can send, receive and reply from, without
+writing the tools yourself.
+
+```bash
+npm install carlyemail-toolkit
+export CARLYEMAIL_API_KEY=ce_us_...
+```
+
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { ToolLoopAgent } from "ai";
+import { CarlyEmailToolkit } from "carlyemail-toolkit/ai-sdk";
+
+const agent = new ToolLoopAgent({
+  model: openai("gpt-5-mini"),
+  instructions: "Read the thread before replying. Draft when unsure.",
+  tools: new CarlyEmailToolkit().getTools(),
+});
+```
+
+```typescript
+import { createAgent } from "langchain";
+import { CarlyEmailToolkit } from "carlyemail-toolkit/langchain";
+
+const agent = createAgent({ model: "openai:gpt-5-mini", tools: new CarlyEmailToolkit().getTools() });
+```
+
+```typescript
+import { CarlyEmailToolkit } from "carlyemail-toolkit"; // no framework
+
+for (const tool of new CarlyEmailToolkit().getTools()) {
+  tool.name, tool.description, tool.inputSchema, tool.annotations.readOnlyHint;
+  await tool.func({ thread_id: "..." }); // runs it
+}
+```
+
+Plain ES modules with no build step; types ship with it. `ai` and
+`@langchain/core` are optional peers — install the one you use.
+
+## What is in it
+
+The 25 tools the hosted [MCP server](https://docs.carlyemail.com/mcp) serves —
+inboxes, threads, messages, drafts, attachments, labels, and account
+verification — with the same names, descriptions and parameter schemas, called
+over the REST API. Pass names to take only some:
+
+```typescript
+const tools = new CarlyEmailToolkit().getTools(["list_messages", "get_thread", "reply_to_message"]);
+```
+
+A name that is not a tool throws rather than being dropped.
+
+## Which inbox
+
+Every tool takes `inbox_id`, and most work without it. A key scoped to one
+inbox means that inbox. An organization with one inbox means that one. With
+several, the tools that read threads and drafts look across all of them, and
+every other tool refuses and names the inboxes so the agent can ask which —
+the same behaviour as the hosted server.
+
+## Errors
+
+A failed call throws one bounded line carrying the API's message and the fix
+it suggests. The AI SDK reports that as a `tool-error` part; LangChain's tool
+node hands it back to the model as an error message.
+
+See <https://docs.carlyemail.com/integrations/toolkit>.

package/ai-sdk.d.ts

@@ -0,0 +1,7 @@
+import type { Tool } from "ai";
+
+import { MapToolkit, ToolDefinition } from "./index.js";
+
+export declare class CarlyEmailToolkit extends MapToolkit<Tool> {
+  protected buildTool(tool: ToolDefinition): Tool;
+}

package/ai-sdk.js

@@ -0,0 +1,27 @@
+// CarlyEmail tools for the Vercel AI SDK.
+//
+//     import { CarlyEmailToolkit } from "carlyemail-toolkit/ai-sdk";
+//     const agent = new ToolLoopAgent({ model, tools: new CarlyEmailToolkit().getTools() });
+//
+// A failed call throws, which the AI SDK reports as a `tool-error` part
+// rather than a successful result that happens to describe a failure.
+
+import { jsonSchema, tool } from "ai";
+
+import { MapToolkit, errorMessage } from "./core.js";
+
+export class CarlyEmailToolkit extends MapToolkit {
+  buildTool(definition) {
+    return tool({
+      description: definition.description,
+      inputSchema: jsonSchema(definition.inputSchema),
+      execute: async (args) => {
+        try {
+          return await definition.func(this.client, args ?? {});
+        } catch (error) {
+          throw new Error(errorMessage(error), { cause: error });
+        }
+      },
+    });
+  }
+}

package/core.js

@@ -0,0 +1,422 @@
+// The tools, the SDK call behind each one, and the toolkit shape every adapter
+// shares.
+//
+// Names, descriptions, parameter schemas and annotations come from `tools.js`,
+// written from the hosted MCP server's registry by `tools/gen_toolkit_tools.py`
+// in the API repository. Nothing in this file describes a tool; it only says
+// what to do when one is called.
+//
+// The one piece of behaviour here that is not a straight SDK call is what
+// happens when a tool is called without `inbox_id`. The hosted server resolves
+// that for the model — an inbox-scoped key means that inbox, an organization
+// with one inbox means that one, and several means the server refuses and
+// names them rather than picking on somebody's behalf. The toolkit does the
+// same, with the same words, so an agent behaves identically whichever way it
+// is connected.
+
+import { CarlyEmail, CarlyEmailError } from "carlyemail";
+
+import definitions from "./tools.js";
+
+/** What to tell a fresh account that has no inbox yet. The server's words. */
+export const FIRST_INBOX = definitions.first_inbox;
+
+// ------------------------------------------------------------------ errors
+
+/** A validation error body can list every field it disliked. That is useful
+ * to a person and useless to a model, which reads the first sentence and
+ * acts. */
+const MAX_MESSAGE_LENGTH = 500;
+
+/** A refusal made on this side of the wire, before any request went out.
+ * Carries `code` and `fix` the way the API's own errors do. */
+export class ToolkitError extends Error {
+  constructor(message, { code, fix }) {
+    super(message);
+    this.name = "ToolkitError";
+    this.code = code;
+    this.fix = fix;
+  }
+}
+
+/** One bounded sentence or three: what went wrong, what clears it, where to
+ * read more. The API answers errors with `message`, `fix` and `docs`, and the
+ * SDK keeps all three on the exception. */
+export function errorMessage(error) {
+  let text;
+  if (error instanceof ToolkitError) {
+    text = `${error.message} ${error.fix}`;
+  } else if (error instanceof CarlyEmailError) {
+    const parts = [error.message];
+    if (error.fix) parts.push(String(error.fix));
+    if (error.docs) parts.push(`See ${error.docs}`);
+    const tag = error.code ? `${error.code}, HTTP ${error.status}` : `HTTP ${error.status}`;
+    text = `${parts.join(" ")} (${tag})`;
+  } else if (error instanceof Error) {
+    text = `${error.name}: ${error.message}`;
+  } else {
+    text = String(error);
+  }
+  return text.length > MAX_MESSAGE_LENGTH ? `${text.slice(0, MAX_MESSAGE_LENGTH)}…` : text;
+}
+
+// ------------------------------------------------------------------- scope
+
+// The identity behind a key never changes for the life of the key, so it is
+// asked for once per client — the promise is stored, so two tools starting
+// together share one request. The inbox list is not cached: `create_inbox` is
+// one of the tools, and the call after it should see what it made.
+const identities = new WeakMap();
+
+function identity(client) {
+  let pending = identities.get(client);
+  if (!pending) {
+    pending = client.auth.whoami();
+    identities.set(client, pending);
+  }
+  return pending;
+}
+
+/** Work out what a call is addressed to, without deciding what to do about
+ * it. Zero inboxes and several inboxes are both legitimate states; reads
+ * answer them by looking across the organization and writes refuse, so this
+ * never throws over the organization's shape. */
+export async function resolveScope(client, inboxId) {
+  if (inboxId) return { inbox: inboxId, candidates: [], empty: false };
+  const keyed = (await identity(client)).inbox_id;
+  if (keyed) return { inbox: keyed, candidates: [], empty: false };
+  // Two would be enough to tell "one" from "several", but the refusal names
+  // the candidates, so fetch enough to list them.
+  const { inboxes } = await client.inboxes.list({ limit: 11 });
+  const ids = inboxes.map((row) => row.inbox_id);
+  if (ids.length === 1) return { inbox: ids[0], candidates: [], empty: false };
+  if (ids.length) return { inbox: null, candidates: ids, empty: false };
+  return { inbox: null, candidates: [], empty: true };
+}
+
+/** The single inbox to act on, or a refusal that says how to name one. Which
+ * address a message is sent from is the person's decision, so when an
+ * organization has several the candidates are reported rather than chosen
+ * between. */
+export async function oneInbox(client, inboxId) {
+  const scope = await resolveScope(client, inboxId);
+  if (scope.inbox) return scope.inbox;
+  if (scope.empty) {
+    throw new ToolkitError(
+      "This organization has no inboxes yet, so there is no mailbox to act on.",
+      { code: "no_inbox", fix: FIRST_INBOX },
+    );
+  }
+  const shown = scope.candidates.slice(0, 10).join(", ");
+  const more = scope.candidates.length > 10 ? " and others" : "";
+  throw new ToolkitError(
+    `This organization has ${scope.candidates.length} inboxes, so inbox_id is required.`,
+    {
+      code: "inbox_id_required",
+      fix: `Ask the person which one to use — ${shown}${more} — and pass it as inbox_id. Do not pick for them.`,
+    },
+  );
+}
+
+/** Attach the first-run instruction when there was nowhere to read from. An
+ * empty organization is not a failed call; what must not be lost is the
+ * instruction. */
+function guided(payload, scope) {
+  if (scope.empty && payload && typeof payload === "object") payload.next_step = FIRST_INBOX;
+  return payload;
+}
+
+/** The named arguments that were actually given. */
+function pick(args, ...names) {
+  const out = {};
+  for (const name of names) {
+    if (args[name] !== undefined && args[name] !== null) out[name] = args[name];
+  }
+  return out;
+}
+
+const camel = (name) => name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+
+/** Query parameters, in the SDK's camelCase. Bodies stay as the API spells
+ * them; only the generated query option names are camelCased. */
+function query(args, ...names) {
+  const out = {};
+  for (const [name, value] of Object.entries(pick(args, ...names))) out[camel(name)] = value;
+  return out;
+}
+
+const PAGE = ["limit", "page_token"];
+const WINDOW = ["before", "after"];
+const OUTBOUND = ["cc", "bcc", "subject", "text", "html", "labels", "reply_to", "headers", "attachments"];
+
+// -------------------------------------------------------------- functions
+
+async function listInboxes(client, a) {
+  const out = await client.inboxes.list(query(a, ...PAGE));
+  if (!out.inboxes?.length) out.next_step = FIRST_INBOX;
+  return out;
+}
+
+async function getInbox(client, a) {
+  return client.inboxes.get(await oneInbox(client, a.inbox_id));
+}
+
+async function createInbox(client, a) {
+  return client.inboxes.create(pick(a, "username", "domain", "display_name", "client_id", "metadata"));
+}
+
+async function updateInbox(client, a) {
+  const inbox = await oneInbox(client, a.inbox_id);
+  return client.inboxes.update(inbox, pick(a, "display_name", "metadata"));
+}
+
+async function deleteInbox(client, a) {
+  const inbox = await oneInbox(client, a.inbox_id);
+  await client.inboxes.delete(inbox);
+  return { deleted: true, inbox_id: inbox };
+}
+
+async function listThreads(client, a) {
+  const scope = await resolveScope(client, a.inbox_id);
+  const q = query(a, ...PAGE, ...WINDOW, "labels", "ascending", "senders", "recipients", "subject");
+  if (scope.inbox) return client.threads.list(scope.inbox, q);
+  return guided(await client.threads.listOrg(q), scope);
+}
+
+async function searchThreads(client, a) {
+  const scope = await resolveScope(client, a.inbox_id);
+  const q = { q: a.query, ...query(a, ...PAGE, ...WINDOW) };
+  if (scope.inbox) return client.threads.search(scope.inbox, q);
+  return guided(await client.threads.searchOrg(q), scope);
+}
+
+async function getThread(client, a) {
+  const scope = await resolveScope(client, a.inbox_id);
+  if (scope.inbox) return client.threads.get(scope.inbox, a.thread_id);
+  return client.threads.getOrg(a.thread_id);
+}
+
+async function updateThread(client, a) {
+  const scope = await resolveScope(client, a.inbox_id);
+  const body = pick(a, "add_labels", "remove_labels");
+  if (scope.inbox) return client.threads.update(scope.inbox, a.thread_id, body);
+  return client.threads.updateOrg(a.thread_id, body);
+}
+
+async function deleteThread(client, a) {
+  const scope = await resolveScope(client, a.inbox_id);
+  if (scope.inbox) await client.threads.delete(scope.inbox, a.thread_id);
+  else await client.threads.deleteOrg(a.thread_id);
+  return { deleted: true, thread_id: a.thread_id };
+}
+
+async function listMessages(client, a) {
+  const inbox = await oneInbox(client, a.inbox_id);
+  const q = query(a, ...PAGE, ...WINDOW, "labels", "ascending", "include_spam", "from", "to", "subject");
+  return client.messages.list(inbox, q);
+}
+
+async function searchMessages(client, a) {
+  const inbox = await oneInbox(client, a.inbox_id);
+  return client.messages.search(inbox, { q: a.query, ...query(a, ...PAGE, ...WINDOW) });
+}
+
+async function sendMessage(client, a) {
+  const inbox = await oneInbox(client, a.inbox_id);
+  return client.messages.send(inbox, pick(a, "to", ...OUTBOUND));
+}
+
+async function replyToMessage(client, a) {
+  const inbox = await oneInbox(client, a.inbox_id);
+  return client.messages.reply(inbox, a.message_id, pick(a, "to", "reply_all", ...OUTBOUND));
+}
+
+async function forwardMessage(client, a) {
+  const inbox = await oneInbox(client, a.inbox_id);
+  return client.messages.forward(inbox, a.message_id, pick(a, "to", ...OUTBOUND));
+}
+
+async function updateMessage(client, a) {
+  const inbox = await oneInbox(client, a.inbox_id);
+  return client.messages.update(inbox, a.message_id, pick(a, "add_labels", "remove_labels"));
+}
+
+async function getAttachment(client, a) {
+  const inbox = await oneInbox(client, a.inbox_id);
+  return client.messages.getAttachment(inbox, a.message_id, a.attachment_id);
+}
+
+async function createDraft(client, a) {
+  const inbox = await oneInbox(client, a.inbox_id);
+  const body = pick(a, "to", ...OUTBOUND, "in_reply_to", "forward_of", "reply_all", "send_at", "client_id");
+  delete body.headers;
+  return client.drafts.create(inbox, body);
+}
+
+async function listDrafts(client, a) {
+  const scope = await resolveScope(client, a.inbox_id);
+  const q = query(a, ...PAGE, ...WINDOW, "labels", "ascending");
+  if (scope.inbox) return client.drafts.list(scope.inbox, q);
+  return guided(await client.drafts.listOrg(q), scope);
+}
+
+async function getDraft(client, a) {
+  const scope = await resolveScope(client, a.inbox_id);
+  if (scope.inbox) return client.drafts.get(scope.inbox, a.draft_id);
+  return client.drafts.getOrg(a.draft_id);
+}
+
+/** The inbox a draft lives in, for the routes that need it in the path. A
+ * draft id is unique across the organization, so when several inboxes make
+ * the inbox ambiguous the draft itself can say. */
+async function draftInbox(client, a) {
+  const scope = await resolveScope(client, a.inbox_id);
+  if (scope.inbox) return scope.inbox;
+  if (scope.empty) return oneInbox(client, null); // throws with the first-inbox guidance
+  return (await client.drafts.getOrg(a.draft_id)).inbox_id;
+}
+
+async function updateDraft(client, a) {
+  const inbox = await draftInbox(client, a);
+  const body = pick(
+    a,
+    "to", "cc", "bcc", "subject", "text", "html", "reply_to", "send_at",
+    "add_labels", "remove_labels", "add_attachments", "remove_attachments",
+  );
+  return client.drafts.update(inbox, a.draft_id, body);
+}
+
+async function sendDraft(client, a) {
+  const inbox = await draftInbox(client, a);
+  return client.drafts.send(inbox, a.draft_id, {});
+}
+
+async function deleteDraft(client, a) {
+  const inbox = await draftInbox(client, a);
+  await client.drafts.delete(inbox, a.draft_id);
+  return { deleted: true, draft_id: a.draft_id };
+}
+
+async function authMe(client) {
+  const out = { ...(await client.auth.whoami()) };
+  // The first call a connected client makes, and so the earliest place a
+  // missing mailbox can be mentioned.
+  if (!out.inbox_id && !(await client.inboxes.list({ limit: 1 })).inboxes?.length) {
+    out.inbox_count = 0;
+    out.next_step = FIRST_INBOX;
+  }
+  return out;
+}
+
+async function verifyAccount(client, a) {
+  return client.agent.verify({ otp_code: String(a.code).trim() });
+}
+
+export const FUNCTIONS = {
+  auth_me: authMe,
+  create_draft: createDraft,
+  create_inbox: createInbox,
+  delete_draft: deleteDraft,
+  delete_inbox: deleteInbox,
+  delete_thread: deleteThread,
+  forward_message: forwardMessage,
+  get_attachment: getAttachment,
+  get_draft: getDraft,
+  get_inbox: getInbox,
+  get_thread: getThread,
+  list_drafts: listDrafts,
+  list_inboxes: listInboxes,
+  list_messages: listMessages,
+  list_threads: listThreads,
+  reply_to_message: replyToMessage,
+  search_messages: searchMessages,
+  search_threads: searchThreads,
+  send_draft: sendDraft,
+  send_message: sendMessage,
+  update_draft: updateDraft,
+  update_inbox: updateInbox,
+  update_message: updateMessage,
+  update_thread: updateThread,
+  verify_account: verifyAccount,
+};
+
+function assemble() {
+  const defined = new Set(definitions.tools.map((t) => t.name));
+  const implemented = new Set(Object.keys(FUNCTIONS));
+  const undefinedOnes = [...implemented].filter((n) => !defined.has(n));
+  const unimplemented = [...defined].filter((n) => !implemented.has(n));
+  // Loud at import, not at the first call. A tool with no function would
+  // otherwise be advertised to the model and fail when chosen.
+  if (undefinedOnes.length || unimplemented.length) {
+    throw new Error(
+      `tools.js and FUNCTIONS disagree: undefined ${JSON.stringify(undefinedOnes)}, ` +
+        `unimplemented ${JSON.stringify(unimplemented)}`,
+    );
+  }
+  return definitions.tools.map((t) => ({
+    name: t.name,
+    title: t.title,
+    description: t.description,
+    inputSchema: t.input_schema,
+    annotations: {
+      title: t.title,
+      readOnlyHint: t.read_only,
+      destructiveHint: t.destructive,
+      idempotentHint: t.idempotent,
+      openWorldHint: t.open_world,
+    },
+    func: FUNCTIONS[t.name],
+  }));
+}
+
+/** Every tool, in the order the server lists them. */
+export const TOOLS = assemble();
+
+// ----------------------------------------------------------------- toolkit
+
+/** Builds one framework-native tool per entry in `TOOLS`. Subclasses say how
+ * in `buildTool`; the client and the filter by name are shared. */
+export class BaseToolkit {
+  constructor(clientOrOptions) {
+    this.client =
+      clientOrOptions instanceof CarlyEmail ? clientOrOptions : new CarlyEmail(clientOrOptions ?? {});
+    this.tools = {};
+    for (const tool of TOOLS) this.tools[tool.name] = this.buildTool(tool);
+  }
+
+  buildTool() {
+    throw new Error("buildTool is what a subclass supplies");
+  }
+
+  /** The named tools, checked. A name that is not a tool is an error, not an
+   * omission: silently dropping it is how an agent ships with `send_message`
+   * misspelled and nobody finds out until it cannot send. */
+  select(names) {
+    if (!names) return Object.keys(this.tools);
+    const unknown = names.filter((name) => !(name in this.tools));
+    if (unknown.length) {
+      throw new Error(
+        `Unknown tool(s): ${unknown.join(", ")}. Available: ${Object.keys(this.tools).join(", ")}.`,
+      );
+    }
+    return names;
+  }
+
+  names() {
+    return Object.keys(this.tools);
+  }
+}
+
+/** `getTools()` is an array, for frameworks that take a list. */
+export class ListToolkit extends BaseToolkit {
+  getTools(names) {
+    return this.select(names).map((name) => this.tools[name]);
+  }
+}
+
+/** `getTools()` is an object keyed by name, for frameworks that take a map. */
+export class MapToolkit extends BaseToolkit {
+  getTools(names) {
+    return Object.fromEntries(this.select(names).map((name) => [name, this.tools[name]]));
+  }
+}

package/index.d.ts

@@ -0,0 +1,88 @@
+import { CarlyEmail } from "carlyemail";
+
+/** What to tell a fresh account that has no inbox yet. */
+export declare const FIRST_INBOX: string;
+
+/** MCP's tool annotations, which is what every framework that has an opinion
+ * about tool safety has converged on. */
+export interface ToolAnnotations {
+  title: string;
+  readOnlyHint: boolean;
+  destructiveHint: boolean;
+  idempotentHint: boolean;
+  openWorldHint: boolean;
+}
+
+export type JsonSchema = Record<string, unknown>;
+export type ToolArguments = Record<string, unknown>;
+
+/** One tool as every framework sees it, plus the function that runs it. */
+export interface ToolDefinition {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: JsonSchema;
+  annotations: ToolAnnotations;
+  func: (client: CarlyEmail, args: ToolArguments) => Promise<unknown>;
+}
+
+/** A tool tied to one client: call `func` with the model's arguments. */
+export interface Tool {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: JsonSchema;
+  annotations: ToolAnnotations;
+  func: (args?: ToolArguments) => Promise<unknown>;
+}
+
+/** Every tool, in the order the server lists them. */
+export declare const TOOLS: ToolDefinition[];
+
+/** A refusal made before any request went out, with `code` and `fix` the way
+ * the API's own errors carry them. */
+export declare class ToolkitError extends Error {
+  code: string;
+  fix: string;
+  constructor(message: string, options: { code: string; fix: string });
+}
+
+/** What a failed tool call says to the framework that made it. */
+export declare function errorMessage(error: unknown): string;
+
+export interface Scope {
+  inbox: string | null;
+  candidates: string[];
+  empty: boolean;
+}
+
+export declare function resolveScope(client: CarlyEmail, inboxId?: string | null): Promise<Scope>;
+export declare function oneInbox(client: CarlyEmail, inboxId?: string | null): Promise<string>;
+
+export interface ClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+
+export declare abstract class BaseToolkit<T> {
+  readonly client: CarlyEmail;
+  protected readonly tools: Record<string, T>;
+  constructor(clientOrOptions?: CarlyEmail | ClientOptions);
+  protected abstract buildTool(tool: ToolDefinition): T;
+  names(): string[];
+}
+
+export declare abstract class ListToolkit<T> extends BaseToolkit<T> {
+  /** All tools, or the named ones in the order named. An unknown name throws. */
+  getTools(names?: string[]): T[];
+}
+
+export declare abstract class MapToolkit<T> extends BaseToolkit<T> {
+  /** All tools, or the named ones, keyed by name. An unknown name throws. */
+  getTools(names?: string[]): Record<string, T>;
+}
+
+export declare class CarlyEmailToolkit extends ListToolkit<Tool> {
+  protected buildTool(tool: ToolDefinition): Tool;
+}

package/index.js

@@ -0,0 +1,42 @@
+// The tools with no framework around them.
+//
+//     import { CarlyEmailToolkit } from "carlyemail-toolkit";
+//     const tools = new CarlyEmailToolkit().getTools();
+//
+// Each has `name`, `title`, `description`, `inputSchema` (JSON Schema),
+// `annotations` (MCP's vocabulary) and `func(args)`, which is enough to hand
+// it to any framework this package has no adapter for.
+
+import { ListToolkit, errorMessage } from "./core.js";
+
+export {
+  FIRST_INBOX,
+  TOOLS,
+  ToolkitError,
+  errorMessage,
+  oneInbox,
+  resolveScope,
+  BaseToolkit,
+  ListToolkit,
+  MapToolkit,
+} from "./core.js";
+
+export class CarlyEmailToolkit extends ListToolkit {
+  buildTool(tool) {
+    return {
+      name: tool.name,
+      title: tool.title,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      annotations: tool.annotations,
+      func: async (args = {}) => {
+        try {
+          return await tool.func(this.client, args);
+        } catch (error) {
+          // One concise line, not the SDK's whole error object.
+          throw new Error(errorMessage(error), { cause: error });
+        }
+      },
+    };
+  }
+}

package/langchain.d.ts

@@ -0,0 +1,7 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
+
+import { ListToolkit, ToolDefinition } from "./index.js";
+
+export declare class CarlyEmailToolkit extends ListToolkit<StructuredToolInterface> {
+  protected buildTool(tool: ToolDefinition): StructuredToolInterface;
+}