@squirrelnotes.app/mcp 2.4.0 → 2.5.0-test.369

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 (3) hide show
  1. package/README.md +70 -16
  2. package/dist/stdio-handler.js +19404 -3413
  3. package/package.json +4 -2
package/README.md CHANGED
@@ -268,7 +268,8 @@ MCP does not (R-038).
268
268
  new entries later, start `since` a little before the last `at` you read (a
269
269
  minute, say) rather than resuming from a saved cursor, and skip the entries
270
270
  you already have. The server also limits history reads to 60 a minute per
271
- account (per server container), answered with a 429.
271
+ account (per server container), answered with a 429; the monthly API call
272
+ limit's 429 gets its own text (see "Monthly API calls" below).
272
273
  History entries are never returned as memories: `search_memory` and the
273
274
  profile never read them, and no tool writes, changes or deletes them. With
274
275
  `entity`, a call makes at most five requests, so fewer than `limit` entries
@@ -304,8 +305,9 @@ MCP does not (R-038).
304
305
  ones missing, so call again with a later `since`. If the history cannot be
305
306
  read (a network error, a server without the history route, a 5xx),
306
307
  `available` is `false` with a fixed note and the rest of the briefing is
307
- still returned; a rejected key (401) or an account no longer Pro fails the
308
- call, as every memory tool does. It writes nothing, uses the 60 s list
308
+ still returned; a rejected key (401), an account no longer Pro, or the
309
+ monthly API call limit (see "Monthly API calls" below) fails the call, as
310
+ every memory tool does. It writes nothing, uses the 60 s list
309
311
  cache, and logs one line of counts (no text, entity, tag, `since`, id, key
310
312
  prefix or reason).
311
313
  - **Agents cannot delete or pin memories.** No tool sends a `DELETE`, and
@@ -395,7 +397,15 @@ Claude generates content
395
397
 
396
398
  ### Claude Desktop configuration
397
399
 
398
- Add both servers to `claude_desktop_config.json`:
400
+ First create the upload folder, private to you. It must exist before the Filesystem server starts (that server exits if its folder is missing):
401
+
402
+ ```sh
403
+ mkdir -m 700 ~/SquirrelUploads # or, if it already exists: chmod 700 ~/SquirrelUploads
404
+ ```
405
+
406
+ On Windows, just create `SquirrelUploads` in your user folder. Whenever the Squirrel MCP server starts with local file access and the default root, it also creates an empty `~/SquirrelUploads` (0700) if it is missing (Gareth, 2026-10-30: "Create at start"), so the folder appears in your home folder and exists from the second start even if this step is skipped.
407
+
408
+ Then add both servers to `claude_desktop_config.json`:
399
409
 
400
410
  ```json
401
411
  {
@@ -406,46 +416,45 @@ Add both servers to `claude_desktop_config.json`:
406
416
  "env": {
407
417
  "SQUIRREL_API_BASE_URL": "https://api.squirrelnotes.app",
408
418
  "SQUIRREL_API_KEY": "sqn_your_api_key",
409
- "SQUIRREL_PASSPHRASE": "your-passphrase",
410
- "SQUIRREL_UPLOAD_ROOT": "/tmp"
419
+ "SQUIRREL_PASSPHRASE": "your-passphrase"
411
420
  }
412
421
  },
413
422
  "filesystem": {
414
423
  "command": "npx",
415
- "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
424
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/SquirrelUploads"],
416
425
  "env": {}
417
426
  }
418
427
  }
419
428
  }
420
429
  ```
421
430
 
422
- > **`SQUIRREL_UPLOAD_ROOT`** restricts which directories `upload_attachment_from_path` may read from. Defaults to `os.tmpdir()` — `/tmp` on macOS/Linux, `%TEMP%` equivalent on Windows. Set to a comma-separated list for multiple allowed roots (e.g. `"/tmp,/Users/you/Downloads"`). This is a security guardrail — without it, a prompt-injection attack could trick Claude into uploading files from anywhere on disk (e.g. `~/.ssh/id_rsa`). Note: symlinks inside an allowed root that point outside it are not followed during the check — use OS-level controls if that is a concern.
431
+ > **`SQUIRREL_UPLOAD_ROOT`** restricts which directories `upload_attachment_from_path` may read from. **Unset, it is `~/SquirrelUploads`** (in your home folder: `/Users/you/SquirrelUploads` on macOS, `/home/you/SquirrelUploads` on Linux, `C:\Users\you\SquirrelUploads` on Windows, written `C:\\Users\\you\\SquirrelUploads` or `C:/Users/you/SquirrelUploads` in JSON), never the temp folder; the example above leaves it unset and points the Filesystem server at that folder. The server creates the folder (mode 0700) when it starts and again on first use if it is missing, and that is the only thing this tool ever writes. Before each upload, on macOS and Linux, it checks the folder is still private: it is refused if it is a symlink, not a folder, owned by someone else, or has any group or other permission, or if any folder above it is owned by someone other than you or root, or writable by others without the sticky bit (as `/tmp` has). A refused folder gets its own message saying what is wrong and how to fix it (for example `run chmod 700 ~/SquirrelUploads`), which names only that folder; one line on stderr says the same, never which file. At start-up the same check runs once and only reports. Access control lists are not checked (macOS and the BSDs); on Linux a POSIX ACL shows in the group bits, which are checked. The read is then held to the folder's checked real path, so swapping a folder above it for a link cannot move it. On Windows only the symlink and folder checks run: the folder gets your profile folder's permissions, unchecked beyond that, and mode 0700 has no effect there. The Windows behaviour has never been run on a real Windows host. To use other folders, set it to a comma-separated list (e.g. `"/Users/you/SquirrelUploads,/Users/you/Downloads"`). Entries are full paths (`~` is not expanded in them). **On macOS and Linux a folder you set is refused** (Gareth, 2026-10-30: "Refuse it") if group or others can write it, sticky or not (so `/tmp` is refused), or it is owned by someone other than you or root; it is judged by `stat`, so a link you set by the folder it leads to. An upload under a refused entry gets `Error: upload folder entry N in SQUIRREL_UPLOAD_ROOT can be written by other users, so it is not used. Use ~/SquirrelUploads instead: remove the setting, or set it to a folder only you can write.` (or "is owned by someone other than you or root"), naming only its position; the server also says so once on stderr at start; entries that pass are still used. A folder you set gets only these checks, not the default folder's (a group-readable folder of yours is accepted; listing the default folder's full path, `/Users/you/SquirrelUploads`, there leaves it with only these). On Windows a folder you set is not checked. So pick folders only you can write, on every platform, and never `/tmp` or another shared folder. If you set `/tmp` for an earlier version, uploads are now refused: remove it and point your Filesystem server at `~/SquirrelUploads`. The path asked for may start with `~/`, which means your home folder, as the Filesystem server reads it; `~user/` is not expanded. This is a security guardrail: without it, a prompt-injection attack could trick Claude into uploading files from anywhere on disk (e.g. `~/.ssh/id_rsa`). Empty entries are ignored, and a setting with none left (or an empty one) means the default. The check is on where the file really is: a symlink (or a symlinked folder) inside an allowed root that leads outside every root is refused, whether or not its target exists, and the file read is the one checked. A link that stays inside a root, or leads into another listed root, is read. A file with more than one hard link is refused, since its other names may be outside every root: copy it into the root instead. Only a regular file of at most 10 MB is read. On Linux the opened file is confirmed by the kernel's own name for it, so a link swapped in during the check is refused. On every other platform the confirmation is by path: in a folder another user can write, a process that swaps a folder for a link at the right moments can still win. On every platform, someone who can put a link in the folder can also learn whether a folder of yours exists, from whether that link is read. Both need a folder someone else can write: a folder you set that others can write, or a default folder whose permissions the checks above miss (on Windows, they check none) (accepted risk R-204).
423
432
 
424
433
  ### Example workflows
425
434
 
426
435
  **Attach a Claude-generated CSV report to a note:**
427
436
  > "Create a monthly expense summary as a CSV and attach it to my Finances note."
428
437
 
429
- 1. Claude generates the CSV content → `write_file("/tmp/expenses.csv", content)` (Filesystem MCP)
430
- 2. Claude calls `upload_attachment_from_path` with `localPath="/tmp/expenses.csv"` (Squirrel MCP)
438
+ 1. Claude generates the CSV content → `write_file("/Users/you/SquirrelUploads/expenses.csv", content)` (Filesystem MCP)
439
+ 2. Claude calls `upload_attachment_from_path` with `localPath="/Users/you/SquirrelUploads/expenses.csv"` (Squirrel MCP)
431
440
 
432
441
  **Attach an xlsx file generated by a script:**
433
442
  > "Write a Python script to generate an xlsx report and attach it to my Analytics note."
434
443
 
435
- 1. Claude writes the script to `/tmp/generate_report.py` → executes it → `report.xlsx` is written to `/tmp/`
436
- 2. Claude calls `upload_attachment_from_path` with `localPath="/tmp/report.xlsx"`
444
+ 1. Claude writes the script to `/Users/you/SquirrelUploads/generate_report.py` → executes it → `report.xlsx` is written to `/Users/you/SquirrelUploads/`
445
+ 2. Claude calls `upload_attachment_from_path` with `localPath="/Users/you/SquirrelUploads/report.xlsx"`
437
446
 
438
447
  **Bulk-import Markdown files from disk:**
439
- > "Import all the markdown files from /tmp/obsidian-export/ as notes in my Archive collection."
448
+ > "Import all the markdown files from ~/SquirrelUploads/obsidian-export/ as notes in my Archive collection."
440
449
 
441
- 1. Claude calls `list_directory("/tmp/obsidian-export/")` (Filesystem MCP) to enumerate files
450
+ 1. Claude calls `list_directory("/Users/you/SquirrelUploads/obsidian-export/")` (Filesystem MCP) to enumerate files
442
451
  2. For each `.md` file: `read_file(path)` → `create_note` with the content (Squirrel MCP)
443
452
 
444
453
  **Export a note to disk:**
445
- > "Export my project roadmap note as a Markdown file to /tmp/roadmap.md."
454
+ > "Export my project roadmap note as a Markdown file to ~/SquirrelUploads/roadmap.md."
446
455
 
447
456
  1. Claude calls `get_note(id)` (Squirrel MCP) to read the note
448
- 2. Claude calls `write_file("/tmp/roadmap.md", content)` (Filesystem MCP)
457
+ 2. Claude calls `write_file("/Users/you/SquirrelUploads/roadmap.md", content)` (Filesystem MCP)
449
458
 
450
459
  The server needs an API key and your passphrase, both set as env vars in your client's config (see Setup). The API key is sent to the Squirrel Notes API in the `Authorization` header; the passphrase is never sent anywhere.
451
460
 
@@ -681,6 +690,51 @@ The attachment upload's storage PUT goes to the upload URL the API returns, not
681
690
 
682
691
  ---
683
692
 
693
+ ## Monthly API calls
694
+
695
+ Squirrel Notes counts the calls each account makes to the public API with its
696
+ API key (feature 0067, proposal 0089). Every request this server sends with
697
+ `SQUIRREL_API_KEY` counts as one call, so each tool call that reaches the API
698
+ counts at least one: the first tool call of a process also fetches the
699
+ encryption settings (one call), a note edit reads and then writes (two), and a
700
+ memory search inside the 60 s list cache sends nothing. A request the key
701
+ guard refuses (401, or 403 for an account that is not Pro) is not counted.
702
+
703
+ - **The limit.** Pro includes 5,000 calls a calendar month, counted per
704
+ account, all keys together.
705
+ - **The reset.** The month is the UTC calendar month: the count starts again
706
+ at 00:00 UTC on the 1st. The app shows the month's usage above Storage in
707
+ the library panel and in Settings → API & Data.
708
+ - **Not enforced yet.** The first release counts and shows usage and refuses
709
+ no call. The handling below ships now so this server already reads the
710
+ refusal correctly when the limit is switched on.
711
+ - **Once it is enforced**, a call over the limit gets HTTP 429 with a
712
+ `Retry-After` header and the body
713
+ `{ "statusCode": 429, "error": "Too Many Requests", "message": "Monthly API call limit reached", "limit": 5000, "resetsAt": "2026-11-01T00:00:00.000Z" }`.
714
+ This server matches the message exactly (any other 429 is the per-minute
715
+ limit) and then:
716
+ - **memory tools** (`get_context` and `memory_history` included) answer
717
+ with a fixed text: "This account has used its 5,000 monthly API calls.
718
+ Nothing more was written. Calls resume on 2026-11-01 (UTC); the user can
719
+ see usage in the Squirrel Notes app." The limit and the day are quoted
720
+ only when they have the expected shape (a whole number of 0 or more; an ISO instant of
721
+ at most 40 characters, named as its UTC day); otherwise the text says "its
722
+ monthly API calls" and "Calls resume at 00:00 UTC on the 1st of next
723
+ month". Nothing else from the response is quoted. `get_context` fails
724
+ rather than returning the briefing with `changes` unavailable;
725
+ - **note and other tools** fail with the API's error as before
726
+ (`Squirrel API GET /public/notes/… → 429: {…}`), which carries the
727
+ message above;
728
+ - **the key is kept**: a 429 never drops the held data key, so the next
729
+ call, once calls resume, needs no new key fetch. A refused call is never
730
+ retried.
731
+
732
+ Older versions of this server show "Too many requests in the last minute …
733
+ Wait a minute" for this refusal. That text is wrong about the wait, but
734
+ nothing is written or dropped.
735
+
736
+ ---
737
+
684
738
  ## Environment Variables
685
739
 
686
740
  | Variable | Required | Description |