@squirrelnotes.app/mcp 2.3.0 → 2.4.0-test.362

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 CHANGED
@@ -33,11 +33,29 @@ The passphrase lives in `claude_desktop_config.json` on your machine and is pass
33
33
  | `update_note` | Updates title, content, or pinnedAt on a note. |
34
34
  | `delete_note` | Moves a note to trash (recoverable for 30 days). Its public share link is revoked at once. |
35
35
  | `pin_note` | Pins or unpins a note (appears at top of sidebar). |
36
- | `append_to_note` | Appends markdown content to an existing note. Saves the agent a get → update, but it is **not** race-free: it reads the note and writes it back whole, and the server has no version check, so an edit made elsewhere in between is overwritten. |
36
+ | `append_to_note` | Appends markdown content to an existing note. Saves the agent a get → update, but it is **not** race-free: it reads the note and writes it back whole, and the server has no version check, so an edit made elsewhere in between is overwritten. Optional `expectedUpdatedAt` refuses the write if the note changed since it was read, as on the large-note writes; the answer then also carries the new `updatedAt`. |
37
37
  | `set_note_tags` | Replaces all tags on a note. |
38
38
  | `search_notes` | Fast title-only search across all notes. |
39
- | `search_note_content` | Full-content search (slow — decrypts all notes). Use only when title search fails. |
39
+ | `search_note_content` | Full-content search (slow — decrypts all notes). Use only when title search fails. Returns `{total, notes}` with up to 5 matching lines per note (`snippets: [{line, text}]`, each cut to 240 characters) and up to `limit` notes (default 20, at most 50). `includeContent: true` returns the full content of every match instead, as an array, as it did before. |
40
40
  | `move_note_to_collection` | Moves a note to a collection (or to scratchpad if collectionId is null). |
41
+ | `get_note_outline` | A note's headings, with each section's line span and size (`chars`, `approxTokens`), the preamble before the first heading, and `updatedAt`. No body text. At most 500 headings (`omitted` counts the rest). |
42
+ | `read_note` | One section by `heading` (+ `occurrence` when the text repeats), or `startLine`/`endLine`. Numbered lines, at most 400 lines or 20,000 characters per call; `truncated` and `nextStartLine` say how to continue. |
43
+ | `edit_note` | Replaces the one exact occurrence of `oldText` with `newText`. Zero or several matches write nothing. Everything outside the match, line endings included, is kept. With `heading` (+ `occurrence`), only matches lying wholly inside that heading's section count, so text that repeats elsewhere can still be changed in one place. |
44
+ | `replace_section` | Replaces everything under a heading, subsections included; the heading line stays. |
45
+ | `insert_in_section` | Adds lines under a heading: `position: "start"` (at the start of the heading's text, after the blank line under the heading) or `"end"` (after the heading's own text, before its first subheading). |
46
+ | `delete_section` | Deletes a heading and everything under it, subsections included, leaving the note spaced as if the section had never been there. |
47
+ | `insert_at_line` | Inserts lines before a 1-based line (`totalLines + 1` appends). `expectedUpdatedAt` is required, because line numbers go stale; a line out of range is refused with `minLine` and `maxLine`. |
48
+
49
+ #### Large notes
50
+
51
+ For a note over about 8,000 characters (about 2,000 tokens), an agent should not read or rewrite the whole note. `get_note_outline` lists the headings with their line numbers and sizes, `read_note` reads one section or a range of lines, and `edit_note`, `replace_section`, `insert_in_section`, `delete_section` and `insert_at_line` change only what they name. Each call is one `GET /public/notes/:id` (and, for a write, one `PATCH` of the encrypted content, as `append_to_note` sends); the note is decrypted, changed and encrypted on your machine.
52
+
53
+ - **Lines** are 1-based and `endLine` is inclusive. A `\r\n` line break counts as one break and is never shown; a lone `\r` is an ordinary character. When every line break in a note is `\r\n`, the text a write adds uses `\r\n` too; otherwise `\n`.
54
+ - **Headings** are exactly the ones the app's Outline panel shows: `#` to `######` headings, none inside fenced code, setext (underlined) headings not counted. Two quirks are kept so the two agree: a trailing `#` with no space before it is dropped (`## C#` reads as `C`), and in a note with `\r\n` line endings a fenced code block is not recognised, so a `#` line inside one is listed.
55
+ - **`edit_note` matches exactly**: case, spaces, accents, Unicode form and line breaks all count, and overlapping matches count (`aa` occurs twice in `aaa`). When the text repeats, widen `oldText` or pass `heading` to look only in that section (subsections included); there is no "replace the Nth match", because a position goes stale like a line number.
56
+ - **Spacing.** `replace_section` and `insert_in_section` keep the blank lines after a heading and before the next heading as the note has them, so repeated edits do not wear a note's spacing down, and writing a section's own body back changes nothing. A section with no lines at all gets the note's usual spacing (one blank line on each side unless most of its headings are followed directly by text). The content's own leading and trailing blank lines are dropped. An insert next to a list continues the list when it is a list item, and is separated from it by one blank line when it is text, so neither joins the other. `delete_section` leaves the spacing the note would have had without the section. `insert_at_line` adds or removes no blank line, except one to keep a heading's own blank line above or below it.
57
+ - **`expectedUpdatedAt`** (optional on every write, required on `insert_at_line`): pass the `updatedAt` from your last read or write. If the note's differs, nothing is written and the answer is `{error: "stale", updatedAt}`. It is checked by the MCP between its read and its write, so it is not a lock, and a pin, tag or move also changes `updatedAt`, so it refuses after those too: read again and retry.
58
+ - **Refusals** carry a code, a fixed sentence and numbers only (counts, line numbers, `updatedAt`), never note text or what you passed. Nothing is logged.
41
59
 
42
60
  ### Trash
43
61
 
@@ -250,7 +268,8 @@ MCP does not (R-038).
250
268
  new entries later, start `since` a little before the last `at` you read (a
251
269
  minute, say) rather than resuming from a saved cursor, and skip the entries
252
270
  you already have. The server also limits history reads to 60 a minute per
253
- 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).
254
273
  History entries are never returned as memories: `search_memory` and the
255
274
  profile never read them, and no tool writes, changes or deletes them. With
256
275
  `entity`, a call makes at most five requests, so fewer than `limit` entries
@@ -286,8 +305,9 @@ MCP does not (R-038).
286
305
  ones missing, so call again with a later `since`. If the history cannot be
287
306
  read (a network error, a server without the history route, a 5xx),
288
307
  `available` is `false` with a fixed note and the rest of the briefing is
289
- still returned; a rejected key (401) or an account no longer Pro fails the
290
- 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
291
311
  cache, and logs one line of counts (no text, entity, tag, `since`, id, key
292
312
  prefix or reason).
293
313
  - **Agents cannot delete or pin memories.** No tool sends a `DELETE`, and
@@ -473,6 +493,10 @@ Quit and reopen Claude Desktop. The Squirrel Notes MCP server will start automat
473
493
 
474
494
  Ask Claude: *"List my Squirrel Notes"* — you should see your note titles.
475
495
 
496
+ **4. Recommended: install the agent skill**
497
+
498
+ Recommended: give your agent the **Squirrel Notes skill** from [github.com/squirrel-notes/skills](https://github.com/squirrel-notes/skills). It teaches the agent to start each session with `get_context`, search before answering (with a near-miss retry), save memories that will be found again, and correct them without losing history. In Claude Code, copy `skills/squirrel-notes` into `~/.claude/skills/`; the repository's README covers other agents.
499
+
476
500
  #### Option B — build from source (local development / pinned version)
477
501
 
478
502
  Use this if you want to run a specific local build or contribute to the server code.
@@ -517,6 +541,7 @@ Once configured, you can speak to Claude naturally. Some examples:
517
541
  | *"Search my notes for 'project roadmap'"* | `search_notes` (title match) or `search_note_content` |
518
542
  | *"Create a note called 'Meeting Notes' in my Work collection"* | `list_collections` → `create_note(collectionId: ...)` |
519
543
  | *"Add today's standup to my Daily Log note"* | `search_notes("Daily Log")` → `append_to_note(id, ...)` |
544
+ | *"Fix the install command in my Setup guide"* | `search_notes("Setup guide")` → `get_note_outline` → `read_note(heading: "Install")` → `edit_note(oldText, newText, expectedUpdatedAt)` |
520
545
  | *"Pin my TODO note"* | `search_notes("TODO")` → `pin_note(id, true)` |
521
546
  | *"Tag my 'Project Roadmap' note as urgent"* | `list_tags` → `search_notes` → `set_note_tags` |
522
547
  | *"Show me all my pinned notes"* | `list_notes(pinned: true)` |
@@ -658,6 +683,51 @@ The attachment upload's storage PUT goes to the upload URL the API returns, not
658
683
 
659
684
  ---
660
685
 
686
+ ## Monthly API calls
687
+
688
+ Squirrel Notes counts the calls each account makes to the public API with its
689
+ API key (feature 0067, proposal 0089). Every request this server sends with
690
+ `SQUIRREL_API_KEY` counts as one call, so each tool call that reaches the API
691
+ counts at least one: the first tool call of a process also fetches the
692
+ encryption settings (one call), a note edit reads and then writes (two), and a
693
+ memory search inside the 60 s list cache sends nothing. A request the key
694
+ guard refuses (401, or 403 for an account that is not Pro) is not counted.
695
+
696
+ - **The limit.** Pro includes 5,000 calls a calendar month, counted per
697
+ account, all keys together.
698
+ - **The reset.** The month is the UTC calendar month: the count starts again
699
+ at 00:00 UTC on the 1st. The app shows the month's usage above Storage in
700
+ the library panel and in Settings → API & Data.
701
+ - **Not enforced yet.** The first release counts and shows usage and refuses
702
+ no call. The handling below ships now so this server already reads the
703
+ refusal correctly when the limit is switched on.
704
+ - **Once it is enforced**, a call over the limit gets HTTP 429 with a
705
+ `Retry-After` header and the body
706
+ `{ "statusCode": 429, "error": "Too Many Requests", "message": "Monthly API call limit reached", "limit": 5000, "resetsAt": "2026-11-01T00:00:00.000Z" }`.
707
+ This server matches the message exactly (any other 429 is the per-minute
708
+ limit) and then:
709
+ - **memory tools** (`get_context` and `memory_history` included) answer
710
+ with a fixed text: "This account has used its 5,000 monthly API calls.
711
+ Nothing more was written. Calls resume on 2026-11-01 (UTC); the user can
712
+ see usage in the Squirrel Notes app." The limit and the day are quoted
713
+ only when they have the expected shape (a whole number of 0 or more; an ISO instant of
714
+ at most 40 characters, named as its UTC day); otherwise the text says "its
715
+ monthly API calls" and "Calls resume at 00:00 UTC on the 1st of next
716
+ month". Nothing else from the response is quoted. `get_context` fails
717
+ rather than returning the briefing with `changes` unavailable;
718
+ - **note and other tools** fail with the API's error as before
719
+ (`Squirrel API GET /public/notes/… → 429: {…}`), which carries the
720
+ message above;
721
+ - **the key is kept**: a 429 never drops the held data key, so the next
722
+ call, once calls resume, needs no new key fetch. A refused call is never
723
+ retried.
724
+
725
+ Older versions of this server show "Too many requests in the last minute …
726
+ Wait a minute" for this refusal. That text is wrong about the wait, but
727
+ nothing is written or dropped.
728
+
729
+ ---
730
+
661
731
  ## Environment Variables
662
732
 
663
733
  | Variable | Required | Description |