@longbook/mcp 0.0.0-stage → 1.40.3

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.
Files changed (5) hide show
  1. package/LICENSE +674 -0
  2. package/README.md +150 -2
  3. package/bin/longbook-mcp.mjs +6810 -0
  4. package/package.json +51 -4
  5. package/server.json +47 -0
package/README.md CHANGED
@@ -1,3 +1,151 @@
1
- # Temporary Holding Version
1
+ # longbook MCP server
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Your financial memory, readable by the AI you already use. longbook keeps every
4
+ recurring commitment — subscriptions, insurance, EMIs, rent, fees — as a plain folder
5
+ of files you own. This MCP server lets any AI answer from that memory with real
6
+ arithmetic: next payment day, upcoming charges, cash flow, spending by tag, account,
7
+ or member. Amounts are per-currency and never converted or blended.
8
+
9
+ There are two ways to connect. Both serve the same tools from the same engine.
10
+
11
+ ## The hosted server (works with any AI, no install)
12
+
13
+ Address: `https://longbook.app/mcp`
14
+
15
+ Sign-in happens in your browser through OAuth; the server reads the hosted copy of
16
+ your memory, which you switch on inside the longbook app (Settings → MCP server).
17
+ A signed-in AI reads. It can also *suggest* changes once you turn on "Let signed-in
18
+ AIs suggest changes" in the app — suggestions wait for your app and land in its
19
+ Changes screen, to keep or undo as one batch. Nothing in the cloud ever edits your
20
+ memory itself. Disconnecting an AI or turning the switch off takes effect immediately.
21
+
22
+ The simplest setup: copy the connect prompt from the app or from
23
+ [longbook.app/mcp](https://longbook.app/mcp) and paste it into your AI.
24
+
25
+ | Client | Where to add it |
26
+ |---|---|
27
+ | Claude (web, desktop, mobile) | Settings → Connectors → Add custom connector → paste the address |
28
+ | ChatGPT | Settings → Connectors → Advanced → Developer mode → add MCP server |
29
+ | Grok | Settings → Connectors → add remote MCP server |
30
+ | Anything else that speaks remote MCP | Point it at the address; OAuth does the rest |
31
+
32
+ Clients that cannot open a browser — schedulers, CLIs — use an access key from the
33
+ app instead (Settings → MCP server → Access keys) as a bearer token. A key made with
34
+ "Read and suggest changes" can file suggestions the same way. On a Mac, save the key
35
+ to the keychain when it is shown; an agent then reads it without a file:
36
+
37
+ ```bash
38
+ security find-generic-password -s "longbook access key" -w
39
+ ```
40
+
41
+ Hand it to a connector config through the environment (`"Authorization": "Bearer
42
+ ${LONGBOOK_KEY}"`), never by pasting the key into a file.
43
+
44
+ ## The local server (reads the folder directly)
45
+
46
+ ```bash
47
+ npx -y @longbook/mcp@latest --vault "/path/to/your/longbook folder"
48
+ ```
49
+
50
+ `@latest` makes npx fetch the newest release each time instead of reusing an older copy
51
+ it kept. It needs Node 18 or later.
52
+
53
+ Without `--vault` (or the `LONGBOOK_VAULT_PATH` environment variable) it looks in
54
+ the iCloud Drive folder the longbook app uses on a Mac. On Windows and Linux, name your
55
+ longbook folder with `--vault`. The local server reads your files
56
+ directly — no account, no network — reads the bank statements in your documents
57
+ folder (PDF, .xlsx, CSV), reads the reports longbook drew into your `reports/` folder with
58
+ their comments, and carries the write tools: adding and changing commitments, charges, accounts, people
59
+ and tags, marking paid, promoting to recurring and leaving an insight. Every write is schema-validated, scanned by
60
+ the data policy, stamped with provenance, and lands in the app's Changes screen for
61
+ you to keep or undo.
62
+
63
+ ### Claude Desktop
64
+
65
+ The Mac app writes this for you in one click (Settings → MCP server). By hand:
66
+
67
+ ```json
68
+ {
69
+ "mcpServers": {
70
+ "longbook": { "command": "npx", "args": ["-y", "@longbook/mcp@latest"] }
71
+ }
72
+ }
73
+ ```
74
+
75
+ ### Cursor
76
+
77
+ Add to `~/.cursor/mcp.json` with the same JSON as above, or use the one-click link:
78
+
79
+ [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=longbook&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBsb25nYm9vay9tY3BAbGF0ZXN0Il19)
80
+
81
+ ### VS Code and GitHub Copilot
82
+
83
+ Add to `.vscode/mcp.json` (or user settings):
84
+
85
+ ```json
86
+ {
87
+ "servers": {
88
+ "longbook": { "command": "npx", "args": ["-y", "@longbook/mcp@latest"] }
89
+ }
90
+ }
91
+ ```
92
+
93
+ ### Codex CLI
94
+
95
+ Add to `~/.codex/config.toml`:
96
+
97
+ ```toml
98
+ [mcp_servers.longbook]
99
+ command = "npx"
100
+ args = ["-y", "@longbook/mcp@latest"]
101
+ ```
102
+
103
+ ### Gemini CLI
104
+
105
+ Add to `~/.gemini/settings.json`:
106
+
107
+ ```json
108
+ {
109
+ "mcpServers": {
110
+ "longbook": { "command": "npx", "args": ["-y", "@longbook/mcp@latest"] }
111
+ }
112
+ }
113
+ ```
114
+
115
+ ## What the tools return
116
+
117
+ Fourteen read tools (next payment, upcoming, charges, cash flow, spending by tag, account
118
+ and member, the commitment list, search, accounts, members, tags, whoami and the guide),
119
+ every number computed by the engine the apps themselves trust. The vault's own `llms.txt` and JSON Schema travel with the
120
+ connection as resources, and four self-contained HTML cards render the answers.
121
+ All read tools declare `readOnlyHint`; nothing here can change your files except
122
+ the two review-gated local write tools described above.
123
+
124
+ ## More about longbook
125
+
126
+ - [longbook.app](https://longbook.app/): the app for Mac and iPhone
127
+ - [This package on longbook.app](https://longbook.app/features/longbook-npm-package/)
128
+ - [Every feature](https://longbook.app/features/) and [automations with your AI](https://longbook.app/automations/)
129
+ - [Automate longbook with Claude](https://longbook.app/features/automate-longbook-with-claude/)
130
+ - [Review every change your AI makes](https://longbook.app/features/review-every-change-your-ai-makes/)
131
+ - [Get insights about your expenses from your AI](https://longbook.app/features/get-insights-about-your-expenses-from-your-ai/)
132
+ - [Import your bank statements](https://longbook.app/features/import-your-bank-statements/)
133
+ - [Why we built longbook](https://longbook.app/why-we-built-longbook/) and the [FAQ](https://longbook.app/faq/)
134
+
135
+ ## Privacy
136
+
137
+ The memory's format cannot hold card numbers, CVVs, expiries, PINs, or credentials —
138
+ there is no field for them, and a save containing one is refused. The privacy policy
139
+ is at [longbook.app/privacy-policy](https://longbook.app/privacy-policy/).
140
+
141
+ ## License
142
+
143
+ GPL-3.0-only. longbook itself is a paid app ($38 one-time, 3-day free trial);
144
+ this server is free software either way.
145
+
146
+ ## Versions
147
+
148
+ The server reports its version to every AI that connects: `1.<rulebook revision>.<patch>`,
149
+ the same number as this package, its MCP registry entry and the longbook plugin for Claude.
150
+ The rulebook is longbook's `llms.txt` and the files beside it; its revision says which
151
+ version of them the server speaks.