@formstr/mcp 0.2.0 → 0.3.0

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) {
@@ -46448,6 +46546,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 +46568,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: