@koderlabs/inbox-mcp 0.1.0

package/dist/chunk-T7SFANFP.js

@@ -0,0 +1,969 @@
+// @koderlabs/inbox-mcp — generated build, do not edit
+
+// ../../packages/shared/src/scopes.ts
+var SCOPE = {
+  INBOX_READ: "inbox:read",
+  INBOX_WRITE: "inbox:write",
+  EMAIL_READ: "email:read",
+  EMAIL_WRITE: "email:write"
+};
+var ALL_SCOPES = Object.values(SCOPE);
+
+// ../../packages/shared/src/types/organization.ts
+var OrgRole = /* @__PURE__ */ ((OrgRole2) => {
+  OrgRole2["OWNER"] = "OWNER";
+  OrgRole2["ADMIN"] = "ADMIN";
+  OrgRole2["MEMBER"] = "MEMBER";
+  return OrgRole2;
+})(OrgRole || {});
+
+// ../../packages/shared/src/constants.ts
+var MAX_EMAIL_SIZE_BYTES = 10 * 1024 * 1024;
+var PASSWORD_MIN_LENGTH = 8;
+var PASSWORD_MAX_LENGTH = 128;
+var NAME_MAX_LENGTH = 100;
+var ORG_NAME_MIN_LENGTH = 2;
+var ORG_NAME_MAX_LENGTH = 255;
+var LABEL_MAX_LENGTH = 255;
+var MAX_ADDRESS_LENGTH = 64;
+var ADDRESS_REGEX = /^[a-zA-Z0-9._-]+$/;
+
+// ../../packages/shared/src/schemas/auth.schema.ts
+import { z } from "zod";
+var passwordField = z.string().min(PASSWORD_MIN_LENGTH, `Password must be at least ${PASSWORD_MIN_LENGTH} characters.`).max(PASSWORD_MAX_LENGTH, `Password must be at most ${PASSWORD_MAX_LENGTH} characters.`);
+var emailField = z.string().email("Enter a valid email address.");
+var nameField = z.string().trim().max(NAME_MAX_LENGTH, `Must be at most ${NAME_MAX_LENGTH} characters.`).optional().or(z.literal(""));
+var loginSchema = z.object({
+  email: emailField,
+  password: z.string().min(1, "Password is required.")
+});
+var registerSchema = z.object({
+  firstName: nameField,
+  lastName: nameField,
+  email: emailField,
+  password: passwordField,
+  confirmPassword: z.string().min(1, "Confirm your password."),
+  organizationName: z.string().trim().min(ORG_NAME_MIN_LENGTH, `Organization name must be at least ${ORG_NAME_MIN_LENGTH} characters.`).max(ORG_NAME_MAX_LENGTH, `Organization name must be at most ${ORG_NAME_MAX_LENGTH} characters.`).optional().or(z.literal(""))
+}).refine((d) => d.password === d.confirmPassword, {
+  path: ["confirmPassword"],
+  message: "Passwords do not match."
+});
+var changePasswordSchema = z.object({
+  currentPassword: z.string().min(1, "Current password is required."),
+  newPassword: passwordField,
+  confirmNewPassword: z.string().min(1, "Confirm your new password.")
+}).refine((d) => d.newPassword === d.confirmNewPassword, {
+  path: ["confirmNewPassword"],
+  message: "Passwords do not match."
+});
+
+// ../../packages/shared/src/schemas/organization.schema.ts
+import { z as z2 } from "zod";
+var orgNameField = z2.string().trim().min(ORG_NAME_MIN_LENGTH, `Organization name must be at least ${ORG_NAME_MIN_LENGTH} characters.`).max(ORG_NAME_MAX_LENGTH, `Organization name must be at most ${ORG_NAME_MAX_LENGTH} characters.`);
+var createOrgSchema = z2.object({
+  name: orgNameField
+});
+var updateOrgSchema = z2.object({
+  name: orgNameField
+});
+var inviteMemberSchema = z2.object({
+  email: z2.string().email("Enter a valid email address."),
+  role: z2.enum(["ADMIN" /* ADMIN */, "MEMBER" /* MEMBER */])
+});
+var updateMemberRoleSchema = z2.object({
+  role: z2.nativeEnum(OrgRole)
+});
+
+// ../../packages/shared/src/schemas/inbox.schema.ts
+import { z as z3 } from "zod";
+var createInboxSchema = z3.object({
+  address: z3.string().trim().max(MAX_ADDRESS_LENGTH, `Address must be at most ${MAX_ADDRESS_LENGTH} characters.`).regex(ADDRESS_REGEX, "Address may only contain letters, numbers, dots, dashes, and underscores.").optional().or(z3.literal("")),
+  label: z3.string().trim().max(LABEL_MAX_LENGTH, `Label must be at most ${LABEL_MAX_LENGTH} characters.`).optional().or(z3.literal(""))
+});
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  McpError as McpError2,
+  ErrorCode as ErrorCode2
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/tools/discover/whoami.ts
+import { z as z4 } from "zod";
+
+// src/tools/define.ts
+import { zodToJsonSchema as convertZodToJsonSchema } from "zod-to-json-schema";
+function defineTool(definition) {
+  return definition;
+}
+function zodToJsonSchema(schema) {
+  const out = convertZodToJsonSchema(schema, {
+    target: "openApi3",
+    $refStrategy: "none"
+  });
+  delete out.$schema;
+  delete out.definitions;
+  return out;
+}
+
+// src/tools/discover/whoami.ts
+var DESCRIPTION = `
+USE WHEN:
+- You need to confirm the InstantInbox token is valid before running any
+  other tool.
+- The user asks "who am I" or "am I logged in to InstantInbox".
+- As a pre-flight before a long agentic workflow that creates inboxes
+  and waits for email.
+
+DO NOT USE:
+- More than once per session unless the token changes.
+- To list inboxes \u2014 use list_inboxes for that.
+
+TRIGGER PATTERNS:
+- "check my token"
+- "what inbox access do I have"
+- "verify InstantInbox auth"
+
+<examples>
+<example>
+<user>Am I logged in?</user>
+<tool>whoami</tool>
+<result>Authenticated as alice@example.com (user id: u_123). Granted scopes: inbox:read, inbox:write, email:read, email:write.</result>
+</example>
+</examples>
+`.trim();
+var whoamiTool = defineTool({
+  name: "whoami",
+  title: "Identify Current User",
+  annotations: { readOnlyHint: true, openWorldHint: true },
+  skills: ["discover"],
+  requiredScopes: [],
+  description: DESCRIPTION,
+  inputSchema: z4.object({}),
+  async handler(_params, ctx) {
+    const me = await ctx.apiClient.whoami();
+    const scopes = ctx.scopes.toArray().join(", ") || "(none)";
+    if (!me) {
+      return {
+        content: [{ type: "text", text: `Token valid but /auth/me returned no profile. Scopes: ${scopes}` }]
+      };
+    }
+    const lines = [
+      `Authenticated as ${me.email ?? "(unknown email)"} (user id: ${me.id})`,
+      `Scopes: ${scopes}`
+    ];
+    if (me.isEmailVerified === false) {
+      lines.push("Warning: email is NOT verified \u2014 some write operations may be rejected.");
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+});
+
+// src/tools/inboxes/list-inboxes.ts
+import { z as z5 } from "zod";
+
+// src/errors.ts
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+var UserInputError = class extends McpError {
+  constructor(message) {
+    super(ErrorCode.InvalidParams, message);
+    this.name = "UserInputError";
+  }
+};
+var ApiNotFoundError = class extends McpError {
+  constructor(resource, id) {
+    super(ErrorCode.InvalidParams, `${resource} not found: ${id}`);
+    this.name = "ApiNotFoundError";
+  }
+};
+var ScopeError = class extends McpError {
+  constructor(requiredScope) {
+    super(ErrorCode.InvalidRequest, `Token missing required scope: ${requiredScope}`);
+    this.name = "ScopeError";
+  }
+};
+var ApiError = class extends McpError {
+  constructor(message, statusCode) {
+    super(ErrorCode.InternalError, `InstantInbox API error: ${message}`);
+    this.statusCode = statusCode;
+    this.name = "ApiError";
+  }
+  statusCode;
+};
+var AuthError = class extends McpError {
+  constructor(reason, detail) {
+    super(ErrorCode.InvalidRequest, detail ? `${reason}: ${detail}` : reason);
+    this.reason = reason;
+    this.name = "AuthError";
+  }
+  reason;
+};
+
+// src/auth/scopes.ts
+var ScopeSet = class {
+  set;
+  constructor(scopes) {
+    this.set = new Set(scopes);
+  }
+  has(scope) {
+    return this.set.has(scope);
+  }
+  hasAll(scopes) {
+    return scopes.every((s) => this.set.has(s));
+  }
+  toArray() {
+    return [...this.set];
+  }
+};
+function assertScope(scopes, required) {
+  if (!scopes.has(required)) {
+    throw new ScopeError(required);
+  }
+}
+
+// src/formatting/inbox.ts
+function formatInbox(inbox) {
+  const meta = inbox;
+  const lines = [
+    `Inbox: ${inbox.address}`,
+    `  id: ${inbox.id}`
+  ];
+  if (inbox.label) lines.push(`  label: ${inbox.label}`);
+  if (typeof meta.emailCount === "number") lines.push(`  emails: ${meta.emailCount}`);
+  if (meta.lastReceivedAt) {
+    lines.push(`  last: ${meta.lastSubject ?? "(no subject)"} <${meta.lastFrom ?? "?"}> @ ${meta.lastReceivedAt}`);
+  }
+  lines.push(`  created: ${inbox.createdAt}`);
+  return lines.join("\n");
+}
+
+// src/tools/inboxes/list-inboxes.ts
+var DESCRIPTION2 = `
+USE WHEN:
+- You need to find an existing disposable inbox the caller already owns.
+- The user asks "what inboxes do I have" or "show my test inboxes".
+- You want to confirm an inbox exists before sending email to it.
+
+DO NOT USE:
+- To create a new inbox \u2014 use create_inbox.
+- To read messages \u2014 use list_emails or wait_for_email.
+
+REQUIRED SCOPE: inbox:read
+
+<examples>
+<example>
+<user>List my inboxes</user>
+<tool>list_inboxes</tool>
+<result>Inbox: ab12cd@inbox.koderlabs.net  (emails: 3, last: "Verify your email" ...)</result>
+</example>
+</examples>
+`.trim();
+var listInboxesTool = defineTool({
+  name: "list_inboxes",
+  title: "List Inboxes",
+  annotations: { readOnlyHint: true, openWorldHint: true },
+  skills: ["inboxes"],
+  requiredScopes: [SCOPE.INBOX_READ],
+  description: DESCRIPTION2,
+  inputSchema: z5.object({
+    organizationId: z5.string().optional().describe("Filter to inboxes in this organization"),
+    search: z5.string().optional().describe("Substring match on address or label"),
+    limit: z5.number().int().min(1).max(100).optional().describe("Default 20, max 100")
+  }),
+  async handler(params, ctx) {
+    assertScope(ctx.scopes, SCOPE.INBOX_READ);
+    const { items, meta } = await ctx.apiClient.listInboxes({
+      organizationId: params.organizationId,
+      search: params.search,
+      limit: params.limit ?? 20
+    });
+    if (items.length === 0) {
+      return { content: [{ type: "text", text: "No inboxes found. Use create_inbox to make one." }] };
+    }
+    const text = [
+      `Found ${meta.total} inbox(es), showing ${items.length}:`,
+      "",
+      ...items.map(formatInbox)
+    ].join("\n");
+    return { content: [{ type: "text", text }] };
+  }
+});
+
+// src/tools/inboxes/create-inbox.ts
+import { z as z6 } from "zod";
+var DESCRIPTION3 = `
+USE WHEN:
+- You are about to test an email-driven flow (signup verification, password
+  reset, magic link, etc.) and need a fresh disposable inbox to plug into
+  the app under test.
+- The user asks to "create a test inbox" or "give me a throwaway email".
+
+WHAT YOU GET BACK:
+- The full email address (e.g. ab12cd@inbox.koderlabs.net) \u2014 this is the
+  string you plug into the signup form, profile, etc.
+- The inbox id (UUID) \u2014 use this with list_emails / wait_for_email.
+
+NEXT STEP after calling this tool:
+- Trigger the flow that should send mail to this address.
+- Then call wait_for_email with this inbox's id.
+
+REQUIRED SCOPE: inbox:write
+
+<examples>
+<example>
+<user>Create a disposable inbox for testing the signup flow.</user>
+<tool>create_inbox {}</tool>
+<result>Created inbox: ab12cd@inbox.koderlabs.net (id u_abc). Use this address in the app, then call wait_for_email.</result>
+</example>
+</examples>
+`.trim();
+var createInboxTool = defineTool({
+  name: "create_inbox",
+  title: "Create Disposable Inbox",
+  annotations: { destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  skills: ["inboxes"],
+  requiredScopes: [SCOPE.INBOX_WRITE],
+  description: DESCRIPTION3,
+  inputSchema: z6.object({
+    address: z6.string().optional().describe('Local-part only (e.g. "alice"). Omit to auto-generate a random address.'),
+    label: z6.string().optional().describe("Human-readable label for this inbox"),
+    organizationId: z6.string().optional().describe("Scope to an organization; omit for personal inbox")
+  }),
+  async handler(params, ctx) {
+    assertScope(ctx.scopes, SCOPE.INBOX_WRITE);
+    const inbox = await ctx.apiClient.createInbox({
+      address: params.address,
+      label: params.label,
+      organizationId: params.organizationId
+    });
+    const text = [
+      `Inbox created: ${inbox.address}`,
+      `  id: ${inbox.id}`,
+      params.label ? `  label: ${params.label}` : null,
+      "",
+      `Next step: trigger the email flow with this address, then call wait_for_email with inboxId=${inbox.id}.`
+    ].filter(Boolean).join("\n");
+    return {
+      content: [{ type: "text", text }],
+      _meta: {
+        "instantinbox/inboxId": inbox.id,
+        "instantinbox/address": inbox.address
+      }
+    };
+  }
+});
+
+// src/tools/inboxes/get-inbox.ts
+import { z as z7 } from "zod";
+var DESCRIPTION4 = `
+USE WHEN:
+- You have an inbox id OR address and want its current state (label, counts,
+  last received email).
+- You need to translate an address back into an inbox id before calling
+  list_emails / wait_for_email.
+
+DO NOT USE to list multiple inboxes (use list_inboxes) or to fetch emails
+(use list_emails or get_email).
+
+REQUIRED SCOPE: inbox:read
+`.trim();
+var getInboxTool = defineTool({
+  name: "get_inbox",
+  title: "Get Inbox Details",
+  annotations: { readOnlyHint: true, openWorldHint: true },
+  skills: ["inboxes"],
+  requiredScopes: [SCOPE.INBOX_READ],
+  description: DESCRIPTION4,
+  inputSchema: z7.object({
+    inboxId: z7.string().optional().describe("Inbox UUID. One of inboxId or address required."),
+    address: z7.string().optional().describe("Full email address. One of inboxId or address required.")
+  }),
+  async handler(params, ctx) {
+    assertScope(ctx.scopes, SCOPE.INBOX_READ);
+    if (!params.inboxId && !params.address) {
+      throw new UserInputError("Provide either inboxId or address.");
+    }
+    const inbox = params.inboxId ? await ctx.apiClient.getInboxById(params.inboxId) : await ctx.apiClient.getInboxByAddress(params.address);
+    if (!inbox) throw new ApiNotFoundError("Inbox", params.inboxId ?? params.address);
+    return {
+      content: [{ type: "text", text: formatInbox(inbox) }],
+      _meta: { "instantinbox/inboxId": inbox.id, "instantinbox/address": inbox.address }
+    };
+  }
+});
+
+// src/tools/inboxes/delete-inbox.ts
+import { z as z8 } from "zod";
+var DESCRIPTION5 = `
+USE WHEN:
+- A test run is complete and the disposable inbox is no longer needed.
+- The user asks to "delete this inbox" or "clean up the test inbox".
+
+DESTRUCTIVE: This permanently deletes the inbox AND every email it ever
+received. There is no recovery. Idempotent \u2014 re-calling with the same id
+after deletion returns 404 from the API which this tool reports cleanly.
+
+REQUIRED SCOPE: inbox:write
+`.trim();
+var deleteInboxTool = defineTool({
+  name: "delete_inbox",
+  title: "Delete Inbox",
+  annotations: { destructiveHint: true, idempotentHint: true, openWorldHint: true },
+  skills: ["inboxes"],
+  requiredScopes: [SCOPE.INBOX_WRITE],
+  description: DESCRIPTION5,
+  inputSchema: z8.object({
+    inboxId: z8.string().describe("Inbox UUID")
+  }),
+  async handler(params, ctx) {
+    assertScope(ctx.scopes, SCOPE.INBOX_WRITE);
+    await ctx.apiClient.deleteInbox(params.inboxId);
+    return {
+      content: [{ type: "text", text: `Inbox ${params.inboxId} deleted (and all its emails).` }]
+    };
+  }
+});
+
+// src/tools/emails/list-emails.ts
+import { z as z9 } from "zod";
+
+// src/formatting/email.ts
+function snippet(text, max = 240) {
+  if (!text) return "";
+  const t = text.replace(/\s+/g, " ").trim();
+  return t.length > max ? `${t.slice(0, max)}\u2026` : t;
+}
+function formatEmailHeader(email) {
+  const read = email.readAt ? " " : "*";
+  return `${read} [${email.receivedAt}] ${email.fromAddress} \u2192 ${email.subject || "(no subject)"} (${email.id})`;
+}
+function formatEmail(email) {
+  const lines = [
+    `Email ${email.id}`,
+    `From:    ${email.fromAddress}`,
+    `To:      ${email.toAddress}`,
+    `Subject: ${email.subject || "(no subject)"}`,
+    `Date:    ${email.receivedAt}`,
+    `Read:    ${email.readAt ?? "no"}`,
+    `Attachments: ${email.attachmentsCount}`,
+    ""
+  ];
+  if (email.textBody) {
+    lines.push("--- text body ---", email.textBody);
+  } else if (email.htmlBody) {
+    lines.push("--- html body (text fallback unavailable) ---", snippet(email.htmlBody, 4e3));
+  } else {
+    lines.push("(no body)");
+  }
+  return lines.join("\n");
+}
+
+// src/tools/emails/list-emails.ts
+var DESCRIPTION6 = `
+USE WHEN:
+- You want to see what mail has already arrived in an inbox.
+- The user asks "what emails did I receive" or "show me the inbox".
+
+DO NOT USE:
+- To poll for a NOT-YET-ARRIVED email \u2014 use wait_for_email which long-polls
+  efficiently. Repeatedly calling list_emails in a tight loop wastes tokens
+  and load on the API.
+- To get the full body \u2014 use get_email; this tool only returns headers
+  (subject / from / date).
+
+REQUIRED SCOPE: email:read
+`.trim();
+var listEmailsTool = defineTool({
+  name: "list_emails",
+  title: "List Emails in Inbox",
+  annotations: { readOnlyHint: true, openWorldHint: true },
+  skills: ["emails"],
+  requiredScopes: [SCOPE.EMAIL_READ, SCOPE.INBOX_READ],
+  description: DESCRIPTION6,
+  inputSchema: z9.object({
+    inboxId: z9.string().optional().describe("Inbox UUID. One of inboxId or address required."),
+    address: z9.string().optional().describe("Full inbox email address. One of inboxId or address required."),
+    limit: z9.number().int().min(1).max(100).optional().describe("Default 20, max 100"),
+    unreadOnly: z9.boolean().optional().describe("Filter to unread emails only"),
+    since: z9.string().optional().describe("ISO timestamp \u2014 only emails received after this time")
+  }),
+  async handler(params, ctx) {
+    assertScope(ctx.scopes, SCOPE.EMAIL_READ);
+    if (!params.inboxId && !params.address) {
+      throw new UserInputError("Provide either inboxId or address.");
+    }
+    let inboxId = params.inboxId;
+    if (!inboxId) {
+      const inbox = await ctx.apiClient.getInboxByAddress(params.address);
+      if (!inbox) throw new ApiNotFoundError("Inbox", params.address);
+      inboxId = inbox.id;
+    }
+    const { items, meta } = await ctx.apiClient.listEmails(inboxId, {
+      limit: params.limit ?? 20,
+      unreadOnly: params.unreadOnly,
+      since: params.since
+    });
+    if (items.length === 0) {
+      return {
+        content: [{
+          type: "text",
+          text: "No emails in this inbox yet. If you are waiting for one, use wait_for_email to long-poll efficiently."
+        }]
+      };
+    }
+    const text = [
+      `Found ${meta.total} email(s), showing ${items.length} (\`*\` = unread):`,
+      ...items.map(formatEmailHeader)
+    ].join("\n");
+    return { content: [{ type: "text", text }] };
+  }
+});
+
+// src/tools/emails/get-email.ts
+import { z as z10 } from "zod";
+var DESCRIPTION7 = `
+USE WHEN:
+- You have an email id (from list_emails or wait_for_email) and need the
+  full body to extract a verification link, OTP code, or password reset
+  token.
+
+DO NOT USE to scan the inbox (use list_emails).
+
+REQUIRED SCOPE: email:read
+`.trim();
+var getEmailTool = defineTool({
+  name: "get_email",
+  title: "Get Email",
+  annotations: { readOnlyHint: true, openWorldHint: true },
+  skills: ["emails"],
+  requiredScopes: [SCOPE.EMAIL_READ],
+  description: DESCRIPTION7,
+  inputSchema: z10.object({
+    emailId: z10.string().describe("Email UUID")
+  }),
+  async handler(params, ctx) {
+    assertScope(ctx.scopes, SCOPE.EMAIL_READ);
+    const email = await ctx.apiClient.getEmail(params.emailId);
+    if (!email) throw new ApiNotFoundError("Email", params.emailId);
+    return {
+      content: [{ type: "text", text: formatEmail(email) }],
+      _meta: { "instantinbox/emailId": email.id, "instantinbox/inboxId": email.inboxId }
+    };
+  }
+});
+
+// src/tools/emails/wait-for-email.ts
+import { z as z11 } from "zod";
+var DESCRIPTION8 = `
+USE WHEN:
+- You have just triggered an action that should send mail (signup, password
+  reset, magic link, OTP) and you need to wait for it to arrive.
+- This is the canonical "did the email arrive?" tool \u2014 long-polls the API
+  every second up to \`timeoutSec\` (default 30s, max 120s) so the agent
+  blocks exactly as long as needed and no longer.
+
+ARGS:
+- inboxId OR address \u2014 required.
+- timeoutSec \u2014 how long to wait (1\u2013120, default 30).
+- subjectContains / fromContains \u2014 optional case-insensitive filters; the
+  first email matching both is returned.
+- sinceMs \u2014 only consider emails received after Date.now() - sinceMs.
+  Defaults to (timeoutSec + 5) seconds. Use this to avoid matching emails
+  that arrived before the trigger.
+
+RETURNS:
+- The full email (subject, from, body, headers) when one arrives.
+- \`{ timedOut: true, matched: 0 }\` if nothing arrives in time.
+
+DO NOT USE for general inbox browsing (use list_emails) \u2014 wait_for_email
+is meant for the "trigger \u2192 wait \u2192 extract" loop in E2E tests.
+
+REQUIRED SCOPE: email:read
+
+<examples>
+<example>
+<user>I signed up. Wait for the verification email.</user>
+<tool>wait_for_email { inboxId, subjectContains: "verify", timeoutSec: 60 }</tool>
+<result>Email arrived from no-reply@example.com \u2014 "Verify your email". Body contains link https://...</result>
+</example>
+</examples>
+`.trim();
+var waitForEmailTool = defineTool({
+  name: "wait_for_email",
+  title: "Wait For Email",
+  annotations: { readOnlyHint: true, openWorldHint: true },
+  skills: ["emails"],
+  requiredScopes: [SCOPE.EMAIL_READ, SCOPE.INBOX_READ],
+  description: DESCRIPTION8,
+  inputSchema: z11.object({
+    inboxId: z11.string().optional().describe("Inbox UUID. One of inboxId or address required."),
+    address: z11.string().optional().describe("Full inbox email address. One of inboxId or address required."),
+    timeoutSec: z11.number().int().min(1).max(120).optional().describe("Max wait, default 30s, hard cap 120s"),
+    subjectContains: z11.string().optional().describe("Case-insensitive substring match on subject"),
+    fromContains: z11.string().optional().describe("Case-insensitive substring match on from address"),
+    sinceMs: z11.number().int().min(0).optional().describe("Only match emails received within the last N ms (default: timeoutSec + 5s)")
+  }),
+  async handler(params, ctx) {
+    assertScope(ctx.scopes, SCOPE.EMAIL_READ);
+    if (!params.inboxId && !params.address) {
+      throw new UserInputError("Provide either inboxId or address.");
+    }
+    let inboxId = params.inboxId;
+    if (!inboxId) {
+      const inbox = await ctx.apiClient.getInboxByAddress(params.address);
+      if (!inbox) throw new ApiNotFoundError("Inbox", params.address);
+      inboxId = inbox.id;
+    }
+    const timeoutSec = Math.min(params.timeoutSec ?? 30, 120);
+    const sinceMs = params.sinceMs ?? (timeoutSec + 5) * 1e3;
+    const startedAt = Date.now();
+    const sinceIso = new Date(startedAt - sinceMs).toISOString();
+    const deadline = startedAt + timeoutSec * 1e3;
+    const subjectMatch = params.subjectContains?.toLowerCase();
+    const fromMatch = params.fromContains?.toLowerCase();
+    const pollIntervalMs = 1e3;
+    while (Date.now() < deadline) {
+      const { items } = await ctx.apiClient.listEmails(inboxId, {
+        limit: 50,
+        since: sinceIso
+      });
+      const match = items.find((e) => {
+        if (subjectMatch && !(e.subject ?? "").toLowerCase().includes(subjectMatch)) return false;
+        if (fromMatch && !(e.fromAddress ?? "").toLowerCase().includes(fromMatch)) return false;
+        return true;
+      });
+      if (match) {
+        const full = await ctx.apiClient.getEmail(match.id) ?? match;
+        const elapsedSec = ((Date.now() - startedAt) / 1e3).toFixed(1);
+        return {
+          content: [{
+            type: "text",
+            text: `Matched after ${elapsedSec}s.
+
+${formatEmail(full)}`
+          }],
+          _meta: {
+            "instantinbox/emailId": full.id,
+            "instantinbox/inboxId": inboxId,
+            "instantinbox/elapsedSec": Number(elapsedSec)
+          }
+        };
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await new Promise((r) => setTimeout(r, Math.min(pollIntervalMs, remaining)));
+    }
+    return {
+      content: [{
+        type: "text",
+        text: `Timed out after ${timeoutSec}s. No matching email arrived. Inbox: ${inboxId}.`
+      }],
+      _meta: { "instantinbox/timedOut": true, "instantinbox/matched": 0 }
+    };
+  }
+});
+
+// src/tools/emails/delete-email.ts
+import { z as z12 } from "zod";
+var DESCRIPTION9 = `
+USE WHEN:
+- A test run is complete and you want to clear specific emails from the
+  inbox before the next iteration.
+
+DESTRUCTIVE: deletes a single email permanently. Idempotent \u2014 re-calling
+with the same id after deletion is safe.
+
+DO NOT USE to delete an entire inbox (use delete_inbox).
+
+REQUIRED SCOPE: email:write
+`.trim();
+var deleteEmailTool = defineTool({
+  name: "delete_email",
+  title: "Delete Email",
+  annotations: { destructiveHint: true, idempotentHint: true, openWorldHint: true },
+  skills: ["emails"],
+  requiredScopes: [SCOPE.EMAIL_WRITE],
+  description: DESCRIPTION9,
+  inputSchema: z12.object({
+    emailId: z12.string().describe("Email UUID")
+  }),
+  async handler(params, ctx) {
+    assertScope(ctx.scopes, SCOPE.EMAIL_WRITE);
+    await ctx.apiClient.deleteEmail(params.emailId);
+    return { content: [{ type: "text", text: `Email ${params.emailId} deleted.` }] };
+  }
+});
+
+// src/tools/emails/mark-email-read.ts
+import { z as z13 } from "zod";
+var DESCRIPTION10 = `
+USE WHEN:
+- You want to mark an email as read or unread (e.g. so list_emails with
+  unreadOnly returns the expected set after you've processed one).
+
+Idempotent. Not destructive.
+
+REQUIRED SCOPE: email:write
+`.trim();
+var markEmailReadTool = defineTool({
+  name: "mark_email_read",
+  title: "Mark Email Read/Unread",
+  annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: true },
+  skills: ["emails"],
+  requiredScopes: [SCOPE.EMAIL_WRITE],
+  description: DESCRIPTION10,
+  inputSchema: z13.object({
+    emailId: z13.string().describe("Email UUID"),
+    read: z13.boolean().describe("true \u2192 mark read; false \u2192 mark unread")
+  }),
+  async handler(params, ctx) {
+    assertScope(ctx.scopes, SCOPE.EMAIL_WRITE);
+    const updated = params.read ? await ctx.apiClient.markRead(params.emailId) : await ctx.apiClient.markUnread(params.emailId);
+    return {
+      content: [{
+        type: "text",
+        text: `Email ${params.emailId} marked ${params.read ? "read" : "unread"} (readAt=${updated.readAt ?? "null"}).`
+      }]
+    };
+  }
+});
+
+// src/tools/index.ts
+var ALL_TOOLS = [
+  whoamiTool,
+  listInboxesTool,
+  createInboxTool,
+  getInboxTool,
+  deleteInboxTool,
+  listEmailsTool,
+  getEmailTool,
+  waitForEmailTool,
+  deleteEmailTool,
+  markEmailReadTool
+];
+function toolsForScopes(scopeList) {
+  const set = new Set(scopeList);
+  return ALL_TOOLS.filter((t) => t.requiredScopes.every((s) => set.has(s)));
+}
+
+// src/server.ts
+var SERVER_NAME = "instantinbox-mcp";
+var SERVER_VERSION = "0.1.0";
+function createMcpServer(getContext) {
+  const server = new Server(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    { capabilities: { tools: { listChanged: false } } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const ctx = await getContext();
+    const available = toolsForScopes(ctx.scopes.toArray());
+    return {
+      tools: available.map((tool) => ({
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        inputSchema: zodToJsonSchema(tool.inputSchema),
+        ...tool.annotations && { annotations: tool.annotations },
+        ...tool.meta && { _meta: tool.meta }
+      }))
+    };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: rawArgs } = request.params;
+    const tool = ALL_TOOLS.find((t) => t.name === name);
+    if (!tool) {
+      throw new McpError2(ErrorCode2.MethodNotFound, `Unknown tool: ${name}`);
+    }
+    const ctx = await getContext();
+    for (const scope of tool.requiredScopes) {
+      if (!ctx.scopes.has(scope)) {
+        throw new McpError2(
+          ErrorCode2.InvalidRequest,
+          `Token missing required scope '${scope}' for tool '${name}'`
+        );
+      }
+    }
+    const parseResult = tool.inputSchema.safeParse(rawArgs ?? {});
+    if (!parseResult.success) {
+      throw new McpError2(
+        ErrorCode2.InvalidParams,
+        `Invalid parameters for tool '${name}': ${parseResult.error.message}`
+      );
+    }
+    const result = await tool.handler(parseResult.data, {
+      apiClient: ctx.apiClient,
+      scopes: ctx.scopes
+    });
+    return {
+      content: result.content,
+      isError: result.isError ?? false,
+      ...result._meta && { _meta: result._meta }
+    };
+  });
+  return server;
+}
+
+// src/api-client.ts
+var ApiClient = class {
+  baseUrl;
+  headers;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+    this.headers = {
+      Authorization: `Bearer ${opts.token}`,
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+  }
+  /** Unwrap `{ success, data, meta }` → either `data` or `{ items, meta }`. */
+  unwrap(json) {
+    if (json && typeof json === "object" && "success" in json && "data" in json) {
+      const data = json.data;
+      if (Array.isArray(data)) {
+        return { items: data, meta: json.meta };
+      }
+      return data;
+    }
+    return json;
+  }
+  async request(method, path, body, query) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== void 0) url.searchParams.set(k, String(v));
+      }
+    }
+    let res;
+    try {
+      res = await fetch(url.toString(), {
+        method,
+        headers: this.headers,
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: AbortSignal.timeout(15e3)
+      });
+    } catch (err) {
+      throw new ApiError(`Network error: ${err.message}`);
+    }
+    if (method === "GET" && res.status === 404) return null;
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new ApiError(`${res.status} ${res.statusText}: ${text}`, res.status);
+    }
+    if (res.status === 204) return null;
+    return this.unwrap(await res.json());
+  }
+  // ── Auth / identity ─────────────────────────────────────────────────────
+  async whoami() {
+    return this.request("GET", "/auth/me");
+  }
+  // ── Inboxes ─────────────────────────────────────────────────────────────
+  async listInboxes(query = {}) {
+    const result = await this.request(
+      "GET",
+      "/inboxes",
+      void 0,
+      query
+    );
+    return result ?? { items: [], meta: { total: 0, page: 1, limit: 20, totalPages: 0 } };
+  }
+  async createInbox(body) {
+    const result = await this.request("POST", "/inboxes", body);
+    if (!result) throw new ApiError("createInbox returned no body");
+    return result;
+  }
+  async getInboxById(id) {
+    return this.request("GET", `/inboxes/${id}`);
+  }
+  /**
+   * The API has no GET /inboxes?address=... filter; emulate by listing and
+   * matching client-side. Good enough at our volumes.
+   */
+  async getInboxByAddress(address) {
+    const target = address.toLowerCase();
+    const { items } = await this.listInboxes({ limit: 100 });
+    return items.find((i) => i.address.toLowerCase() === target) ?? null;
+  }
+  async deleteInbox(id) {
+    await this.request("DELETE", `/inboxes/${id}`);
+  }
+  // ── Emails ──────────────────────────────────────────────────────────────
+  async listEmails(inboxId, query = {}) {
+    const result = await this.request(
+      "GET",
+      `/inboxes/${inboxId}/emails`,
+      void 0,
+      query
+    );
+    return result ?? { items: [], meta: { total: 0, page: 1, limit: 20, totalPages: 0 } };
+  }
+  async getEmail(id) {
+    return this.request("GET", `/emails/${id}`);
+  }
+  async deleteEmail(id) {
+    await this.request("DELETE", `/emails/${id}`);
+  }
+  async markRead(id) {
+    const r = await this.request("PATCH", `/emails/${id}/read`, {});
+    if (!r) throw new ApiError("markRead returned no body");
+    return r;
+  }
+  async markUnread(id) {
+    const r = await this.request("PATCH", `/emails/${id}/unread`, {});
+    if (!r) throw new ApiError("markUnread returned no body");
+    return r;
+  }
+};
+
+// src/auth/secret-key.ts
+function extractBearerToken(authHeader) {
+  if (!authHeader?.startsWith("Bearer ")) return null;
+  const token = authHeader.slice(7).trim();
+  return token || null;
+}
+async function validateSecretKey(token, apiBaseUrl) {
+  const url = `${apiBaseUrl}/auth/me`;
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(5e3)
+    });
+  } catch (err) {
+    throw new ApiError(`Cannot reach InstantInbox API: ${err.message}`);
+  }
+  if (!res.ok) {
+    throw new AuthError("invalid_token", `/auth/me returned ${res.status}`);
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch (err) {
+    throw new ApiError(`Malformed /auth/me response: ${err.message}`);
+  }
+  const data = body.data ?? body;
+  if (!data?.id) {
+    throw new AuthError("invalid_token", "/auth/me response missing user id");
+  }
+  void SCOPE;
+  return {
+    userId: data.id,
+    email: data.email,
+    scopes: new ScopeSet([...ALL_SCOPES]),
+    kind: token.startsWith("sk_") ? "secret-key" : "jwt"
+  };
+}
+
+export {
+  ALL_SCOPES,
+  ApiError,
+  AuthError,
+  ScopeSet,
+  createMcpServer,
+  ApiClient,
+  extractBearerToken,
+  validateSecretKey
+};
+//# sourceMappingURL=chunk-T7SFANFP.js.map