@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.
- package/README.md +70 -16
- package/dist/stdio-handler.js +19404 -3413
- 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)
|
|
308
|
-
|
|
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
|
-
|
|
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", "/
|
|
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.
|
|
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("/
|
|
430
|
-
2. Claude calls `upload_attachment_from_path` with `localPath="/
|
|
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 `/
|
|
436
|
-
2. Claude calls `upload_attachment_from_path` with `localPath="/
|
|
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 /
|
|
448
|
+
> "Import all the markdown files from ~/SquirrelUploads/obsidian-export/ as notes in my Archive collection."
|
|
440
449
|
|
|
441
|
-
1. Claude calls `list_directory("/
|
|
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 /
|
|
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("/
|
|
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 |
|