@formstr/mcp 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +37 -26
- package/dist/index.js +4265 -3516
- package/dist/index.js.map +1 -1
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -5,38 +5,44 @@ exposes the **Formstr** super-app (forms, calendar, pages, drive, polls) to any
|
|
|
5
5
|
Claude Code/Desktop, Cursor, and others. It builds on `@formstr/core` and the super-app's
|
|
6
6
|
service layer and talks to Nostr relays directly. Transport: **stdio**.
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
8
|
+
Identity is powered by [`@formstr/signer`](https://www.npmjs.com/package/@formstr/signer) —
|
|
9
|
+
the same login engine the Formstr web app uses. Local keys are stored **NIP-49 encrypted
|
|
10
|
+
(`ncryptsec`)** inside an OS-keychain (or encrypted-file) keystore; a raw nsec is never
|
|
11
|
+
persisted. Remote keys stay in your NIP-46 signer.
|
|
10
12
|
|
|
11
13
|
## Quick start
|
|
12
14
|
|
|
13
15
|
```bash
|
|
14
|
-
# 1. Sign in once (
|
|
16
|
+
# 1. Sign in once (terminal-interactive; key is stored encrypted in your keystore)
|
|
15
17
|
npx -y @formstr/mcp login
|
|
16
18
|
|
|
17
19
|
# 2. Point your MCP host at the server (see "Host configuration")
|
|
18
|
-
# No key in the config —
|
|
20
|
+
# No key in the config — the account is unlocked from the keystore at startup.
|
|
19
21
|
```
|
|
20
22
|
|
|
21
|
-
Subcommands: `formstr-mcp login` · `formstr-mcp whoami` · `formstr-mcp
|
|
22
|
-
`formstr-mcp` (run the stdio server, the default).
|
|
23
|
+
Subcommands: `formstr-mcp login` · `formstr-mcp whoami` · `formstr-mcp accounts` ·
|
|
24
|
+
`formstr-mcp logout` · `formstr-mcp` (run the stdio server, the default).
|
|
23
25
|
|
|
24
26
|
## Sign-in
|
|
25
27
|
|
|
26
|
-
`formstr-mcp login`
|
|
27
|
-
|
|
28
|
+
`formstr-mcp login` is fully terminal-interactive (no browser, no localhost server) and
|
|
29
|
+
offers four methods:
|
|
28
30
|
|
|
29
|
-
| Method
|
|
30
|
-
|
|
|
31
|
-
| **
|
|
32
|
-
| **
|
|
33
|
-
| **
|
|
31
|
+
| Method | What happens |
|
|
32
|
+
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
33
|
+
| **Create** (new key) | Generates a key, encrypts it with a passphrase you choose, and prints the `ncryptsec` once — **back it up**, it is the only recovery path. |
|
|
34
|
+
| **Import** (nsec/hex/ncryptsec) | Paste an `nsec…`, hex secret, or existing `ncryptsec1…`. Non-encrypted input is encrypted with your passphrase before storage. |
|
|
35
|
+
| **Bunker URI** (NIP-46) | Paste a `bunker://…` URI. Your key stays in the remote signer; only the session is stored. |
|
|
36
|
+
| **QR** (NIP-46 nostrconnect) | A `nostrconnect://` URI is rendered as a terminal QR; scan it in Amber / nsec.app / nsecbunker. |
|
|
34
37
|
|
|
35
38
|
**Where the key lives:** the OS keychain (macOS Keychain / Windows Credential Manager /
|
|
36
39
|
Linux Secret Service via `@napi-rs/keyring`). On hosts without a keychain (e.g. headless
|
|
37
40
|
Linux), set `FORMSTR_MCP_PASSPHRASE` to use an AES-256-GCM encrypted file at
|
|
38
|
-
`~/.config/formstr-mcp/
|
|
39
|
-
select one with `--account <pubkey>`.
|
|
41
|
+
`~/.config/formstr-mcp/keystore.enc` (mode `0600`). Multiple identities are supported
|
|
42
|
+
(`formstr-mcp accounts` lists them); select one at boot with `--account <pubkey>`.
|
|
43
|
+
|
|
44
|
+
**Defense in depth:** even on the encrypted-file fallback the stored key is _also_ NIP-49
|
|
45
|
+
encrypted, so recovering it needs **both** the keystore **and** the unlock passphrase.
|
|
40
46
|
|
|
41
47
|
**The agent never sees your key.** No tool returns key material, and login happens
|
|
42
48
|
out-of-band, so secrets never enter the chat transcript.
|
|
@@ -59,20 +65,25 @@ After `login`, no key belongs in the config:
|
|
|
59
65
|
Add `"--allow-writes"` to `args` to enable the gated (destructive/outward) tools, and
|
|
60
66
|
`"--relays", "wss://a,wss://b"` to override relays.
|
|
61
67
|
|
|
62
|
-
## Headless /
|
|
68
|
+
## Headless / unattended
|
|
69
|
+
|
|
70
|
+
Run `formstr-mcp login` once interactively to populate the keystore, then run the server
|
|
71
|
+
unattended. At boot the active account is unlocked headlessly:
|
|
63
72
|
|
|
64
|
-
|
|
65
|
-
|
|
73
|
+
- **ncryptsec accounts** decrypt using `FORMSTR_MCP_NCRYPTSEC_PASSPHRASE` (the passphrase
|
|
74
|
+
you set during `login`). Required for the `run` command when the active account is local.
|
|
75
|
+
- **NIP-46 accounts** reconnect from their stored session — no passphrase needed.
|
|
66
76
|
|
|
67
|
-
| Variable
|
|
68
|
-
|
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
77
|
+
| Variable | Meaning |
|
|
78
|
+
| ---------------------------------- | ----------------------------------------------------------------- |
|
|
79
|
+
| `FORMSTR_MCP_NCRYPTSEC_PASSPHRASE` | unlock the active ncryptsec account at boot |
|
|
80
|
+
| `FORMSTR_MCP_PASSPHRASE` | encrypts the at-rest keystore **file** (keychain-less hosts only) |
|
|
81
|
+
| `FORMSTR_MCP_KEYSTORE` | force `file` or `keychain` backend (optional) |
|
|
82
|
+
| `FORMSTR_MCP_CONFIG_DIR` | keystore directory (default `~/.config/formstr-mcp`) |
|
|
83
|
+
| `FORMSTR_RELAYS` | comma-separated relay override (optional) |
|
|
73
84
|
|
|
74
|
-
CLI flags: `--
|
|
75
|
-
|
|
85
|
+
CLI flags: `--relays <wss://a,wss://b>`, `--allow-writes`, `--account <pubkey>`.
|
|
86
|
+
There is no plaintext-nsec path — a raw key is never read from env, flags, or a config file.
|
|
76
87
|
|
|
77
88
|
## Forms tools
|
|
78
89
|
|