lystbot 0.3.6 → 0.3.7

package/README.md

@@ -9,6 +9,12 @@ npx lystbot login <your-api-key>
 npx lystbot lists
 npx lystbot add "Groceries" "Milk, Eggs, Butter"
 npx lystbot check "Groceries" "Milk"
+
+# Categories
+npx lystbot categories "Groceries"
+npx lystbot category add "Groceries" "Fruits"
+npx lystbot add "Groceries" "Bananas" --category "Fruits"
+npx lystbot move "Groceries" "Bananas" --category other
 ```
 
 ## MCP Server (Claude Desktop, Cursor, Windsurf)
@@ -65,8 +71,15 @@ Add to `.cursor/mcp.json` or `.windsurf/mcp.json`:
 | `check_item` | Check off an item |
 | `uncheck_item` | Reopen a checked item |
 | `remove_item` | Delete an item |
+| `clear_checked` | Remove all checked (completed) items from a list |
 | `share_list` | Generate a share code |
 | `join_list` | Join a shared list |
+| `list_categories` | List categories for a list |
+| `create_category` | Create a category |
+| `rename_category` | Rename a category |
+| `delete_category` | Delete a category |
+| `reorder_categories` | Reorder categories |
+| `move_item` | Move an item to a category (or Other) |
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lystbot",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "mcpName": "io.github.TourAround/lystbot",
   "description": "LystBot CLI - Manage your lists from the terminal",
   "main": "src/index.js",

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "cli"
   },
-  "version": "0.3.5",
+  "version": "0.3.7",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "lystbot",
-      "version": "0.3.5",
+      "version": "0.3.7",
       "transport": {
         "type": "stdio"
       },
@@ -30,7 +30,15 @@
     { "name": "check_item", "description": "Check off an item" },
     { "name": "uncheck_item", "description": "Uncheck an item" },
     { "name": "remove_item", "description": "Remove an item from a list" },
+    { "name": "clear_checked", "description": "Remove all checked (completed) items from a list" },
     { "name": "share_list", "description": "Generate a share code for a list" },
-    { "name": "join_list", "description": "Join a shared list via code" }
+    { "name": "join_list", "description": "Join a shared list via code" },
+
+    { "name": "list_categories", "description": "List categories for a list" },
+    { "name": "create_category", "description": "Create a category" },
+    { "name": "rename_category", "description": "Rename a category" },
+    { "name": "delete_category", "description": "Delete a category" },
+    { "name": "reorder_categories", "description": "Reorder categories" },
+    { "name": "move_item", "description": "Move an item to a category (or Other)" }
   ]
 }

package/src/api.js

@@ -121,6 +121,27 @@ function findItem(items, query) {
   return null;
 }
 
+// Fuzzy match: find a category by name or ID from an array of categories
+function findCategory(categories, query) {
+  if (!Array.isArray(categories)) return null;
+
+  // Try exact ID match
+  const byId = categories.find(c => String(c.id) === String(query));
+  if (byId) return byId;
+
+  const lower = String(query).toLowerCase();
+  const exact = categories.find(c => (c.name || '').toLowerCase() === lower);
+  if (exact) return exact;
+
+  const starts = categories.find(c => (c.name || '').toLowerCase().startsWith(lower));
+  if (starts) return starts;
+
+  const includes = categories.find(c => (c.name || '').toLowerCase().includes(lower));
+  if (includes) return includes;
+
+  return null;
+}
+
 // Resolve a list query to {list, detail} - fetches all lists then the specific one
 async function resolveList(query, { withItems = false } = {}) {
   const res = await request('GET', '/lists');
@@ -156,4 +177,4 @@ function autoEmoji(name) {
   return '📋';
 }
 
-module.exports = { request, rawRequest, findList, findItem, resolveList, autoEmoji };
+module.exports = { request, rawRequest, findList, findItem, findCategory, resolveList, autoEmoji };

package/src/index.js

@@ -177,28 +177,209 @@ program
     const shared = detail.is_shared ? ` 👥 (${memberCount} member${memberCount === 1 ? '' : 's'})` : '';
     console.log(`\n${emoji} ${listTitle}${shared}\n`);
 
-    if (!detail.items || !detail.items.length) {
+    const items = detail.items || [];
+    const categories = Array.isArray(detail.categories)
+      ? [...detail.categories].sort((a, b) => (a.position ?? 0) - (b.position ?? 0))
+      : [];
+
+    if (!items.length) {
       console.log('  (empty list)');
       return;
     }
 
-    for (const item of detail.items) {
-      if (item.checked) {
-        console.log(`  ✅ ~~${item.text}~~`);
-      } else {
-        console.log(`  ⬜ ${item.text}`);
+    // If categories exist, render sectioned view like the app.
+    if (categories.length > 0) {
+      const byCategory = new Map();
+      for (const c of categories) byCategory.set(c.id, []);
+      const other = [];
+
+      for (const item of items) {
+        const cid = item.category_id || null;
+        if (cid && byCategory.has(cid)) byCategory.get(cid).push(item);
+        else other.push(item);
+      }
+
+      for (const c of categories) {
+        const sectionItems = byCategory.get(c.id) || [];
+        console.log(`  ${c.name}`);
+        if (sectionItems.length === 0) {
+          console.log('    (empty)');
+        } else {
+          for (const item of sectionItems) {
+            console.log(item.checked ? `    ✅ ~~${item.text}~~` : `    ⬜ ${item.text}`);
+          }
+        }
+        console.log('');
+      }
+
+      if (other.length > 0) {
+        console.log('  Other');
+        for (const item of other) {
+          console.log(item.checked ? `    ✅ ~~${item.text}~~` : `    ⬜ ${item.text}`);
+        }
+      }
+    } else {
+      // Flat view
+      for (const item of items) {
+        console.log(item.checked ? `  ✅ ~~${item.text}~~` : `  ⬜ ${item.text}`);
+      }
+    }
+
+    const checked = items.filter(i => i.checked).length;
+    console.log(`\n  ${checked}/${items.length} done`);
+  });
+
+// ── categories (read-only shortcut) ───────────────────
+program
+  .command('categories <list>')
+  .description('Show categories in a list (including Other/uncategorized)')
+  .option('--json', 'Output as JSON')
+  .action(async (listQuery, options) => {
+    config.getApiKey();
+    const { list, detail } = await api.resolveList(listQuery, { withItems: true });
+
+    const categories = Array.isArray(detail.categories)
+      ? [...detail.categories].sort((a, b) => (a.position ?? 0) - (b.position ?? 0))
+      : [];
+    const items = detail.items || [];
+
+    if (options.json) {
+      const otherCount = items.filter(i => !i.category_id).length;
+      console.log(JSON.stringify({ list_id: list.id, categories, other_count: otherCount }, null, 2));
+      return;
+    }
+
+    console.log(`\n${detail.emoji || '📋'} ${detail.title || detail.name} — Categories\n`);
+    if (categories.length === 0) {
+      console.log('  (no categories yet)');
+    } else {
+      for (const c of categories) {
+        const count = items.filter(i => i.category_id === c.id).length;
+        console.log(`  • ${c.name}  (${count} item${count === 1 ? '' : 's'})`);
       }
     }
 
-    const checked = detail.items.filter(i => i.checked).length;
-    console.log(`\n  ${checked}/${detail.items.length} done`);
+    const otherCount = items.filter(i => !i.category_id).length;
+    console.log(`  • Other  (${otherCount} item${otherCount === 1 ? '' : 's'})`);
+  });
+
+// ── category (manage) ─────────────────────────────────
+const categoryCmd = program
+  .command('category')
+  .description('Manage list categories');
+
+categoryCmd
+  .command('add <list> <name>')
+  .description('Create a category')
+  .option('--position <n>', 'Insert position (default: end)')
+  .action(async (listQuery, name, options) => {
+    config.getApiKey();
+    const { list } = await api.resolveList(listQuery);
+    const body = { id: randomUUID(), name: name.trim() };
+    if (options.position !== undefined) body.position = parseInt(options.position, 10);
+    const res = await api.request('POST', `/lists/${list.id}/categories`, body);
+    console.log(`✅ Category created: ${res.name} [id: ${res.id}]`);
+  });
+
+categoryCmd
+  .command('rename <list> <category> <newName>')
+  .description('Rename a category')
+  .action(async (listQuery, categoryQuery, newName) => {
+    config.getApiKey();
+    const { list, detail } = await api.resolveList(listQuery, { withItems: true });
+    const cat = api.findCategory(detail.categories || [], categoryQuery);
+    if (!cat) {
+      const names = (detail.categories || []).map(c => c.name).join(', ');
+      console.error(`❌ Category '${categoryQuery}' not found. Categories: ${names || '(none)'}`);
+      process.exit(1);
+    }
+    const res = await api.request('PUT', `/lists/${list.id}/categories/${cat.id}`, { name: newName.trim() });
+    console.log(`✅ Category renamed: ${cat.name} → ${res.name}`);
+  });
+
+categoryCmd
+  .command('delete <list> <category>')
+  .description('Delete a category (items will move to Other)')
+  .option('--force', 'Skip confirmation')
+  .action(async (listQuery, categoryQuery, options) => {
+    config.getApiKey();
+    const { list, detail } = await api.resolveList(listQuery, { withItems: true });
+    const cat = api.findCategory(detail.categories || [], categoryQuery);
+    if (!cat) {
+      const names = (detail.categories || []).map(c => c.name).join(', ');
+      console.error(`❌ Category '${categoryQuery}' not found. Categories: ${names || '(none)'}`);
+      process.exit(1);
+    }
+
+    if (!options.force) {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await new Promise(resolve =>
+        rl.question(`🗑️  Delete category '${cat.name}'? Items will be moved to Other. (y/N) `, resolve)
+      );
+      rl.close();
+      if (answer.toLowerCase() !== 'y') {
+        console.log('Cancelled.');
+        process.exit(0);
+      }
+    }
+
+    const res = await api.request('DELETE', `/lists/${list.id}/categories/${cat.id}`);
+    console.log(`🗑️  Deleted category: ${cat.name} (moved ${res.moved_count ?? 0} item(s) to Other)`);
+  });
+
+categoryCmd
+  .command('reorder <list>')
+  .description('Reorder categories')
+  .requiredOption('--order <csv>', 'Comma-separated category names or IDs in desired order')
+  .action(async (listQuery, options) => {
+    config.getApiKey();
+    const { list, detail } = await api.resolveList(listQuery, { withItems: true });
+    const categories = detail.categories || [];
+    if (!categories.length) {
+      console.error('❌ This list has no categories to reorder.');
+      process.exit(1);
+    }
+
+    const parts = String(options.order)
+      .split(',')
+      .map(s => s.trim())
+      .filter(Boolean);
+
+    if (parts.length === 0) {
+      console.error('❌ --order cannot be empty');
+      process.exit(1);
+    }
+
+    const resolved = [];
+    for (const q of parts) {
+      const cat = api.findCategory(categories, q);
+      if (!cat) {
+        console.error(`❌ Category '${q}' not found in list.`);
+        process.exit(1);
+      }
+      resolved.push(cat);
+    }
+
+    // Require full order to avoid surprises
+    const uniqueIds = new Set(resolved.map(c => c.id));
+    if (uniqueIds.size !== categories.length) {
+      console.error('❌ --order must include each category exactly once.');
+      console.error(`   Expected ${categories.length} unique categories, got ${uniqueIds.size}.`);
+      process.exit(1);
+    }
+
+    const order = resolved.map((c, idx) => ({ category_id: c.id, position: idx }));
+    await api.request('PUT', `/lists/${list.id}/categories/reorder`, { order });
+    console.log('✅ Categories reordered.');
   });
 
 // ── add ────────────────────────────────────────────────
 program
   .command('add <list> <items...>')
   .description('Add items to a list (supports comma-separated)')
-  .action(async (listQuery, rawItems) => {
+  .option('--category <category>', 'Add items to a category (name or ID)')
+  .option('--create-category', 'Auto-create the category if it does not exist (only works with --category name)')
+  .action(async (listQuery, rawItems, options) => {
     config.getApiKey();
 
     // Smart parsing: each CLI argument is one item.
@@ -246,6 +427,30 @@ program
       console.log(`✨ Created list: ${emoji} ${listQuery}`);
     }
 
+    // Resolve category (optional)
+    let categoryId = null;
+    if (options.category) {
+      const detail = await api.request('GET', `/lists/${match.id}`);
+      const cat = api.findCategory(detail.categories || [], options.category);
+      if (!cat) {
+        if (options.createCategory) {
+          const created = await api.request('POST', `/lists/${match.id}/categories`, {
+            id: randomUUID(),
+            name: String(options.category).trim(),
+          });
+          categoryId = created.id;
+          console.log(`✅ Created category: ${created.name}`);
+        } else {
+          const names = (detail.categories || []).map(c => c.name).join(', ');
+          console.error(`❌ Category '${options.category}' not found. Categories: ${names || '(none)'}`);
+          console.error('   Tip: Use --create-category to create it automatically.');
+          process.exit(1);
+        }
+      } else {
+        categoryId = cat.id;
+      }
+    }
+
     // Add items one by one (each needs a client-generated UUID)
     let added = 0;
     for (let idx = 0; idx < items.length; idx++) {
@@ -255,6 +460,7 @@ program
         quantity: 1,
         unit: null,
         position: idx,
+        category_id: categoryId,
       });
       added++;
     }
@@ -266,6 +472,40 @@ program
     }
   });
 
+// ── move (item category) ──────────────────────────────
+program
+  .command('move <list> <item>')
+  .description('Move an item to a category (or to Other)')
+  .requiredOption('--category <category>', 'Target category name/ID, or "other" to uncategorize')
+  .action(async (listQuery, itemQuery, options) => {
+    config.getApiKey();
+    const { list, detail } = await api.resolveList(listQuery, { withItems: true });
+
+    const item = api.findItem(detail.items || [], itemQuery);
+    if (!item) {
+      const names = (detail.items || []).map(i => i.text).join(', ');
+      console.error(`❌ Item '${itemQuery}' not found in ${list.title || list.name}. Items: ${names || '(empty)'}`);
+      process.exit(1);
+    }
+
+    const q = String(options.category).trim().toLowerCase();
+    let categoryId = null;
+    if (q === 'other' || q === 'uncategorized' || q === 'none' || q === 'null') {
+      categoryId = null;
+    } else {
+      const cat = api.findCategory(detail.categories || [], options.category);
+      if (!cat) {
+        const names = (detail.categories || []).map(c => c.name).join(', ');
+        console.error(`❌ Category '${options.category}' not found. Categories: ${names || '(none)'}`);
+        process.exit(1);
+      }
+      categoryId = cat.id;
+    }
+
+    await api.request('PUT', `/lists/${list.id}/items/${item.id}`, { category_id: categoryId });
+    console.log(`✅ Moved: ${item.text} → ${categoryId ? options.category : 'Other'}`);
+  });
+
 // ── check ──────────────────────────────────────────────
 program
   .command('check <list> <item>')

package/src/mcp.js

@@ -35,6 +35,17 @@ function findList(lists, query) {
     || null;
 }
 
+function findCategory(categories, query) {
+  if (!Array.isArray(categories)) return null;
+  const byId = categories.find(c => String(c.id) === String(query));
+  if (byId) return byId;
+  const lower = String(query).toLowerCase();
+  return categories.find(c => (c.name || '').toLowerCase() === lower)
+    || categories.find(c => (c.name || '').toLowerCase().startsWith(lower))
+    || categories.find(c => (c.name || '').toLowerCase().includes(lower))
+    || null;
+}
+
 function uuid() {
   return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
     const r = Math.random() * 16 | 0;
@@ -79,12 +90,46 @@ async function startMcpServer() {
 
     const detail = await api('GET', `/lists/${match.id}`);
     const items = detail.items || [];
+    const categories = Array.isArray(detail.categories)
+      ? [...detail.categories].sort((a, b) => (a.position ?? 0) - (b.position ?? 0))
+      : [];
 
     let text = `${match.emoji || '📋'} ${match.title}\n`;
     text += `Type: ${match.type || 'generic'} | ${items.length} items\n\n`;
 
     if (items.length === 0) {
       text += '(empty)';
+    } else if (categories.length > 0) {
+      const byCategory = new Map();
+      for (const c of categories) byCategory.set(c.id, []);
+      const other = [];
+
+      for (const i of items) {
+        const cid = i.category_id || null;
+        if (cid && byCategory.has(cid)) byCategory.get(cid).push(i);
+        else other.push(i);
+      }
+
+      const renderItem = (i) => {
+        const check = i.checked ? '✅' : '⬜';
+        const qty = (i.quantity || 1) > 1 ? ` (${i.quantity}x)` : '';
+        const unit = i.unit ? ` ${i.unit}` : '';
+        return `${check} ${i.text}${qty}${unit}`;
+      };
+
+      for (const c of categories) {
+        text += `${c.name}\n`;
+        const sectionItems = byCategory.get(c.id) || [];
+        if (sectionItems.length === 0) {
+          text += '  (empty)\n\n';
+        } else {
+          text += sectionItems.map(i => `  ${renderItem(i)}`).join('\n') + '\n\n';
+        }
+      }
+      if (other.length > 0) {
+        text += `Other\n`;
+        text += other.map(i => `  ${renderItem(i)}`).join('\n');
+      }
     } else {
       text += items.map(i => {
         const check = i.checked ? '✅' : '⬜';
@@ -129,17 +174,34 @@ async function startMcpServer() {
   server.tool('add_items', 'Add one or more items to a list', {
     list: z.string().describe('List name or ID'),
     items: z.string().describe('Items to add, separated by comma+space or semicolon. Example: "Milk, Eggs, Butter"'),
-  }, async ({ list: query, items: itemsStr }) => {
+    category: z.string().optional().describe('Optional category name or ID. Use "other" to add uncategorized.'),
+  }, async ({ list: query, items: itemsStr, category }) => {
     const all = await api('GET', '/lists');
     const match = findList(all.lists || all, query);
     if (!match) throw new Error(`List "${query}" not found`);
 
+    const detail = await api('GET', `/lists/${match.id}`);
+    const categories = detail.categories || [];
+
+    let categoryId = null;
+    if (typeof category === 'string' && category.trim() !== '') {
+      const cQuery = category.trim();
+      const lower = cQuery.toLowerCase();
+      if (lower === 'other' || lower === 'uncategorized' || lower === 'none' || lower === 'null') {
+        categoryId = null;
+      } else {
+        const cat = findCategory(categories, cQuery);
+        if (!cat) throw new Error(`Category "${cQuery}" not found`);
+        categoryId = cat.id;
+      }
+    }
+
     const texts = itemsStr.split(/;\s*|,\s+/).map(s => s.trim()).filter(Boolean);
     const added = [];
 
     for (const text of texts) {
       const id = uuid();
-      await api('POST', `/lists/${match.id}/items`, { id, text });
+      await api('POST', `/lists/${match.id}/items`, { id, text, category_id: categoryId });
       added.push(text);
     }
 
@@ -228,10 +290,136 @@ async function startMcpServer() {
   server.tool('join_list', 'Join a shared list using a share code', {
     code: z.string().describe('The share code'),
   }, async ({ code }) => {
-    const data = await api('POST', '/lists/join', { share_code: code });
+    const data = await api('POST', '/lists/join', { code });
     return { content: [{ type: 'text', text: `Joined list: ${data.emoji || '📋'} ${data.title || data.list_id}` }] };
   });
 
+  // --- Categories ---
+
+  server.tool('list_categories', 'List categories for a list (includes Other/uncategorized count)', {
+    list: z.string().describe('List name or ID'),
+  }, async ({ list: query }) => {
+    const all = await api('GET', '/lists');
+    const match = findList(all.lists || all, query);
+    if (!match) throw new Error(`List "${query}" not found`);
+    const detail = await api('GET', `/lists/${match.id}`);
+    const categories = (detail.categories || []).slice().sort((a, b) => (a.position ?? 0) - (b.position ?? 0));
+    const items = detail.items || [];
+
+    if (categories.length === 0) {
+      const otherCount = items.filter(i => !i.category_id).length;
+      return { content: [{ type: 'text', text: `No categories in ${match.emoji || '📋'} ${match.title}.\nOther: ${otherCount} item(s)` }] };
+    }
+
+    const lines = categories.map(c => {
+      const count = items.filter(i => i.category_id === c.id).length;
+      return `- ${c.name} (${count} item(s)) [id: ${c.id}]`;
+    });
+    const otherCount = items.filter(i => !i.category_id).length;
+    lines.push(`- Other (${otherCount} item(s))`);
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+  });
+
+  server.tool('create_category', 'Create a category', {
+    list: z.string().describe('List name or ID'),
+    name: z.string().describe('Category name'),
+    position: z.number().optional().describe('Optional position (default: end)'),
+  }, async ({ list: query, name, position }) => {
+    const all = await api('GET', '/lists');
+    const match = findList(all.lists || all, query);
+    if (!match) throw new Error(`List "${query}" not found`);
+    const id = uuid();
+    const body = { id, name };
+    if (typeof position === 'number') body.position = position;
+    const res = await api('POST', `/lists/${match.id}/categories`, body);
+    return { content: [{ type: 'text', text: `Created category: ${res.name} [id: ${res.id}]` }] };
+  });
+
+  server.tool('rename_category', 'Rename a category', {
+    list: z.string().describe('List name or ID'),
+    category: z.string().describe('Category name or ID'),
+    name: z.string().describe('New category name'),
+  }, async ({ list: query, category, name }) => {
+    const all = await api('GET', '/lists');
+    const match = findList(all.lists || all, query);
+    if (!match) throw new Error(`List "${query}" not found`);
+    const detail = await api('GET', `/lists/${match.id}`);
+    const cat = findCategory(detail.categories || [], category);
+    if (!cat) throw new Error(`Category "${category}" not found`);
+    const res = await api('PUT', `/lists/${match.id}/categories/${cat.id}`, { name });
+    return { content: [{ type: 'text', text: `Renamed category: ${cat.name} → ${res.name}` }] };
+  });
+
+  server.tool('delete_category', 'Delete a category (items will move to Other)', {
+    list: z.string().describe('List name or ID'),
+    category: z.string().describe('Category name or ID'),
+  }, async ({ list: query, category }) => {
+    const all = await api('GET', '/lists');
+    const match = findList(all.lists || all, query);
+    if (!match) throw new Error(`List "${query}" not found`);
+    const detail = await api('GET', `/lists/${match.id}`);
+    const cat = findCategory(detail.categories || [], category);
+    if (!cat) throw new Error(`Category "${category}" not found`);
+    const res = await api('DELETE', `/lists/${match.id}/categories/${cat.id}`);
+    return { content: [{ type: 'text', text: `Deleted category: ${cat.name} (moved ${res.moved_count ?? 0} item(s) to Other)` }] };
+  });
+
+  server.tool('reorder_categories', 'Reorder categories', {
+    list: z.string().describe('List name or ID'),
+    order: z.array(z.string()).describe('Desired order as an array of category names or IDs (must include each category exactly once)'),
+  }, async ({ list: query, order }) => {
+    const all = await api('GET', '/lists');
+    const match = findList(all.lists || all, query);
+    if (!match) throw new Error(`List "${query}" not found`);
+    const detail = await api('GET', `/lists/${match.id}`);
+    const categories = detail.categories || [];
+    if (categories.length === 0) throw new Error('This list has no categories');
+
+    const resolved = order.map(q => {
+      const cat = findCategory(categories, q);
+      if (!cat) throw new Error(`Category "${q}" not found`);
+      return cat;
+    });
+
+    const unique = new Set(resolved.map(c => c.id));
+    if (unique.size !== categories.length) {
+      throw new Error(`order must include each category exactly once (expected ${categories.length}, got ${unique.size})`);
+    }
+
+    const payload = resolved.map((c, idx) => ({ category_id: c.id, position: idx }));
+    await api('PUT', `/lists/${match.id}/categories/reorder`, { order: payload });
+    return { content: [{ type: 'text', text: 'Categories reordered.' }] };
+  });
+
+  server.tool('move_item', 'Move an item to a category (or to Other)', {
+    list: z.string().describe('List name or ID'),
+    item: z.string().describe('Item text (fuzzy match)'),
+    category: z.string().describe('Target category name/ID, or "other" to uncategorize'),
+  }, async ({ list: query, item: itemQuery, category }) => {
+    const all = await api('GET', '/lists');
+    const match = findList(all.lists || all, query);
+    if (!match) throw new Error(`List "${query}" not found`);
+    const detail = await api('GET', `/lists/${match.id}`);
+    const items = detail.items || [];
+    const lower = itemQuery.toLowerCase();
+    const found = items.find(i => i.text.toLowerCase() === lower)
+      || items.find(i => i.text.toLowerCase().includes(lower));
+    if (!found) throw new Error(`Item "${itemQuery}" not found in ${match.title}`);
+
+    const cLower = String(category).trim().toLowerCase();
+    let categoryId = null;
+    if (cLower === 'other' || cLower === 'uncategorized' || cLower === 'none' || cLower === 'null') {
+      categoryId = null;
+    } else {
+      const cat = findCategory(detail.categories || [], category);
+      if (!cat) throw new Error(`Category "${category}" not found`);
+      categoryId = cat.id;
+    }
+
+    await api('PUT', `/lists/${match.id}/items/${found.id}`, { category_id: categoryId });
+    return { content: [{ type: 'text', text: `Moved: ${found.text} → ${categoryId ? category : 'Other'}` }] };
+  });
+
   // Connect via stdio
   const transport = new StdioServerTransport();
   await server.connect(transport);