@formstr/mcp 0.7.1 → 0.8.0

package/AGENTS.md

@@ -10,6 +10,52 @@ first write. Then jump to the module you need.
 
 ---
 
+## Before you can do anything
+
+You almost certainly cannot change this yourself — it is a one-time, human, out-of-band step.
+But you should know what it is so you can tell the user exactly what's wrong if a tool is
+missing or a command fails.
+
+**1. A human signs in once** (interactive terminal; never in the chat):
+
+```bash
+npx -y @formstr/mcp login
+```
+
+They pick **Bunker URI (NIP-46)** for the best setup — the private key stays in their signer
+app (Amber, nsec.app), only a session is stored, and no passphrase is ever needed in a config
+file. The alternative, an `ncryptsec` key, unlocks with a passphrase supplied via the
+`FORMSTR_MCP_NCRYPTSEC_PASSPHRASE` env var in the host config. Either way **the key never
+reaches you**.
+
+**2. The host starts the server.** The user adds an entry to their MCP host config
+(`claude_desktop_config.json`, Cursor's `~/.cursor/mcp.json`, Goose, …):
+
+```json
+{
+  "mcpServers": {
+    "formstr": {
+      "command": "npx",
+      "args": ["-y", "@formstr/mcp", "--allow-writes"]
+    }
+  }
+}
+```
+
+- **`--allow-writes` is what registers the gated tools.** Without it, tools like `send_mail`,
+  `delete_form`, `update_page`, `share_form` are **absent from your tool list entirely** — not
+  disabled, just not there. If a write tool the user expects is missing, this is why: tell them
+  to add the flag and restart the host.
+- The flag does **not** make anything automatic — every gated tool still requires you to pass
+  `confirm: true`, and you should only do that after the user agrees (see
+  [the confirm gate](#the-confirm-gate)).
+- Add `"--relays", "wss://a,wss://b"` to override the relay set if the user asks.
+
+That's the whole setup. If the tools are present and `list_*` calls work, you're good — the
+sections below are everything else.
+
+---
+
 ## Golden rules
 
 1. **Never invent an id.** Every tool that acts on existing data takes an id, pubkey, or
@@ -201,8 +247,8 @@ types: `short`, `paragraph`, `choice`, `dropdown`, `number`, `date`, `time`, `gr
 
 | Tool | Required args | Notes |
 | --- | --- | --- |
-| `list_mail` | — | Inbox, newest first: `id`, sender, subject, date. |
-| `read_mail` | `mailId` | Full body of one message. |
+| `list_mail` | — | A page of the inbox, newest first. Page with `until`. |
+| `read_mail` | `mailId` | Full body of one message (fetched by id). |
 | `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. |
@@ -216,6 +262,12 @@ choose which alias appears in the `From:`; call `list_mail_aliases` first to see
 `raw`. For external email, the `From:` must be a registered alias (not the bare npub) or the
 bridge bounces it.
 
+**Paging a large inbox.** `list_mail` returns a bounded **page** (default 50, newest first) —
+it does not scan the whole mailbox. When the page is full the result includes `oldestReceivedAt`
+and `hasMore: true`; to read further back, call again with `until` set to that value. `since`
+and `until` are unix seconds. If you only need one message you already have the id for, call
+`read_mail` — it fetches that exact wrap and never depends on the page window.
+
 > **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.
@@ -292,9 +344,18 @@ read_mail { mailId: "<id from list>" }
 
 ---
 
-## For the operator (setup, not for the agent)
+## Pointing other agents here
+
+This guide is the single entry point. Canonical source is the ngit repository; GitHub is a
+read-only mirror.
+
+- **Agent-readable (raw Markdown — what you want to feed a model):**
+  `https://raw.githubusercontent.com/formstr-hq/common-packages/main/packages/mcp/AGENTS.md`
+- **Human-readable (rendered):**
+  `https://github.com/formstr-hq/common-packages/blob/main/packages/mcp/AGENTS.md`
+- **Shipped in the package too:** `AGENTS.md` is included in the `@formstr/mcp` npm tarball, so
+  `node_modules/@formstr/mcp/AGENTS.md` exists after any install.
+
+For deeper operator detail — keystore internals, the full environment-variable and CLI-flag
+reference, Ollama/Goose setup, troubleshooting — see [`README.md`](./README.md).
 
-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

@@ -13,8 +13,10 @@ the same login engine the Formstr web app uses. Local keys are stored **NIP-49 e
 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.
+> every tool, the `confirm` gate, id/coordinate formats, and worked recipes. It is
+> self-contained (setup included), so you can point a model straight at the raw file:
+> `https://raw.githubusercontent.com/formstr-hq/common-packages/main/packages/mcp/AGENTS.md`.
+> This README is the operator's setup guide.
 
 ## Quick start
 

package/dist/index.js

@@ -33501,7 +33501,14 @@ async function collectInbox(recipient, opts, unwrap) {
   const filter = {
     kinds: [KIND_GIFTWRAP],
     "#p": [recipient],
-    limit: opts.limit ?? 100
+    limit: opts.limit ?? 100,
+    // Time-window paging. Both optional: absent `until` means "newest", absent
+    // `since` means "all the way back". Together they turn a potentially huge
+    // inbox scan into bounded pages (oldest receivedAt → next `until`).
+    ...opts.since !== void 0 ? { since: opts.since } : {},
+    ...opts.until !== void 0 ? { until: opts.until } : {},
+    // Exact lookup by id — no time window, for reading one known message.
+    ...opts.ids !== void 0 ? { ids: opts.ids } : {}
   };
   const wraps = opts.queryWraps ? await opts.queryWraps(filter) : await new SimplePool().querySync(relays, filter);
   const seen = /* @__PURE__ */ new Map();
@@ -33544,7 +33551,8 @@ async function readInboxWith(signer, opts = {}) {
     recipient,
     opts,
     (wrap) => unwrapMailWith(wrap, signer, {
-      maxAgeSeconds: opts.maxAgeSeconds,
+      // See readInbox: the inbox has no staleness bound by default.
+      maxAgeSeconds: opts.maxAgeSeconds ?? Infinity,
       acceptKinds: opts.acceptKinds,
       now: opts.now
     })
@@ -33777,7 +33785,7 @@ async function publishEverywhere(pool, relays, event) {
   };
 }
 
-// ../agent/dist/chunk-5L26ARX5.js
+// ../agent/dist/chunk-CCSELOJL.js
 var service_exports2 = {};
 __export3(service_exports2, {
   defaultSenderAddress: () => defaultSenderAddress,
@@ -33785,6 +33793,7 @@ __export3(service_exports2, {
   mailIdentity: () => mailIdentity,
   publishMailSetup: () => publishMailSetup,
   readMail: () => readMail,
+  readMailById: () => readMailById,
   requestMailbox: () => requestMailbox,
   sendMail: () => sendMail
 });
@@ -33811,11 +33820,27 @@ async function defaultSenderAddress() {
 }
 async function readMail(opts = {}) {
   const signer = await mailSigner();
+  const limit = opts.limit ?? 50;
   const { mail, failures } = await readInboxWith(signer, {
     relays: inboxRelays(),
-    ...opts.limit !== void 0 ? { limit: opts.limit } : {}
+    limit,
+    ...opts.since !== void 0 ? { since: opts.since } : {},
+    ...opts.until !== void 0 ? { until: opts.until } : {}
   });
-  return { mail, failures };
+  mail.sort((a, b) => b.receivedAt - a.receivedAt);
+  return {
+    mail,
+    failures,
+    oldestReceivedAt: mail.length ? mail[mail.length - 1].receivedAt : void 0,
+    // A full page means there are probably older messages to page to. We cannot
+    // know for certain without a second query; this is a cheap, honest hint.
+    hasMore: mail.length >= limit
+  };
+}
+async function readMailById(mailId) {
+  const signer = await mailSigner();
+  const { mail } = await readInboxWith(signer, { relays: inboxRelays(), ids: [mailId] });
+  return mail[0] ?? null;
 }
 async function sendMail(params) {
   const signer = await mailSigner();
@@ -44770,7 +44795,7 @@ var coerce = {
 };
 var NEVER = INVALID;
 
-// ../agent/dist/chunk-JORUNTXB.js
+// ../agent/dist/chunk-XHSE23RE.js
 function ok(text, data) {
   return data !== void 0 ? { ok: true, text, data } : { ok: true, text };
 }
@@ -45967,25 +45992,35 @@ function buildMailTools() {
   server.registerTool(
     "list_mail",
     {
-      description: "List the mail in your mailstr inbox (kind-1059 gift-wrapped email). Returns each message's id, sender, subject and date, newest first.",
-      inputSchema: { limit: external_exports.number().optional() }
+      description: "List a page of the mailstr inbox (kind-1059 gift-wrapped email), newest first. Returns each message's id, sender, subject and date. Pages are bounded (default 50); when the page is full the result carries `oldestReceivedAt` \u2014 pass it back as `until` to page further back. `since`/`until` are unix seconds; omitted `until` means newest.",
+      inputSchema: {
+        limit: external_exports.number().optional(),
+        since: external_exports.number().optional(),
+        until: external_exports.number().optional()
+      }
     },
-    async ({ limit }) => {
-      const { mail: messages, failures } = await service_exports2.readMail(
-        limit !== void 0 ? { limit } : {}
-      );
-      messages.sort((a, b) => b.receivedAt - a.receivedAt);
+    async ({ limit, since, until }) => {
+      const { mail: messages, failures, oldestReceivedAt, hasMore } = await service_exports2.readMail({
+        ...limit !== void 0 ? { limit } : {},
+        ...since !== void 0 ? { since } : {},
+        ...until !== void 0 ? { until } : {}
+      });
       const rows = messages.map((m) => ({
         id: m.wrapId,
         from: m.from,
         subject: m.subject,
         date: new Date(m.receivedAt * 1e3).toISOString()
       }));
-      let text = `${messages.length} message(s) in your inbox.`;
+      let text = `${messages.length} message(s) in this page of your inbox.`;
+      if (hasMore && oldestReceivedAt !== void 0) {
+        text += ` Older mail may exist \u2014 call list_mail again with until: ${oldestReceivedAt}.`;
+      }
       if (failures.length > 0) text += ` ${failures.length} wrap(s) could not be decoded.`;
       return ok(text, {
         mail: rows,
         count: messages.length,
+        oldestReceivedAt,
+        hasMore,
         failures
       });
     }
@@ -45997,8 +46032,7 @@ function buildMailTools() {
       inputSchema: { mailId: external_exports.string() }
     },
     async ({ mailId }) => {
-      const { mail: messages } = await service_exports2.readMail();
-      const msg = messages.find((m) => m.wrapId === mailId);
+      const msg = await service_exports2.readMailById(mailId);
       if (!msg) {
         return fail(
           `No message with id "${mailId}". Use list_mail to see the ids in your inbox.`,