@formstr/mcp 0.3.2 → 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

@@ -27493,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();
@@ -27539,6 +27550,7 @@ function helpText() {
     "  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).",
@@ -27547,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");
 }
 
@@ -32431,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
   );
@@ -32627,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;
@@ -46563,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);
@@ -46653,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);