@formstr/mcp 0.2.0 → 0.3.1

package/README.md

@@ -21,7 +21,9 @@ npx -y @formstr/mcp login
 ```
 
 Subcommands: `formstr-mcp login` · `formstr-mcp whoami` · `formstr-mcp accounts` ·
-`formstr-mcp logout` · `formstr-mcp` (run the stdio server, the default).
+`formstr-mcp switch <npub>` · `formstr-mcp logout` · `formstr-mcp help` ·
+`formstr-mcp` (run the stdio server, the default). Run `formstr-mcp help` (or `-h`) for
+the full usage.
 
 ## Sign-in
 
@@ -39,7 +41,11 @@ offers four methods:
 Linux Secret Service via `@napi-rs/keyring`). On hosts without a keychain (e.g. headless
 Linux), set `FORMSTR_MCP_PASSPHRASE` to use an AES-256-GCM encrypted file at
 `~/.config/formstr-mcp/keystore.enc` (mode `0600`). Multiple identities are supported
-(`formstr-mcp accounts` lists them); select one at boot with `--account <pubkey>`.
+(`formstr-mcp accounts` lists them). Change the persisted active account with
+`formstr-mcp switch <npub>`, or pick one for a single boot with `--account <npub>`; the
+server follows the active account when neither is given, so switching accounts just works.
+Both `switch` and `--account` accept either the `npub` (as shown by `accounts`) or the hex
+pubkey.
 
 **Defense in depth:** even on the encrypted-file fallback the stored key is _also_ NIP-49
 encrypted, so recovering it needs **both** the keystore **and** the unlock passphrase.
@@ -71,8 +77,13 @@ Run `formstr-mcp login` once interactively to populate the keystore, then run th
 unattended. At boot the active account is unlocked headlessly:
 
 - **ncryptsec accounts** decrypt using `FORMSTR_MCP_NCRYPTSEC_PASSPHRASE` (the passphrase
-  you set during `login`). Required for the `run` command when the active account is local.
-- **NIP-46 accounts** reconnect from their stored session — no passphrase needed.
+  you set during `login`). On an **interactive terminal** the server instead **prompts**
+  for it (and re-prompts up to 3× on a typo) — so the env var is only _required_ when an
+  MCP host spawns the server, since then stdin is the JSON-RPC channel and there's nobody
+  to prompt. Each account has its own passphrase.
+- **NIP-46 accounts** reconnect from their stored session — no passphrase needed. This is
+  the simplest setup for a host: `formstr-mcp switch <npub>` to a bunker account and the
+  config needs no secret at all.
 
 | Variable                           | Meaning                                                           |
 | ---------------------------------- | ----------------------------------------------------------------- |
@@ -81,8 +92,9 @@ unattended. At boot the active account is unlocked headlessly:
 | `FORMSTR_MCP_KEYSTORE`             | force `file` or `keychain` backend (optional)                     |
 | `FORMSTR_MCP_CONFIG_DIR`           | keystore directory (default `~/.config/formstr-mcp`)              |
 | `FORMSTR_RELAYS`                   | comma-separated relay override (optional)                         |
+| `FORMSTR_MCP_DEBUG`                | print full stack traces on fatal errors (set to `1`)              |
 
-CLI flags: `--relays <wss://a,wss://b>`, `--allow-writes`, `--account <pubkey>`.
+CLI flags: `--relays <wss://a,wss://b>`, `--allow-writes`, `--account <npub|hex>`.
 There is no plaintext-nsec path — a raw key is never read from env, flags, or a config file.
 
 ## Forms tools

package/dist/index.js

@@ -24405,7 +24405,26 @@ async function loginImport(deps) {
 }
 async function loginBunker(deps) {
   const uri = (await deps.prompt("Paste the bunker:// URI: ")).trim();
-  await deps.signer.loginWithBunkerUri(uri, { pool: deps.pool, perms: NIP46_PERMS });
+  try {
+    await deps.signer.loginWithBunkerUri(uri, { pool: deps.pool, perms: NIP46_PERMS });
+  } catch (err) {
+    throw new Error(describeBunkerError(uri, err));
+  }
+}
+function describeBunkerError(uri, err) {
+  const raw = err instanceof Error ? err.message : String(err);
+  const hasSecret = /[?&]secret=/.test(uri);
+  const expected = "`bunker://<pubkey>?relay=wss://\u2026&secret=<token>`";
+  if (/no secret/i.test(raw) || !hasSecret) {
+    return "Could not pair with this bunker URI" + (hasSecret ? "" : " \u2014 it has no `secret=` token") + `, so the remote signer rejected the connection. A pairing URI must look like ${expected}. Copy the FULL connection URI (including \`&secret=\u2026\`) from your signer app (e.g. nsec.app \u2192 Connect app), and make sure nothing was truncated \u2014 the secret is often one-time, so generate a fresh connection if needed. Or use the QR flow: \`formstr-mcp login\` \u2192 \`q\`. (signer reported: ${raw})`;
+  }
+  if (/invalid bunker uri/i.test(raw)) {
+    return `That doesn't look like a valid bunker URI. Expected ${expected}. (parser reported: ${raw})`;
+  }
+  if (/at least one relay/i.test(raw)) {
+    return `This bunker URI has no relays. Expected ${expected}. (reported: ${raw})`;
+  }
+  return `Bunker login failed: ${raw}. Check that the URI includes a \`secret=\` token and at least one \`relay=\`, that the remote signer is online, or try the QR flow (\`formstr-mcp login\` \u2192 \`q\`).`;
 }
 async function loginNostrConnect(deps, log) {
   const relays = deps.relays?.length ? deps.relays : DEFAULT_NOSTRCONNECT_RELAYS;
@@ -24426,6 +24445,19 @@ function whoami(signer) {
 function listAccounts(signer) {
   return signer.listAccounts();
 }
+function findAccount(accounts, target) {
+  return accounts.find((a) => a.npub === target || a.pubkey === target) ?? null;
+}
+async function doSwitch(signer, target) {
+  const match = findAccount(listAccounts(signer), target);
+  if (!match) {
+    throw new Error(
+      `No stored account matching "${target}". Run \`formstr-mcp accounts\` to list them.`
+    );
+  }
+  await signer.switchAccount(match.pubkey);
+  return match;
+}
 
 // src/auth/kvStore.ts
 var import_node_crypto = require("crypto");
@@ -27366,7 +27398,7 @@ async function bootstrap(input, deps = {}) {
 }
 async function selectAccount(signer, requested) {
   if (requested) {
-    const match = signer.listAccounts().find((a) => a.pubkey === requested);
+    const match = findAccount(signer.listAccounts(), requested);
     if (!match) {
       throw new Error(
         `No stored account for --account ${requested}. Run \`formstr-mcp accounts\` to list them.`
@@ -27383,18 +27415,7 @@ async function selectAccount(signer, requested) {
 }
 async function unlock(signer, account, deps) {
   if (account.method === "ncryptsec") {
-    if (!account.ncryptsec) {
-      throw new Error(
-        "Stored ncryptsec account is missing its encrypted key. Run `formstr-mcp login`."
-      );
-    }
-    const passphrase = deps.passphrase ?? process.env.FORMSTR_MCP_NCRYPTSEC_PASSPHRASE ?? (deps.promptPassphrase ? await deps.promptPassphrase("Passphrase to unlock your key: ") : void 0);
-    if (!passphrase) {
-      throw new Error(
-        "Set FORMSTR_MCP_NCRYPTSEC_PASSPHRASE to unlock the ncryptsec account at boot (or run in an interactive terminal to be prompted)."
-      );
-    }
-    await signer.loginWithNcryptsec(account.ncryptsec, passphrase);
+    await unlockNcryptsec(signer, account, deps);
     return;
   }
   if (account.method === "nip46") {
@@ -27414,31 +27435,108 @@ async function unlock(signer, account, deps) {
     `Account method "${account.method}" cannot be unlocked headlessly \u2014 use ncryptsec or nip46.`
   );
 }
+var MAX_PASSPHRASE_ATTEMPTS = 3;
+async function unlockNcryptsec(signer, account, deps) {
+  if (!account.ncryptsec) {
+    throw new Error(
+      `Account ${account.npub} is stored as an ncryptsec but its encrypted key is missing. Re-add it with \`formstr-mcp login\`.`
+    );
+  }
+  const ncryptsec = account.ncryptsec;
+  const tryUnlock = async (passphrase) => {
+    try {
+      await signer.loginWithNcryptsec(ncryptsec, passphrase);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const configured = deps.passphrase ?? process.env.FORMSTR_MCP_NCRYPTSEC_PASSPHRASE;
+  if (configured) {
+    if (await tryUnlock(configured)) return;
+    if (!deps.promptPassphrase) {
+      throw new Error(
+        `The configured passphrase did not unlock account ${account.npub} \u2014 it is most likely the wrong passphrase for this account (each account has its own). Set FORMSTR_MCP_NCRYPTSEC_PASSPHRASE to the passphrase that matches this account, or switch to another with \`formstr-mcp switch <npub>\` (a nip46/bunker account needs no passphrase).`
+      );
+    }
+    console.error(
+      `formstr-mcp: the configured passphrase didn't unlock ${account.npub} \u2014 enter it manually.`
+    );
+  } else if (!deps.promptPassphrase) {
+    throw new Error(
+      `Cannot unlock account ${account.npub} (ncryptsec): no passphrase is available. FORMSTR_MCP_NCRYPTSEC_PASSPHRASE is not set and this process has no interactive terminal to prompt on \u2014 an MCP host runs the server with stdin wired to the JSON-RPC channel. Fix: add FORMSTR_MCP_NCRYPTSEC_PASSPHRASE to your MCP server config's \`env\`, or switch to a nip46/bunker account with \`formstr-mcp switch <npub>\` (resumes with no passphrase).`
+    );
+  }
+  const promptPassphrase = deps.promptPassphrase;
+  for (let attempt = 1; attempt <= MAX_PASSPHRASE_ATTEMPTS; attempt++) {
+    const passphrase = await promptPassphrase(`Passphrase to unlock ${account.npub}: `);
+    if (await tryUnlock(passphrase)) return;
+    const left = MAX_PASSPHRASE_ATTEMPTS - attempt;
+    if (left > 0) console.error(`formstr-mcp: incorrect passphrase, ${left} attempt(s) left.`);
+  }
+  throw new Error(
+    `Incorrect passphrase for account ${account.npub} after ${MAX_PASSPHRASE_ATTEMPTS} attempts.`
+  );
+}
 
 // src/cli.ts
-var SUBCOMMANDS = /* @__PURE__ */ new Set(["login", "logout", "whoami", "accounts"]);
+var SUBCOMMANDS = /* @__PURE__ */ new Set(["login", "logout", "whoami", "accounts", "switch", "help"]);
 function parseCli(argv) {
   const rest = [...argv];
+  if (rest.includes("-h") || rest.includes("--help")) {
+    return { command: "help", allowWrites: false };
+  }
   let command = "run";
   if (rest[0] && SUBCOMMANDS.has(rest[0])) {
     command = rest.shift();
   }
   let relays;
   let account;
+  let target;
   let allowWrites = false;
   for (let i4 = 0; i4 < rest.length; i4++) {
     const arg = rest[i4];
     if (arg === "--relays") relays = splitRelays(rest[++i4]);
     else if (arg === "--allow-writes") allowWrites = true;
     else if (arg === "--account") account = rest[++i4];
+    else if (!arg.startsWith("-") && target === void 0) target = arg;
   }
-  return { command, relays, allowWrites, account };
+  return { command, relays, allowWrites, account, target };
+}
+function formatFatal(err, debug = false) {
+  if (err instanceof Error) return debug && err.stack ? err.stack : err.message;
+  return String(err);
 }
 function splitRelays(value) {
   if (!value) return void 0;
   const parts = value.split(",").map((s) => s.trim()).filter(Boolean);
   return parts.length ? parts : void 0;
 }
+function helpText() {
+  return [
+    "formstr-mcp \u2014 MCP server for the Formstr super-app (Nostr forms & more).",
+    "",
+    "Usage: formstr-mcp [command] [flags]",
+    "",
+    "Commands:",
+    "  run               Run the stdio MCP server (default when no command is given).",
+    "  login             Sign in (create / import / bunker URI / QR) and store the key.",
+    "  logout [npub]     Remove a stored account (defaults to the active one).",
+    "  whoami            Print the active account.",
+    "  accounts          List stored accounts ('*' marks the active one).",
+    "  switch <npub>     Set the active account (accepts an npub or hex pubkey).",
+    "  help              Show this help (also -h, --help).",
+    "",
+    "Flags:",
+    "  --allow-writes         Enable gated write tools (update / delete / share / submit).",
+    "  --account <npub|hex>   Boot a specific account instead of the active one.",
+    "  --relays <a,b,\u2026>       Override relays (comma-separated).",
+    "",
+    "Env:",
+    "  FORMSTR_MCP_NCRYPTSEC_PASSPHRASE   Unlock the active ncryptsec account at boot.",
+    "  FORMSTR_MCP_PASSPHRASE             Encrypt the keystore file (keychain-less hosts)."
+  ].join("\n");
+}
 
 // src/config.ts
 function resolveConfig(cli, env) {
@@ -32063,14 +32161,22 @@ function buildSpecRows(formId, name, fields, settings) {
   for (const field of fields) rows.push(buildFieldTag(field));
   return rows;
 }
-function buildEncryptedOuterTags(formId, name, relays, settings) {
-  const tags = [["d", formId], ["name", name], ...relays.map((r) => ["relay", r])];
+function buildParticipantTags(settings) {
+  const tags = [];
   const allowed = settings?.allowedResponders ?? [];
   const pTags = /* @__PURE__ */ new Set([...allowed, ...settings?.collaborators ?? []]);
   for (const pk of allowed) tags.push(["allowed", pk]);
   for (const pk of pTags) tags.push(["p", pk]);
   return tags;
 }
+function buildEncryptedOuterTags(formId, name, relays, settings) {
+  return [
+    ["d", formId],
+    ["name", name],
+    ...relays.map((r) => ["relay", r]),
+    ...buildParticipantTags(settings)
+  ];
+}
 async function createForm(params) {
   await signerManager.getSigner();
   const formId = crypto.randomUUID().slice(0, 8);
@@ -32096,7 +32202,12 @@ async function createForm(params) {
     await appendToMyFormsList(signingPubkey, formId, relays[0] ?? "", signingKeyHex, viewKeyHex);
     return { formId, pubkey: signingPubkey, signingKey: signingKeyHex, viewKey: viewKeyHex };
   }
-  const tags = [...specRows, ["t", "public"], ...relays.map((r) => ["relay", r])];
+  const tags = [
+    ...specRows,
+    ["t", "public"],
+    ...relays.map((r) => ["relay", r]),
+    ...buildParticipantTags(params.settings)
+  ];
   const event = {
     kind: FORM_KINDS.template,
     created_at: Math.floor(Date.now() / 1e3),
@@ -32416,7 +32527,12 @@ async function updateForm(params) {
     await nostrRuntime.publish(relays, finalizeEvent(event2, signingKeyBytes));
     return;
   }
-  const tags = [...specRows, ["t", "public"], ...relays.map((r) => ["relay", r])];
+  const tags = [
+    ...specRows,
+    ["t", "public"],
+    ...relays.map((r) => ["relay", r]),
+    ...buildParticipantTags(settings)
+  ];
   const event = {
     kind: FORM_KINDS.template,
     created_at: Math.floor(Date.now() / 1e3),
@@ -32548,6 +32664,7 @@ function parseResponseEvent(event) {
 var service_exports2 = {};
 __export(service_exports2, {
   addEventToCalendarList: () => addEventToCalendarList,
+  createCalendarEvent: () => createCalendarEvent,
   createCalendarList: () => createCalendarList,
   deleteCalendarEvent: () => deleteCalendarEvent,
   deleteCalendarList: () => deleteCalendarList,
@@ -32978,6 +33095,33 @@ async function publishPrivateCalendarEvent(draft, calendarId) {
     event: signed
   };
 }
+async function createCalendarEvent(draft, opts = {}) {
+  let calendars = opts.calendars ?? null;
+  const loadCalendars = async () => calendars ?? (calendars = await fetchCalendarLists());
+  let targetCalendarId = draft.calendarId;
+  let targetCalendar;
+  if (targetCalendarId) {
+    targetCalendar = (await loadCalendars()).find((c) => c.id === targetCalendarId);
+  } else if (draft.isPrivate) {
+    targetCalendar = (await loadCalendars())[0];
+    if (!targetCalendar) targetCalendar = await createCalendarList("My Calendar", "#334155");
+    targetCalendarId = targetCalendar.id;
+  }
+  const event = draft.isPrivate ? await publishPrivateCalendarEvent(
+    { ...draft, calendarId: targetCalendarId },
+    targetCalendarId ?? "default"
+  ) : await publishPublicCalendarEvent(draft);
+  let calendar;
+  if (targetCalendar) {
+    const ref = [
+      `${event.kind}:${event.user}:${event.id}`,
+      event.relayHint ?? "",
+      event.viewKey ?? ""
+    ];
+    calendar = await addEventToCalendarList(targetCalendar, ref);
+  }
+  return { event, calendar };
+}
 async function fetchRelayListsForPubkeys(pubkeys) {
   const result = /* @__PURE__ */ new Map();
   if (pubkeys.length === 0) return result;
@@ -34104,6 +34248,7 @@ async function fetchDocMetadata(address) {
 async function saveDocMetadata(address, patch) {
   const existing = await fetchDocMetadata(address) ?? {};
   const merged = { ...existing, ...patch };
+  if (!Array.isArray(merged.tags)) merged.tags = [];
   const signer = await signerManager.getSigner();
   const content = await nip44SelfEncrypt(signer, JSON.stringify(merged));
   const signed = await signer.signEvent({
@@ -34288,7 +34433,9 @@ async function uploadFile(params) {
     name: params.file.name,
     hash: result.sha256,
     size: params.file.size,
-    type: params.file.type,
+    // Browsers report "" for unknown MIME types; coalesce exactly as upstream
+    // formstr-drive's uploadPreparedFile does so the on-wire metadata matches.
+    type: params.file.type || "application/octet-stream",
     folder: params.folder ?? "/",
     uploadedAt: Date.now(),
     server,
@@ -34504,8 +34651,9 @@ async function createPoll(draft) {
   for (const tag of draft.hashtags ?? []) {
     tags.push(["t", tag]);
   }
-  if (draft.endsAt) {
-    tags.push(["endsAt", String(Math.floor(draft.endsAt.getTime() / 1e3))]);
+  const endsAtSec = draft.endsAt && Number.isFinite(draft.endsAt.getTime()) ? Math.floor(draft.endsAt.getTime() / 1e3) : void 0;
+  if (endsAtSec !== void 0) {
+    tags.push(["endsAt", String(endsAtSec)]);
   }
   const event = {
     kind: POLLS_KINDS.poll,
@@ -34522,7 +34670,7 @@ async function createPoll(draft) {
     pollType: draft.pollType,
     pubkey,
     createdAt: signed.created_at,
-    endsAt: draft.endsAt ? Math.floor(draft.endsAt.getTime() / 1e3) : void 0,
+    endsAt: endsAtSec,
     relays,
     hashtags: draft.hashtags ?? [],
     event: signed
@@ -34756,7 +34904,7 @@ function buildCalendarTools() {
   server.registerTool(
     "create_calendar_event",
     {
-      description: "Schedule a calendar event. start/end are ISO 8601. Set isPrivate:true for an encrypted event; participants receive NIP-59 invitations.",
+      description: "Schedule a calendar event. start/end are ISO 8601. Events default to PRIVATE (encrypted) and are linked into a calendar list \u2014 that is the only way they show on calendar.formstr.app, which renders only events referenced in a calendar list. Pass calendarId to choose which calendar; if omitted and the user already has calendars, this tool returns the list so you can ASK the user which one (then re-run with calendarId). Set isPrivate:false for a public, unencrypted event \u2014 note public events do NOT sync to calendar.formstr.app. participants receive NIP-59 invitations.",
       inputSchema: {
         title: external_exports.string(),
         description: external_exports.string().optional(),
@@ -34764,6 +34912,7 @@ function buildCalendarTools() {
         end: external_exports.string().optional(),
         location: external_exports.string().optional(),
         isPrivate: external_exports.boolean().optional(),
+        calendarId: external_exports.string().optional(),
         participants: external_exports.array(external_exports.string()).optional(),
         rrule: external_exports.string().optional(),
         startTzid: external_exports.string().optional(),
@@ -34771,6 +34920,22 @@ function buildCalendarTools() {
       }
     },
     async (args) => {
+      const isPrivate = args.isPrivate ?? true;
+      const calendars = await service_exports2.fetchCalendarLists();
+      if (isPrivate && !args.calendarId && calendars.length > 0) {
+        const choices = calendars.map((c) => `${c.title} (${c.id})`).join("; ");
+        return fail(
+          `Which calendar should "${args.title}" go in? Re-run create_calendar_event with calendarId set to one of: ${choices}.`,
+          "CALENDAR_REQUIRED"
+        );
+      }
+      if (args.calendarId && !calendars.some((c) => c.id === args.calendarId)) {
+        const available = calendars.map((c) => c.id).join(", ") || "(none)";
+        return fail(
+          `No calendar found for id ${args.calendarId}. Available: ${available}.`,
+          "NOT_FOUND"
+        );
+      }
       const begin = new Date(args.start);
       const end = args.end ? new Date(args.end) : new Date(begin.getTime() + 36e5);
       const draft = {
@@ -34780,18 +34945,23 @@ function buildCalendarTools() {
         end,
         location: args.location,
         participants: args.participants,
-        isPrivate: Boolean(args.isPrivate),
+        isPrivate,
+        calendarId: args.calendarId,
         rrule: args.rrule,
         startTzid: args.startTzid,
         registrationFormRef: args.registrationFormRef
       };
-      const event = args.isPrivate ? await service_exports2.publishPrivateCalendarEvent(draft, "default") : await service_exports2.publishPublicCalendarEvent(draft);
+      const { event, calendar: list } = await service_exports2.createCalendarEvent(draft, { calendars });
       const coordinate = `${event.kind}:${event.user}:${event.id}`;
-      return ok(`Created ${args.isPrivate ? "private" : "public"} event "${args.title}".`, {
-        id: event.id,
-        eventId: event.eventId,
-        coordinate
-      });
+      return ok(
+        `Created ${isPrivate ? "private" : "public"} event "${args.title}"${list ? ` in calendar "${list.title}"` : ""}.`,
+        {
+          id: event.id,
+          eventId: event.eventId,
+          coordinate,
+          calendarId: list?.id
+        }
+      );
     }
   );
   server.registerTool(
@@ -46448,6 +46618,19 @@ async function main() {
       }
       return cli.command;
     }
+    case "switch": {
+      if (!cli.target) {
+        throw new Error(
+          "Usage: formstr-mcp switch <npub|hex>. Run `formstr-mcp accounts` to list them."
+        );
+      }
+      const account = await doSwitch(await buildMcpSigner(), cli.target);
+      console.error(`formstr-mcp: active account is now ${account.npub} (${account.method}).`);
+      return cli.command;
+    }
+    case "help":
+      console.error(helpText());
+      return cli.command;
     case "run":
     default:
       await runServer(cli);
@@ -46457,7 +46640,9 @@ async function main() {
 main().then((command) => {
   if (command !== "run") process.exit(0);
 }).catch((err) => {
-  console.error("formstr-mcp: fatal:", err instanceof Error ? err.message : err);
+  const debug = !!(process.env.FORMSTR_MCP_DEBUG || process.env.DEBUG);
+  console.error("formstr-mcp: fatal:", formatFatal(err, debug));
+  if (!debug) console.error("formstr-mcp: (set FORMSTR_MCP_DEBUG=1 for a full stack trace)");
   process.exit(1);
 });
 /*! Bundled license information: