keepsake-mcp 1.4.0 → 1.5.0

package/README.md

@@ -165,12 +165,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

@@ -488,17 +488,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 +508,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.5.0",
   "description": "MCP server for Keepsake personal CRM — connect your AI agent to your contacts, tasks, notes, and more",
   "type": "module",
   "bin": {