keepsake-mcp 1.5.0 → 1.7.0

package/README.md

@@ -100,7 +100,7 @@ Add to `.cursor/mcp.json` in your project:
 }
 ```
 
-## Available tools (62)
+## Available tools (67)
 
 ### Contacts
 | Tool | Description |
@@ -148,6 +148,7 @@ Add to `.cursor/mcp.json` in your project:
 | Tool | Description |
 |------|-------------|
 | `list_notes` | List notes (filter by pinned/archived) |
+| `get_note` | Get one note by ID with its tags, contacts, tasks and linked notes |
 | `create_note` | Create a note — supports `#tag#` and `[[tag]]` syntax |
 | `update_note` | Update note content |
 | `delete_note` | Soft-delete (or permanent) |
@@ -155,6 +156,17 @@ Add to `.cursor/mcp.json` in your project:
 | `archive_note` | Archive a note |
 | `restore_note` | Restore a deleted/archived note |
 
+### Note comments (marginalia)
+
+Material kept *alongside* a note without entering its text — an idea, a reference, an excerpt pasted to rewrite a passage later. Anchored to a passage by quoting it, or to the whole note. Never published, and temporary by design: anything worth keeping becomes a note or a linked task.
+
+| Tool | Description |
+|------|-------------|
+| `list_note_comments` | List the marginalia attached to a note |
+| `create_note_comment` | Attach a marginalia to a passage (pass `quote`) or to the whole note |
+| `update_note_comment` | Edit the content of a marginalia |
+| `delete_note_comment` | Permanently delete a marginalia |
+
 ### Daily Journal
 | Tool | Description |
 |------|-------------|

package/build/tools.js

@@ -380,6 +380,15 @@ export function registerAllTools(server, fetchApi) {
     }, async ({ pinned, archived, limit, offset }) => {
         return toContent(await fetchApi(`/notes${qs({ pinned, archived, limit, offset })}`));
     });
+    server.registerTool("get_note", {
+        description: "Get a single note by ID, including its tags, linked contacts, linked tasks and linked notes. Use this when the user points you at one specific note (e.g. gives you its URL — the UUID is the last path segment) instead of listing everything.",
+        inputSchema: {
+            id: z.string().uuid().describe("Note UUID (last segment of the note URL)"),
+        },
+        annotations: { title: "Get note", readOnlyHint: true, openWorldHint: false },
+    }, async ({ id }) => {
+        return toContent(await fetchApi(`/notes/${id}`));
+    });
     server.registerTool("create_note", {
         description: "Create a new QuickNote in the Inbox. QuickNotes are temporary captures — use archive_note to transform one into a permanent Note.\n\nContent supports #tag# and [[tag]] for automatic tag linking.",
         inputSchema: {
@@ -814,6 +823,68 @@ export function registerAllTools(server, fetchApi) {
         return toContent(await fetchApi(`/search${qs({ q, type, limit })}`));
     });
     // ---------------------------------------------------------------------------
+    // Note comments (marginalia)
+    // ---------------------------------------------------------------------------
+    server.registerTool("list_note_comments", {
+        description: "List the marginalia attached to a note. A marginalia is working material the user keeps ALONGSIDE a note without it entering the text: an idea, a reference, a link, an excerpt pasted to rewrite a passage later. They are never published, and they are meant to be TEMPORARY — anything worth keeping becomes a note or a linked task.\n\nEach one is either attached to a specific passage (`quote` is set) or to the whole note (`quote` is null).",
+        inputSchema: {
+            note_id: z.string().uuid().describe("Note UUID"),
+        },
+        annotations: { title: "List note comments", readOnlyHint: true, openWorldHint: false },
+    }, async ({ note_id }) => {
+        return toContent(await fetchApi(`/notes/${note_id}/comments`));
+    });
+    server.registerTool("create_note_comment", {
+        description: "Attach a marginalia to a note — material that must stay OUT of the note text.\n\nTo attach it to a passage, pass `quote` with that passage copied VERBATIM from the note content; the server locates it and stores the surrounding context so the comment survives later edits. Omit `quote` to comment on the note as a whole. If the quote is not found verbatim the call is refused rather than attached to the wrong place.\n\nDo not use this to suggest edits to the text — use update_note for that. And keep the number of comments low: a note peppered with them is a note the user abandons.",
+        inputSchema: {
+            note_id: z.string().uuid().describe("Note UUID"),
+            body: z.string().describe("The material itself (markdown, any length)"),
+            quote: z
+                .string()
+                .optional()
+                .describe("Passage to attach to, copied verbatim from the note content. Omit for a note-wide comment."),
+        },
+        annotations: {
+            title: "Create note comment",
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ note_id, ...params }) => {
+        return toContent(await fetchApi(`/notes/${note_id}/comments`, "POST", params));
+    });
+    server.registerTool("update_note_comment", {
+        description: "Edit the content of a marginalia. There is no intermediate state: a marginalia exists, or it is deleted. A remark that should outlive the note's revision becomes a note or a linked task instead.",
+        inputSchema: {
+            note_id: z.string().uuid().describe("Note UUID"),
+            comment_id: z.string().uuid().describe("Comment UUID"),
+            body: z.string().describe("New content (markdown)"),
+        },
+        annotations: {
+            title: "Update note comment",
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ note_id, comment_id, ...params }) => {
+        return toContent(await fetchApi(`/notes/${note_id}/comments/${comment_id}`, "PATCH", params));
+    });
+    server.registerTool("delete_note_comment", {
+        description: "Delete a marginalia. Marginalia are temporary by design, so this is the normal way to retire one — there is no recoverable middle state.",
+        inputSchema: {
+            note_id: z.string().uuid().describe("Note UUID"),
+            comment_id: z.string().uuid().describe("Comment UUID"),
+        },
+        annotations: {
+            title: "Delete note comment",
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ note_id, comment_id }) => {
+        return toContent(await fetchApi(`/notes/${note_id}/comments/${comment_id}`, "DELETE"));
+    });
+    // ---------------------------------------------------------------------------
     // Agent instructions
     // ---------------------------------------------------------------------------
     server.registerTool("get_agent_instructions", {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "keepsake-mcp",
-  "version": "1.5.0",
-  "description": "MCP server for Keepsake personal CRM — connect your AI agent to your contacts, tasks, notes, and more",
+  "version": "1.7.0",
+  "description": "MCP server for Keepsake personal CRM \u2014 connect your AI agent to your contacts, tasks, notes, and more",
   "type": "module",
   "bin": {
     "keepsake-mcp": "build/index.js"