@formstr/mcp 0.6.0 → 0.7.1

package/AGENTS.md

@@ -0,0 +1,300 @@
+# Formstr MCP — Agent Guide
+
+You are connected to `@formstr/mcp`, a Model Context Protocol server that gives you tools to
+manage a person's **Formstr** account: forms, calendar, pages, drive, polls, and Mailstr email.
+Everything is stored on Nostr relays under the user's own identity. There is no backend you can
+query for help — **this document is the contract**.
+
+Read the [Golden rules](#golden-rules) and the [confirm gate](#the-confirm-gate) before your
+first write. Then jump to the module you need.
+
+---
+
+## Golden rules
+
+1. **Never invent an id.** Every tool that acts on existing data takes an id, pubkey, or
+   `coordinate` returned by a *list/get* tool. Chain reads before writes: list → pick → act.
+2. **A write tool needs `confirm: true`.** Without it the tool returns a "Confirmation
+   required…" message and does nothing. See [the confirm gate](#the-confirm-gate).
+3. **Creating is not gated, but it is real and public-permanent.** `create_*` tools are always
+   on and publish immediately on the user's identity. Don't create things the user didn't ask
+   for.
+4. **Addresses and coordinates are exact strings.** Coordinates look like `kind:pubkey:d`.
+   naddr/npub are bech32. Don't "fix" or reformat them.
+5. **Report outcomes honestly.** Tools return `ok`/`errorCode`. Relay publishes return per-relay
+   results; partial success is normal. Say what actually happened, don't claim success on a
+   failed call.
+6. **The user's key never reaches you.** No tool returns secrets. If you ever see key material
+   in output, stop and tell the user — it's a bug.
+7. **Prefer the smallest action.** Use list/get to confirm before update/delete. Never delete or
+   overwrite without the user's explicit go-ahead in the conversation.
+
+---
+
+## The confirm gate
+
+Roughly half the tools are marked **gated** (destructive, outward, or identity-changing). Each
+is registered *and* requires `confirm: true` on the call.
+
+### How to use it safely
+
+The first call **without** `confirm` is a free preview: it returns exactly what would happen
+and executes nothing.
+
+```
+send_mail({ to: "alice@example.com", subject: "Hi", text: "…" })
+→ { ok: false, text: "Confirmation required for \"send_mail\". This action is irreversible
+   and acts on your Nostr identity: sends email to \"alice@example.com\". Re-call with
+   \"confirm\": true to proceed." }
+```
+
+The correct pattern is:
+
+1. Call the gated tool **once without `confirm`** (or just describe the effect to the user).
+2. Show the user what will happen and get their agreement **in the conversation**.
+3. Call again with `confirm: true`.
+
+Do **not** silently pass `confirm: true` on the first try for anything destructive. For
+outward actions (send mail, share) or deletions, always surface the effect to the user first.
+
+### What is gated
+
+Gated (`confirm: true` required) — 27 of 60 tools:
+`update_form`, `share_form`, `delete_form`, `submit_form_response`,
+`delete_calendar_event`, `update_calendar_event`, `attach_form_to_event`, `update_calendar`,
+`delete_calendar`, `add_event_to_calendar`, `remove_event_from_calendar`, `approve_booking`,
+`decline_booking`, `rsvp_event`, `delete_page`, `update_page`, `share_page`, `add_page_comment`,
+`delete_poll`, `clear_my_vote`, `submit_poll_response`, `delete_file`, `rename_file`, `move_file`,
+`send_mail`, `claim_mailbox`, `publish_mail_setup`.
+
+The other 33 are always on. **"Always on" still means it publishes to the user's identity** —
+`create_*`, `save_private_note`, `import_form_from_naddr`, and `submit_*` are real writes even
+though they don't need `confirm`.
+
+> If a gated tool is **absent** from your tool list entirely, the server was started without
+> `--allow-writes`. Tell the user; you cannot enable it from here.
+
+---
+
+## Addresses, ids and coordinates
+
+| Thing | Format | Example | Produced by |
+| --- | --- | --- | --- |
+| Form | `formId` + author `pubkey` | `a1b2…` / `c3d4…` | `list_forms`, `create_form` |
+| Form reference | `naddr1…`, `pubkey:formId`, or `kind:pubkey:formId` | — | `create_form` (`naddr`) |
+| Calendar event / calendar | `coordinate` = `kind:pubkey:d` | `31923:<pk>:my-event` | `list_calendar_events`, `create_calendar_event` |
+| Calendar list | its `id` (d-tag) | `work` | `list_calendars`, `create_calendar` |
+| Page / doc | `docId` (d-tag) + author `pubkey`, or an `address` | — | `list_pages`, `create_page` |
+| Poll | `pollEventId` | `ab12…` | `list_polls`, `create_poll` |
+| Drive file | `name` (+ optional `folder`) | `report.pdf` | `browse_files` |
+| Mail message | `mailId` (the wrap id) | `ef56…` | `list_mail` |
+
+**Private/encrypted things need a view key.** Forms, pages, and private calendar events can be
+encrypted; pass `viewKey` (an `nsec`) where a tool offers it or you will get ciphertext or an
+error. `list_shared_pages` returns the `viewKey` for documents shared with the user.
+`get_calendar_event` reports `registrationFormHasViewKey` so you can check an attached form is
+readable.
+
+---
+
+## Tool catalog
+
+### Forms (9)
+
+| Tool | Required args | Notes |
+| --- | --- | --- |
+| `list_forms` | — | The user's forms index. Start here. |
+| `get_form` | `pubkey`, `formId` | Pass `viewKey` for encrypted forms. |
+| `fetch_form_responses` | `formAuthorPubkey`, `formId` | Submissions with responder + answers. |
+| `create_form` | `name`, `fields` | Always on. Returns `formId`, `pubkey`, `naddr`. |
+| `import_form_from_naddr` | `ref` | `naddr1…`, `pubkey:formId`, or `kind:pubkey:formId`. |
+| `update_form` ⚠ | `formId`, `formPubkey` | Republish name/fields/description. Gated. |
+| `share_form` ⚠ | `formId`, `formPubkey`, `recipients` | Gift-wraps the **view key**; `editors` also get edit access. Gated. |
+| `delete_form` ⚠ | `formId`, `formPubkey` | NIP-09 deletion. Gated. |
+| `submit_form_response` ⚠ | `formAuthorPubkey`, `formId`, `answers` | Submits on the user's identity. Gated. |
+
+`create_form` fields: each is `{ type, label, required?, options?, validation?, … }`. Supported
+types: `short`, `paragraph`, `choice`, `dropdown`, `number`, `date`, `time`, `grid`, `file`,
+`signature`, `section`. Optional: `description`, `publicForm`, `encrypted`,
+`allowedResponders`, `collaborators`, `notifyNpubs`, `titleImageUrl`, `coverImageUrl`,
+`thankYouText`.
+
+> **Encrypted form?** After `create_form` with `encrypted: true`, share it with
+> `share_form` so the people you want can read it — otherwise only the creator can.
+
+### Calendar (19)
+
+| Tool | Required args | Notes |
+| --- | --- | --- |
+| `list_calendar_events` | — | Optional ISO-8601 `since`/`until`. |
+| `get_calendar_event` | `coordinate` | |
+| `create_calendar_event` | `title`, `start` | **Defaults to PRIVATE.** See note below. |
+| `list_calendars` | — | |
+| `create_calendar` | `title` | A calendar *list* (like a folder). |
+| `fetch_event_rsvps` | `coordinate` | |
+| `list_invitations` | — | NIP-59 invitations received. |
+| `list_scheduling_pages` | — | Booking links, each with a shareable URL. |
+| `list_booking_requests` | — | Incoming appointment requests. |
+| `approve_booking` ⚠ | `requestId`, `calendarId` | Creates the appointment, notifies booker. Gated. |
+| `decline_booking` ⚠ | `requestId` | Gated. |
+| `delete_calendar_event` ⚠ | `eventId` | Gated. |
+| `rsvp_event` ⚠ | `eventCoordinate`, `status` | Gated. Optional suggested time/comment. |
+| `update_calendar_event` ⚠ | `coordinate` | Only send changed fields. Gated. |
+| `attach_form_to_event` ⚠ | `coordinate`, `formRef` | Gated. Pass `formViewKey` for encrypted forms. |
+| `update_calendar` ⚠ | `id` | Gated. |
+| `delete_calendar` ⚠ | `coordinate` | Gated. |
+| `add_event_to_calendar` ⚠ | `calendarId`, `coordinate` | Gated. |
+| `remove_event_from_calendar` ⚠ | `calendarId`, `coordinate` | Gated. |
+
+> **`create_calendar_event` workflow (important).** Events are linked into a calendar list;
+> that link is the only way they render on calendar.formstr.app. If you omit `calendarId` and
+> the user already has calendars, the tool returns the list and a `CALENDAR_REQUIRED` code —
+> **ask the user which calendar**, then re-run with `calendarId`. `isPrivate:false` makes a
+> public unencrypted event, which does **not** sync to calendar.formstr.app. `participants`
+> (npub/hex) receive NIP-59 invitations. To attach a registration form, pass
+> `registrationFormRef` and, for encrypted forms, `registrationFormViewKey`.
+
+### Pages (12)
+
+| Tool | Required args | Notes |
+| --- | --- | --- |
+| `list_pages` | — | |
+| `get_page` | `pubkey`, `docId` | Pass `viewKey` if encrypted. |
+| `list_shared_pages` | — | Docs shared with the user (carries `viewKey`). |
+| `get_page_tags` | `address` | Private labels. |
+| `list_page_comments` | `address`, `viewKey` | Inline comments/suggestions (kind 1494). |
+| `create_page` | `title`, `content` | Markdown, encrypted. Always on. |
+| `save_private_note` | `title`, `content` | Quick encrypted note. Always on. |
+| `set_page_tags` | `address`, `tags` | Always on. |
+| `update_page` ⚠ | `docId`, `content` | Replaces content. Gated. |
+| `delete_page` ⚠ | `address` | NIP-09. Gated. |
+| `share_page` ⚠ | `address`, `content` | Re-encrypts under a view key; `canEdit` for edit links. Gated. |
+| `add_page_comment` ⚠ | `address`, `eventId`, `viewKey`, `content` | Gated. |
+
+### Polls (8)
+
+| Tool | Required args | Notes |
+| --- | --- | --- |
+| `list_polls` | — | User's own polls. |
+| `list_recent_polls` | — | Public polls to discover. Optional `limit`. |
+| `get_poll` | `pollEventId` | Includes option ids. |
+| `fetch_poll_results` | `pollEventId` | |
+| `create_poll` | `question`, `options` | Always on. |
+| `submit_poll_response` ⚠ | `pollEventId`, `optionIds` | Gated. |
+| `delete_poll` ⚠ | `pollEventId` | Gated. |
+| `clear_my_vote` ⚠ | `pollEventId` | Retract own votes. Gated. |
+
+### Drive (5)
+
+| Tool | Required args | Notes |
+| --- | --- | --- |
+| `browse_files` | — | Encrypted drive; optional `folder`. |
+| `get_file_info` | `name` | Optional `folder`. |
+| `delete_file` ⚠ | `name` | **Soft delete** — blob stays on Blossom, index forgets it. Gated. |
+| `rename_file` ⚠ | `name`, `newName` | Gated. |
+| `move_file` ⚠ | `name`, `newFolder` | Gated. |
+
+> There is **no upload/create-file tool** — Blossom blobs can't stream over the MCP text
+> channel. Upload happens in the web app; the MCP browses and manages metadata only.
+
+### Mail — Mailstr (7)
+
+| Tool | Required args | Notes |
+| --- | --- | --- |
+| `list_mail` | — | Inbox, newest first: `id`, sender, subject, date. |
+| `read_mail` | `mailId` | Full body of one message. |
+| `who_is_my_mail_address` | — | Signed-in identity, default `From:`, and aliases. |
+| `list_mail_aliases` | — | Every address the account can send as, and the default. |
+| `send_mail` ⚠ | `to` | `to` = npub/hex **or** external email. Gated. |
+| `claim_mailbox` ⚠ | `name` | Returns a **bolt11 invoice**; the server cannot pay it. Gated. |
+| `publish_mail_setup` ⚠ | `name` | Profile (nip05) + kind-10050 delivery relays. Gated. |
+
+**Aliases.** One identity owns many NIP-05 addresses (`you@mailstr.app`, or
+`you@yourdomain.com` on a workspace), all sharing one inbox. Pass `from` to `send_mail` to
+choose which alias appears in the `From:`; call `list_mail_aliases` first to see the options. A
+`from` the account doesn't own is rejected with the valid list. `send_mail` needs `text` or
+`raw`. For external email, the `From:` must be a registered alias (not the bare npub) or the
+bridge bounces it.
+
+> **Claiming is two-step and human-driven.** `claim_mailbox` returns a bolt11 invoice. The
+> user pays it in their own wallet. Then the address starts working once NIP-05 propagates.
+> You **cannot** complete payment from here.
+
+---
+
+## Recipes
+
+### "Make me a survey and share it"
+
+```
+create_form { name: "Team offsite", fields: [
+  { type: "short", label: "Your name", required: true },
+  { type: "choice", label: "Preferred month", options: ["May","June","July"] },
+  { type: "paragraph", label: "Dietary needs" }
+], encrypted: true }
+→ formId = F, pubkey = P
+
+# encrypted forms must be shared to be readable:
+share_form { formId: F, formPubkey: P, recipients: ["npub1…"], confirm: true }
+→ tell the user it's shared and irreversible-ish
+```
+
+### "Schedule a meeting with X"
+
+```
+list_calendars          # does the user have a calendar list?
+create_calendar_event { title: "Sync", start: "2026-10-20T15:00:00Z",
+                        end: "2026-10-20T15:30:00Z", participants: ["npub1…"] }
+# if it returns CALENDAR_REQUIRED → ask the user which calendar, then:
+create_calendar_event { …, calendarId: "<chosen>" }
+```
+
+### "Send an email to alice@example.com as me"
+
+```
+list_mail_aliases        # see what From: addresses are available
+send_mail { to: "alice@example.com", subject: "Hi", text: "…",
+            from: "me@mailstr.app" }          # preview (no confirm)
+# show the user, get agreement, then:
+send_mail { to: "alice@example.com", subject: "Hi", text: "…",
+            from: "me@mailstr.app", confirm: true }
+```
+
+### "What did I miss in my inbox?"
+
+```
+list_mail                # newest first
+read_mail { mailId: "<id from list>" }
+```
+
+---
+
+## Errors and edge cases
+
+- **`"Confirmation required…"`** — expected. Re-call with `confirm: true` after the user agrees.
+- **`NOT_FOUND`** — the id/name doesn't exist. Re-run the relevant `list_*`; don't retry blindly.
+- **`CALENDAR_REQUIRED`** — `create_calendar_event` needs a `calendarId`. The message lists the
+  available calendars; ask the user, then re-run.
+- **`BAD_INPUT`** — a parameter is missing, unknown, or invalid (this includes a `from` address
+  the account doesn't own). The message names the valid values; fix and retry.
+- **`CLAIM_FAILED`** — `claim_mailbox` couldn't create an invoice (name taken, or the API
+  rejected the request). Read the message, don't retry blindly.
+- **Unknown parameter error** — tool schemas are **strict**; an unrecognized key is rejected
+  with `BAD_INPUT` rather than ignored. Use exactly the parameter names in this guide. (This is
+  deliberate: before, a typo'd parameter was silently dropped and you'd think a write happened
+  when it didn't.)
+- **Partial relay success** — publish tools return per-relay results. Report how many relays
+  accepted; a few failing is normal and not an error.
+- **Gated tools missing** — the server runs without `--allow-writes`. You can't change it; tell
+  the user.
+- **Encrypted data looks like ciphertext** — you need the `viewKey`/`nsec`. Ask the user or list
+  shared items.
+
+---
+
+## For the operator (setup, not for the agent)
+
+See [`README.md`](./README.md) for installation, `formstr-mcp login`, host configuration
+(`claude_desktop_config.json`, Cursor, Goose/Ollama), the passphrase env var, and the full
+environment-variable and CLI-flag reference. In short: `npx -y @formstr/mcp`; add
+`"--allow-writes"` to enable gated tools.

package/README.md

@@ -12,6 +12,10 @@ the same login engine the Formstr web app uses. Local keys are stored **NIP-49 e
 (`ncryptsec`)** inside an OS-keychain (or encrypted-file) keystore; a raw nsec is never
 persisted. Remote keys stay in your NIP-46 signer.
 
+> **Driving this from an AI agent?** Read [`AGENTS.md`](./AGENTS.md) — a task-oriented guide to
+> every tool, the `confirm` gate, id/coordinate formats, and worked recipes. This README is the
+> operator's setup guide.
+
 ## Quick start
 
 ```bash
@@ -236,17 +240,26 @@ Email through mailstr, using the same identity you logged in with (the account t
 
 - `list_mail` — your inbox: sender, subject, date per message (kind-1059 gift-wrapped mail).
 - `read_mail` — the full body of one message by its id.
-- `who_is_my_mail_address` — the account's mail address (NIP-05) and pubkey.
+- `list_mail_aliases` — every address (NIP-05 alias) this account can send as, and the default.
+- `who_is_my_mail_address` — the signed-in identity, its default `From:`, and its aliases.
 
 **Gated (require `--allow-writes` + `confirm: true`)**
 
 - `send_mail` — send email to an npub/hex key, or an external address via the domain's SMTP bridge.
+  Pass `from` to choose which alias to send as (one of your own addresses); omit it to send from
+  an owned alias, or the npub mailbox when you have none. A `from` you do not own is rejected with
+  the list of valid senders.
 - `claim_mailbox` — start claiming `you@mailstr.app`. Returns a **Lightning invoice to pay in
   your own wallet** — the server holds no wallet, so it cannot pay it. Mail works once NIP-05
   propagates.
 - `publish_mail_setup` — publish your profile (with the NIP-05 address) and the kind-10050
   delivery-relay list senders read.
 
+**Aliases.** A mail identity is one Nostr key; an *alias* is a NIP-05 name bound to that key.
+All of an account's aliases share one key and one inbox — mail is encrypted to the key, so which
+alias a message was addressed to is only a header. `send_mail`'s `from` picks which alias appears
+in the `From:`; `list_mail_aliases` shows the choices.
+
 ## Safety model
 
 Destructive / outward tools are **not registered** unless `--allow-writes` (or

package/dist/index.js

@@ -33354,6 +33354,64 @@ var defaultFetchJson = async (url, init) => {
     clearTimeout(timer);
   }
 };
+var OWNED_ADDRESSES_PATH = "/api/nip-05/get-nip05";
+function normalizeOwnedAddresses(body, domain = DEFAULT_MAIL_DOMAIN) {
+  const qualify = (addr, entryDomain) => {
+    if (addr.includes("@")) return addr;
+    if (typeof entryDomain === "string" && entryDomain.trim()) return `${addr}@${entryDomain}`;
+    return `${addr}@${domain}`;
+  };
+  if (typeof body === "string") return [qualify(body)];
+  let raw = [];
+  if (Array.isArray(body)) {
+    raw = body.flatMap((entry) => {
+      if (typeof entry === "string") return [{ value: entry }];
+      if (entry && typeof entry === "object") {
+        const obj = entry;
+        if (typeof obj.nip05 === "string") return [{ value: obj.nip05, domain: obj.domain }];
+        if (typeof obj.name === "string") return [{ value: obj.name, domain: obj.domain }];
+      }
+      return [];
+    });
+  } else if (body && typeof body === "object") {
+    const obj = body;
+    if (typeof obj.nip05 === "string") {
+      raw = [{ value: obj.nip05, domain: obj.domain }];
+    } else if (Array.isArray(obj.nip05Addresses)) {
+      raw = obj.nip05Addresses.filter((v) => typeof v === "string").map((value) => ({ value }));
+    }
+  }
+  return raw.map(({ value, domain: d }) => qualify(value, d));
+}
+async function defaultFetch(url, init) {
+  const res = await fetch(url, init);
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+  }
+  return { ok: res.ok, status: res.status, body };
+}
+async function fetchAddresses(url, header, opts) {
+  const fetchJson = opts.fetchJson ?? defaultFetch;
+  const res = await fetchJson(url, { method: "GET", headers: { Authorization: header } });
+  if (res.status === 404 || res.status === 401) return [];
+  if (!res.ok) throw new Error(`Address lookup failed (${res.status})`);
+  return normalizeOwnedAddresses(res.body, opts.domain ?? DEFAULT_MAIL_DOMAIN);
+}
+async function fetchOwnedAddressesWith(signer, opts = {}) {
+  const api = (opts.api ?? DEFAULT_CLAIM_API).replace(/\/+$/, "");
+  const url = `${api}${OWNED_ADDRESSES_PATH}`;
+  return fetchAddresses(url, await signNip98With(signer, url, "GET"), opts);
+}
+function defaultFromAddress(pubkey, ownedAddresses) {
+  const isNpubAlias = (a) => {
+    const at = a.indexOf("@");
+    return at > 0 && a.slice(0, at).toLowerCase().startsWith("npub1");
+  };
+  const alias = ownedAddresses.find((a) => !isNpubAlias(a));
+  return alias ?? ownedAddresses[0] ?? `${nip19_exports.npubEncode(pubkey)}@${DEFAULT_MAIL_DOMAIN}`;
+}
 function verifySealAndRumor(wrap, seal, rumor, opts = {}) {
   const maxAge = opts.maxAgeSeconds ?? MAX_RUMOR_AGE_SECONDS;
   const now3 = opts.now ?? Math.floor(Date.now() / 1e3);
@@ -33719,9 +33777,11 @@ async function publishEverywhere(pool, relays, event) {
   };
 }
 
-// ../agent/dist/chunk-ZPXEAOMQ.js
+// ../agent/dist/chunk-5L26ARX5.js
 var service_exports2 = {};
 __export3(service_exports2, {
+  defaultSenderAddress: () => defaultSenderAddress,
+  listAliases: () => listAliases,
   mailIdentity: () => mailIdentity,
   publishMailSetup: () => publishMailSetup,
   readMail: () => readMail,
@@ -33740,6 +33800,15 @@ async function mailIdentity() {
   const profile = await fetchProfile(pubkey).catch(() => null);
   return { pubkey, npub: nip19_exports.npubEncode(pubkey), nip05: profile?.nip05 ?? null };
 }
+async function listAliases() {
+  const signer = await mailSigner();
+  return fetchOwnedAddressesWith(signer).catch(() => []);
+}
+async function defaultSenderAddress() {
+  const signer = await signerManager.getSigner();
+  const pubkey = await signer.getPublicKey();
+  return defaultFromAddress(pubkey, await listAliases());
+}
 async function readMail(opts = {}) {
   const signer = await mailSigner();
   const { mail, failures } = await readInboxWith(signer, {
@@ -33750,12 +33819,13 @@ async function readMail(opts = {}) {
 }
 async function sendMail(params) {
   const signer = await mailSigner();
+  const from = params.from ?? await defaultSenderAddress();
   return sendMailWith(signer, {
     to: params.to,
     ...params.subject !== void 0 ? { subject: params.subject } : {},
     ...params.text !== void 0 ? { text: params.text } : {},
     ...params.raw !== void 0 ? { raw: params.raw } : {},
-    ...params.from !== void 0 ? { from: params.from } : {},
+    from,
     relays: relayManager.getRelaysForModule("mail")
   });
 }
@@ -44700,7 +44770,7 @@ var coerce = {
 };
 var NEVER = INVALID;
 
-// ../agent/dist/chunk-QX4DSGPL.js
+// ../agent/dist/chunk-JORUNTXB.js
 function ok(text, data) {
   return data !== void 0 ? { ok: true, text, data } : { ok: true, text };
 }
@@ -45956,14 +46026,31 @@ function buildMailTools() {
   server.registerTool(
     "who_is_my_mail_address",
     {
-      description: "Show the mail address (NIP-05) and pubkey of the account currently signed in to this server.",
+      description: "Show the account signed in to this server, its default mail address, and every alias it can send as.",
       inputSchema: {}
     },
     async () => {
       const who = await service_exports2.mailIdentity();
+      const aliases = await service_exports2.listAliases();
+      const defaultFrom = await service_exports2.defaultSenderAddress();
       return ok(
-        who.nip05 ? `Your mail address is ${who.nip05}.` : `Signed in as ${who.npub}. No mailstr address is bound to this key yet \u2014 claim one with claim_mailbox.`,
-        who
+        `Signed in as ${who.npub}. Sending as ${defaultFrom}.` + (aliases.length ? ` Aliases: ${aliases.join(", ")}.` : " No registered alias yet \u2014 claim one with claim_mailbox."),
+        { ...who, aliases, defaultFrom }
+      );
+    }
+  );
+  server.registerTool(
+    "list_mail_aliases",
+    {
+      description: "List every mail address (NIP-05 alias) this account can send as, and which is the default. All aliases share one inbox.",
+      inputSchema: {}
+    },
+    async () => {
+      const aliases = await service_exports2.listAliases();
+      const defaultFrom = await service_exports2.defaultSenderAddress();
+      return ok(
+        aliases.length ? `You can send as ${aliases.length} address(es); default is ${defaultFrom}.` : `No aliases yet \u2014 sending uses ${defaultFrom}. Claim an address with claim_mailbox.`,
+        { aliases, defaultFrom }
       );
     }
   );
@@ -45987,6 +46074,18 @@ function buildMailTools() {
       if (args.text === void 0 && args.raw === void 0) {
         return fail("send_mail needs either `text` or `raw`.", "BAD_INPUT");
       }
+      if (args.from !== void 0) {
+        const identity = await service_exports2.mailIdentity();
+        const aliases = await service_exports2.listAliases();
+        const npubAddress = `${identity.npub}@${DEFAULT_MAIL_DOMAIN}`;
+        const validSenders = [npubAddress, ...aliases];
+        if (!validSenders.map((a) => a.toLowerCase()).includes(args.from.toLowerCase())) {
+          return fail(
+            `You cannot send as "${args.from}". Use one of: ${validSenders.join(", ")}.`,
+            "BAD_SENDER"
+          );
+        }
+      }
       try {
         const result = await service_exports2.sendMail({
           to: args.to,