keepsake-mcp 1.4.0 → 1.6.0

package/README.md

@@ -100,7 +100,7 @@ Add to `.cursor/mcp.json` in your project:
 }
 ```
 
-## Available tools (62)
+## Available tools (63)
 
 ### 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) |
@@ -165,12 +166,12 @@ Add to `.cursor/mcp.json` in your project:
 ### Tags
 | Tool | Description |
 |------|-------------|
-| `list_tags` | List all tags |
-| `get_tag` | Get a tag by ID with all properties (color, icon, view mode, etc.) |
+| `list_tags` | List tags (lightweight — ordering arrays omitted), with optional name search (`q`) |
+| `get_tag` | Get a tag by ID with all properties, including `tasks_order` (section markers `h:<header_id>`) |
 | `create_tag` | Create a new tag |
 | `update_tag` | Update a tag (name, description, color, icon, view mode, favorite) |
 | `delete_tag` | Permanently delete a tag and all its links |
-| `get_tag_items` | Get everything linked to a tag |
+| `get_tag_items` | Get items linked to a tag — filter by `types`/`status`, `summary` mode, task `sections` included |
 | `link_tag` | Link any entity to a tag |
 | `unlink_tag` | Remove a tag link |
 

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: {
@@ -488,17 +497,18 @@ export function registerAllTools(server, fetchApi) {
     // TAGS
     // ===========================================================================
     server.registerTool("list_tags", {
-        description: "List all tags. Tags organize contacts, entries, tasks, notes, and companies.",
+        description: "List tags (lightweight: the manual tasks_order arrays are omitted — use get_tag for a tag's full ordering). Tags organize contacts, entries, tasks, notes, and companies. Use q to find a tag by name.",
         inputSchema: {
+            q: z.string().optional().describe("Filter by name (case-insensitive substring match)"),
             limit: z.number().int().positive().optional().describe("Max results (default 50)"),
             offset: z.number().int().nonnegative().optional().describe("Pagination offset"),
         },
         annotations: { title: "List tags", readOnlyHint: true, openWorldHint: false },
-    }, async ({ limit, offset }) => {
-        return toContent(await fetchApi(`/tags${qs({ limit, offset })}`));
+    }, async ({ q, limit, offset }) => {
+        return toContent(await fetchApi(`/tags${qs({ q, limit, offset })}`));
     });
     server.registerTool("get_tag", {
-        description: "Get a single tag by ID with all its properties (name, description, color, icon, view mode, favorite status).",
+        description: "Get a single tag by ID with all its properties (name, description, color, icon, view mode, favorite status). Includes tasks_order, the manual ordering of the tag page's task list, where entries of the form \"h:<header_id>\" are section separators (see list_task_headers).",
         inputSchema: {
             id: z.string().uuid().describe("Tag UUID"),
         },
@@ -507,13 +517,22 @@ export function registerAllTools(server, fetchApi) {
         return toContent(await fetchApi(`/tags/${id}`));
     });
     server.registerTool("get_tag_items", {
-        description: "Get all items linked to a specific tag: contacts, entries, tasks, notes, and companies with counts.",
+        description: "Get items linked to a tag. By default returns every type in full — on large tags that can be a huge response, so prefer types/status/summary to narrow it (e.g. types=['tasks'], status='pending', summary=true to review a project's open tasks). When tasks are included, the response also contains `sections`: the tag page's task sections with their task_ids (header_id null = tasks outside any section).",
         inputSchema: {
             id: z.string().uuid().describe("Tag UUID"),
+            types: z
+                .array(z.enum(["contacts", "entries", "tasks", "notes", "companies"]))
+                .optional()
+                .describe("Only fetch these item types (default: all)"),
+            status: z.enum(["pending", "completed"]).optional().describe("Filter tasks by status"),
+            summary: z
+                .boolean()
+                .optional()
+                .describe("Return lightweight items (ids, titles, excerpts) instead of full rows — recommended unless full content is needed"),
         },
         annotations: { title: "Get tag items", readOnlyHint: true, openWorldHint: false },
-    }, async ({ id }) => {
-        return toContent(await fetchApi(`/tags/${id}/items`));
+    }, async ({ id, types, status, summary }) => {
+        return toContent(await fetchApi(`/tags/${id}/items${qs({ types: types?.join(","), status, summary })}`));
     });
     server.registerTool("create_tag", {
         description: "A TAG is a thematic grouping space. Syntax: #name# or [[name]]. Groups notes, entries, tasks, and contacts.\n\nCreate a new tag. If a tag with the same name already exists, returns the existing tag.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keepsake-mcp",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "MCP server for Keepsake personal CRM — connect your AI agent to your contacts, tasks, notes, and more",
   "type": "module",
   "bin": {