@formstr/mcp 0.3.1 → 0.4.0

package/README.md

@@ -21,9 +21,27 @@ npx -y @formstr/mcp login
 ```
 
 Subcommands: `formstr-mcp login` · `formstr-mcp whoami` · `formstr-mcp accounts` ·
-`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.
+`formstr-mcp switch <npub>` · `formstr-mcp logout` · `formstr-mcp version` ·
+`formstr-mcp help` · `formstr-mcp` (run the stdio server, the default). Run
+`formstr-mcp help` (or `-h`) for the full usage.
+
+## Version & updates
+
+`formstr-mcp version` (or `-v` / `--version`) prints the installed version and checks the
+npm registry for a newer release:
+
+```text
+$ formstr-mcp version
+@formstr/mcp 0.4.0
+Update available: 0.5.0 (you have 0.4.0).
+Upgrade: npm install -g @formstr/mcp@latest
+Or just re-run via: npx -y @formstr/mcp@latest
+```
+
+The update check is best-effort — if you're offline or the registry is unreachable it
+prints the installed version and a note, never an error. If you run the server via
+`npx -y @formstr/mcp` you already get the latest published version on each launch; pin a
+version (`@formstr/mcp@0.4.0`) in your host config if you'd rather control upgrades.
 
 ## Sign-in
 
@@ -71,6 +89,82 @@ After `login`, no key belongs in the config:
 Add `"--allow-writes"` to `args` to enable the gated (destructive/outward) tools, and
 `"--relays", "wss://a,wss://b"` to override relays.
 
+### Passing the ncryptsec passphrase
+
+If your active account is an `ncryptsec` key (Create / Import login), the server needs its
+passphrase to unlock at boot. An MCP host spawns the server with stdin wired to the
+JSON-RPC channel, so it **can't prompt** — supply the passphrase through an `"env"` block in
+the server entry of your MCP config (`mcp_config.json`, `claude_desktop_config.json`, Cursor's
+`~/.cursor/mcp.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "formstr": {
+      "command": "npx",
+      "args": ["-y", "@formstr/mcp"],
+      "env": {
+        "FORMSTR_MCP_NCRYPTSEC_PASSPHRASE": "your-passphrase-here"
+      }
+    }
+  }
+}
+```
+
+The host hands that value to the server as an environment variable at startup — it never
+enters the chat transcript. Each account has its own passphrase, so this unlocks whichever
+one is **active** (set it with `formstr-mcp switch <npub>`).
+
+> **Tip:** prefer not to keep a passphrase in a config file? Use a **NIP-46 (bunker)**
+> account instead — it reconnects from its stored session and needs **no** passphrase, so
+> the config can stay secret-free. Run `formstr-mcp switch <npub>` to a bunker account.
+
+## Using with Ollama (local models)
+
+Ollama isn't an MCP client — it just runs the model. To drive this server with a **local**
+model you need an MCP **host** that uses Ollama as its backend. A good, actively-maintained
+option is [**Goose**](https://block.github.io/goose/) (open-source agent by Block; CLI +
+desktop), which has both first-class Ollama support and native stdio MCP extensions.
+
+**1. Pull a tool-calling-capable model and start Ollama:**
+
+```bash
+ollama pull qwen2.5     # llama3.1 / 3.2, mistral, … also work — the model MUST support tools
+ollama serve            # serves the API on http://localhost:11434
+```
+
+A model **without** tool/function-calling support can chat but can't invoke this server's
+tools (`list_forms`, `create_form`, …), so don't pick one of those.
+
+**2. Sign in to formstr once** (stores your key in the keystore):
+
+```bash
+npx -y @formstr/mcp login
+```
+
+**3. Point Goose at Ollama** — `goose configure` → _Configure Providers_ → **Ollama**, then
+enter the host (`http://localhost:11434`) and pick your model.
+
+**4. Add this server as an extension** — `goose configure` → _Add Extension_ → **Command-line
+Extension**, then answer the prompts:
+
+| Prompt                | Value                                                         |
+| --------------------- | ------------------------------------------------------------- |
+| Name                  | `formstr`                                                     |
+| Command               | `npx -y @formstr/mcp` (add `--allow-writes` to enable writes) |
+| Timeout (secs)        | `300`                                                         |
+| Environment variables | `FORMSTR_MCP_NCRYPTSEC_PASSPHRASE` = _your passphrase_        |
+
+Goose passes that env var to the server when it spawns it (so it unlocks headlessly), and
+saves the extension to `~/.config/goose/config.yaml`. Then just run `goose` (or `goose
+session`) and ask it to work with your forms.
+
+> **Bunker accounts need no passphrase** — skip the env-variable step and `formstr-mcp switch
+<npub>` to a NIP-46 account (see the tip above); the extension then stores no secret.
+
+The same approach works with any other Ollama-backed MCP host: point it at
+`npx -y @formstr/mcp` and supply the passphrase through that host's env mechanism.
+
 ## Headless / unattended
 
 Run `formstr-mcp login` once interactively to populate the keystore, then run the server

package/dist/index.js

@@ -24436,8 +24436,21 @@ async function loginNostrConnect(deps, log) {
     perms: NIP46_PERMS
   });
 }
-async function doLogout(signer, pubkey) {
-  await signer.logout(pubkey);
+async function doLogout(signer, target) {
+  if (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.logout(match.pubkey);
+    return match;
+  }
+  const active = signer.getActiveAccount();
+  if (!active) return null;
+  await signer.logout(active.pubkey);
+  return active;
 }
 function whoami(signer) {
   return signer.getActiveAccount();
@@ -27480,12 +27493,23 @@ async function unlockNcryptsec(signer, account, deps) {
 }
 
 // src/cli.ts
-var SUBCOMMANDS = /* @__PURE__ */ new Set(["login", "logout", "whoami", "accounts", "switch", "help"]);
+var SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "login",
+  "logout",
+  "whoami",
+  "accounts",
+  "switch",
+  "help",
+  "version"
+]);
 function parseCli(argv) {
   const rest = [...argv];
   if (rest.includes("-h") || rest.includes("--help")) {
     return { command: "help", allowWrites: false };
   }
+  if (rest.includes("-v") || rest.includes("--version")) {
+    return { command: "version", allowWrites: false };
+  }
   let command = "run";
   if (rest[0] && SUBCOMMANDS.has(rest[0])) {
     command = rest.shift();
@@ -27521,11 +27545,12 @@ function helpText() {
     "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).",
+    "  logout [npub|hex] Permanently remove a stored account from the keystore (defaults to active).",
     "  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).",
+    "  version           Print the installed version and check for an update (also -v, --version).",
     "",
     "Flags:",
     "  --allow-writes         Enable gated write tools (update / delete / share / submit).",
@@ -27534,7 +27559,28 @@ function helpText() {
     "",
     "Env:",
     "  FORMSTR_MCP_NCRYPTSEC_PASSPHRASE   Unlock the active ncryptsec account at boot.",
-    "  FORMSTR_MCP_PASSPHRASE             Encrypt the keystore file (keychain-less hosts)."
+    "  FORMSTR_MCP_PASSPHRASE             Encrypt the keystore file (keychain-less hosts).",
+    "",
+    "Setting the passphrase in your MCP host config:",
+    "  When an MCP host (Claude Desktop/Code, Cursor, \u2026) spawns the server, stdin is the",
+    "  JSON-RPC channel, so it can't prompt for your ncryptsec passphrase. Pass it via an",
+    '  "env" block in the server entry of your MCP config (e.g. mcp_config.json /',
+    "  claude_desktop_config.json) so the host hands it to the server at startup:",
+    "",
+    "    {",
+    '      "mcpServers": {',
+    '        "formstr": {',
+    '          "command": "npx",',
+    '          "args": ["-y", "@formstr/mcp"],',
+    '          "env": {',
+    '            "FORMSTR_MCP_NCRYPTSEC_PASSPHRASE": "your-passphrase-here"',
+    "          }",
+    "        }",
+    "      }",
+    "    }",
+    "",
+    "  Tip: a NIP-46 (bunker) account needs no passphrase \u2014 `switch` to one and the config",
+    '  can stay secret-free. Add "--allow-writes" to args to enable gated write tools.'
   ].join("\n");
 }
 
@@ -32418,19 +32464,27 @@ async function fetchMyForms() {
     return summary;
   }).filter((s) => s !== null);
 }
+var MY_FORMS_LIST_READ_ATTEMPTS = 3;
+async function readMyFormsEntriesForWrite(signer, userPubkey, relays) {
+  let listEvent = null;
+  for (let attempt = 0; attempt < MY_FORMS_LIST_READ_ATTEMPTS; attempt++) {
+    listEvent = await fetchLatestMyFormsEvent(relays, userPubkey);
+    if (listEvent?.content) break;
+  }
+  if (!listEvent?.content) return [];
+  try {
+    return await decryptListEntries(signer, userPubkey, listEvent.content);
+  } catch (err) {
+    throw new Error(
+      `Could not read your existing forms list to add this form, so it was left unchanged to avoid losing your other forms. The form itself was published \u2014 retry to add it. (${err instanceof Error ? err.message : String(err)})`
+    );
+  }
+}
 async function appendToMyFormsList(formPubkey, formId, relay, signingKeyHex, viewKeyHex) {
   const signer = await signerManager.getSigner();
   const userPubkey = await signer.getPublicKey();
   const relays = relayManager.getRelaysForModule("forms");
-  const existing = await fetchLatestMyFormsEvent(relays, userPubkey);
-  let entries = [];
-  if (existing?.content) {
-    try {
-      entries = await decryptListEntries(signer, userPubkey, existing.content);
-    } catch {
-      entries = [];
-    }
-  }
+  let entries = await readMyFormsEntriesForWrite(signer, userPubkey, relays);
   entries = entries.map(
     (e) => e[0] === "f" && e.length < 4 ? ["f", e[1] ?? "", e[2] ?? "", ""] : e
   );
@@ -32614,9 +32668,13 @@ async function fetchFormSummaryFromRef(pubkey, formId) {
   };
 }
 async function importForm(summary) {
-  const current = await fetchMyForms();
-  if (current.some((f) => f.id === summary.id && f.pubkey === summary.pubkey)) return;
-  await saveToMyForms([...current, summary]);
+  await appendToMyFormsList(
+    summary.pubkey,
+    summary.id,
+    summary.relay ?? "",
+    summary.signingKey,
+    summary.viewKey
+  );
 }
 function parseFormEvent(event, decryptedRows) {
   const merged = decryptedRows ? [...event.tags, ...decryptedRows] : event.tags;
@@ -34865,6 +34923,25 @@ function computeResults(responses) {
   return { results, totalVotes: totalVoters };
 }
 
+// ../agent/src/tools/pubkey.ts
+function normalizePubkey(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (/^[0-9a-f]{64}$/i.test(trimmed)) return trimmed.toLowerCase();
+  if (trimmed.startsWith("npub1")) {
+    try {
+      const decoded = nip19_exports.decode(trimmed);
+      if (decoded.type === "npub") return decoded.data;
+    } catch {
+    }
+  }
+  return null;
+}
+function normalizePubkeyList(values) {
+  if (!Array.isArray(values)) return [];
+  return values.map((v) => typeof v === "string" ? normalizePubkey(v) : null).filter((p) => !!p);
+}
+
 // ../agent/src/tools/calendar.ts
 var calendarTools = buildCalendarTools();
 function buildCalendarTools() {
@@ -34904,7 +34981,7 @@ function buildCalendarTools() {
   server.registerTool(
     "create_calendar_event",
     {
-      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.",
+      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 (npub or hex) receive NIP-59 invitations.",
       inputSchema: {
         title: external_exports.string(),
         description: external_exports.string().optional(),
@@ -34944,7 +35021,9 @@ function buildCalendarTools() {
         begin,
         end,
         location: args.location,
-        participants: args.participants,
+        // Accept npub OR hex for each participant — the wire (["p"] tags, NIP-59
+        // invitation wraps, relay-list query) needs hex, so convert here.
+        participants: normalizePubkeyList(args.participants),
         isPrivate,
         calendarId: args.calendarId,
         rrule: args.rrule,
@@ -34971,7 +35050,8 @@ function buildCalendarTools() {
       inputSchema: { coordinate: external_exports.string() }
     },
     async ({ coordinate }) => {
-      const event = await service_exports2.fetchCalendarEventByCoordinate(coordinate);
+      const viewKey = await service_exports2.lookupEventViewKey(coordinate);
+      const event = await service_exports2.fetchCalendarEventByCoordinate(coordinate, viewKey);
       if (!event) return fail(`No event found for ${coordinate}.`, "NOT_FOUND");
       return ok(`Event "${event.title}".`, {
         event: {
@@ -35222,7 +35302,8 @@ function buildCalendarTools() {
         `updates event ${args.coordinate}`
       );
       if (blocked) return blocked;
-      const existing = await service_exports2.fetchCalendarEventByCoordinate(args.coordinate);
+      const viewKey = await service_exports2.lookupEventViewKey(args.coordinate);
+      const existing = await service_exports2.fetchCalendarEventByCoordinate(args.coordinate, viewKey);
       if (!existing) return fail(`No event found for ${args.coordinate}.`, "NOT_FOUND");
       const draft = {
         title: args.title ?? existing.title,
@@ -35264,7 +35345,8 @@ function buildCalendarTools() {
         `attaches a form to ${coordinate}`
       );
       if (blocked) return blocked;
-      const existing = await service_exports2.fetchCalendarEventByCoordinate(coordinate);
+      const viewKey = await service_exports2.lookupEventViewKey(coordinate);
+      const existing = await service_exports2.fetchCalendarEventByCoordinate(coordinate, viewKey);
       if (!existing) return fail(`No event found for ${coordinate}.`, "NOT_FOUND");
       const draft = {
         title: existing.title,
@@ -35543,23 +35625,6 @@ function buildDriveTools() {
 }
 
 // ../agent/src/tools/shared.ts
-function normalizePubkey(value) {
-  const trimmed = value.trim();
-  if (!trimmed) return null;
-  if (/^[0-9a-f]{64}$/i.test(trimmed)) return trimmed.toLowerCase();
-  if (trimmed.startsWith("npub1")) {
-    try {
-      const decoded = nip19_exports.decode(trimmed);
-      if (decoded.type === "npub") return decoded.data;
-    } catch {
-    }
-  }
-  return null;
-}
-function normalizePubkeyList(values) {
-  if (!Array.isArray(values)) return [];
-  return values.map((v) => typeof v === "string" ? normalizePubkey(v) : null).filter((p) => !!p);
-}
 var ANSWER_TYPES = new Set(Object.values(AnswerType));
 var LEGACY_TYPE_ALIASES = {
   multiChoiceGrid: "multipleChoiceGrid" /* multipleChoiceGrid */
@@ -46543,6 +46608,95 @@ async function startStdio(ctx) {
   await server.connect(transport);
 }
 
+// src/version.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var PACKAGE_NAME = "@formstr/mcp";
+function readInstalledVersion() {
+  try {
+    const pkg = JSON.parse((0, import_node_fs2.readFileSync)((0, import_node_path2.join)(__dirname, "..", "package.json"), "utf8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function parseSemver(version2) {
+  const cleaned = version2.trim().replace(/^v/i, "").split("+")[0];
+  const [core, pre] = cleaned.split("-", 2);
+  const release = core.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  while (release.length < 3) release.push(0);
+  return { release, prerelease: pre ? pre.split(".") : [] };
+}
+function compareIdentifiers(a, b) {
+  const na = /^\d+$/.test(a);
+  const nb = /^\d+$/.test(b);
+  if (na && nb) return Number(a) - Number(b) < 0 ? -1 : Number(a) === Number(b) ? 0 : 1;
+  if (na) return -1;
+  if (nb) return 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function compareVersions(a, b) {
+  const va = parseSemver(a);
+  const vb = parseSemver(b);
+  for (let i4 = 0; i4 < 3; i4++) {
+    if (va.release[i4] !== vb.release[i4]) return va.release[i4] < vb.release[i4] ? -1 : 1;
+  }
+  if (va.prerelease.length === 0 && vb.prerelease.length === 0) return 0;
+  if (va.prerelease.length === 0) return 1;
+  if (vb.prerelease.length === 0) return -1;
+  const len = Math.max(va.prerelease.length, vb.prerelease.length);
+  for (let i4 = 0; i4 < len; i4++) {
+    const ia = va.prerelease[i4];
+    const ib = vb.prerelease[i4];
+    if (ia === void 0) return -1;
+    if (ib === void 0) return 1;
+    const c = compareIdentifiers(ia, ib);
+    if (c !== 0) return c < 0 ? -1 : 1;
+  }
+  return 0;
+}
+async function fetchLatestVersion(pkgName, opts = {}) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? 3e3;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(`https://registry.npmjs.org/${pkgName}/latest`, {
+      signal: controller.signal,
+      // The abbreviated metadata document is far smaller than the full packument.
+      headers: { accept: "application/vnd.npm.install-v1+json" }
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function formatVersionReport(installed, latest) {
+  const head = `${PACKAGE_NAME} ${installed}`;
+  if (!latest) {
+    return `${head}
+(could not check for updates \u2014 offline or registry unreachable)`;
+  }
+  const cmp = compareVersions(installed, latest);
+  if (cmp < 0) {
+    return [
+      head,
+      `Update available: ${latest} (you have ${installed}).`,
+      `Upgrade: npm install -g ${PACKAGE_NAME}@latest`,
+      `Or just re-run via: npx -y ${PACKAGE_NAME}@latest`
+    ].join("\n");
+  }
+  if (cmp > 0) {
+    return `${head}
+(ahead of the latest published release ${latest})`;
+  }
+  return `${head} (latest)`;
+}
+
 // src/index.ts
 async function runServer(cli) {
   const cfg = resolveConfig(cli, process.env);
@@ -46593,8 +46747,10 @@ async function main() {
       await runLogin(cli);
       return cli.command;
     case "logout": {
-      await doLogout(await buildMcpSigner(), cli.account);
-      console.error("formstr-mcp: signed out.");
+      const removed = await doLogout(await buildMcpSigner(), cli.target ?? cli.account);
+      console.error(
+        removed ? `formstr-mcp: removed ${removed.npub} (${removed.method}).` : "formstr-mcp: no account to remove."
+      );
       return cli.command;
     }
     case "whoami": {
@@ -46631,6 +46787,12 @@ async function main() {
     case "help":
       console.error(helpText());
       return cli.command;
+    case "version": {
+      const installed = readInstalledVersion();
+      const latest = await fetchLatestVersion(PACKAGE_NAME);
+      console.log(formatVersionReport(installed, latest));
+      return cli.command;
+    }
     case "run":
     default:
       await runServer(cli);