@formstr/mcp 0.3.2 → 0.5.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.5.0
+Update available: 0.6.0 (you have 0.5.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.5.0`) in your host config if you'd rather control upgrades.
 
 ## Sign-in
 
@@ -71,6 +89,88 @@ 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.
 
+> **Note:** the default (no `--allow-writes`) is _not_ read-only. Create/import tools
+> (`create_form`, `create_calendar_event`, `create_calendar`, `create_poll`, `create_page`,
+> `import_form_from_naddr`) are always enabled and publish events on your identity. The
+> flag gates the tools that modify or delete existing data or act toward other people
+> (update / delete / share / submit / RSVP).
+
+### 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
@@ -130,9 +230,16 @@ actions; see the source under `src/tools/`.
 Destructive / outward tools are **not registered** unless `--allow-writes` (or
 `FORMSTR_ALLOW_WRITES=true`) is set, AND each such call additionally requires
 `"confirm": true`. Without `confirm`, the tool returns a structured "confirmation
-required" message naming the irreversible effect instead of executing. `share_form`
-distributes only the view key (read access) — never the signing key. Logging goes to
-stderr (stdout is the MCP transport).
+required" message naming the irreversible effect instead of executing.
+
+**Create tools are always on.** `--allow-writes` gates updates, deletions, shares,
+submissions, and RSVPs — not creation. Creating a new form/event/calendar/poll/page
+(and importing a form) publishes to relays on your identity even without the flag,
+because a fresh entity can't clobber existing data. If you need a strictly read-only
+server, don't connect an identity that matters.
+
+`share_form` distributes only the view key (read access) — never the signing key.
+Logging goes to stderr (stdout is the MCP transport).
 
 ## Tests