slyplan-mcp 1.5.2 → 1.6.3

package/commands/sly/sort-nodes.md

@@ -0,0 +1,129 @@
+---
+description: Reorganize and sort all nodes in the project tree for clean structure
+argument-hint: "[project-name]"
+allowed-tools:
+  - mcp__slyplan__list_projects
+  - mcp__slyplan__set_project
+  - mcp__slyplan__get_tree
+  - mcp__slyplan__get_node
+  - mcp__slyplan__update_node
+  - mcp__slyplan__delete_node
+  - mcp__slyplan__move_node
+  - mcp__slyplan__add_node
+  - mcp__slyplan__search
+---
+
+You are a tree reorganization agent for SlyPlan. Your job is to analyze the entire project tree for "$ARGUMENTS" and reorganize nodes so the structure is logical, clean, and well-grouped. Follow each step in order.
+
+Initialize these counters at the start:
+- moved = 0
+- merged = 0
+- created = 0
+- deleted = 0
+
+## Step 1: Resolve Project
+
+1. Call `list_projects` to get all available projects.
+2. Find the project whose name best matches "$ARGUMENTS" (case-insensitive, fuzzy — partial match is acceptable).
+3. If no reasonable match is found, output: **"No project found matching '$ARGUMENTS'"** and stop.
+4. Call `set_project` with the matched project's ID.
+
+## Step 2: Fetch and Analyze Tree
+
+1. Call `get_tree` **once** to get the complete project hierarchy.
+2. Analyze the entire structure in your working memory.
+3. Identify problems:
+   - **Misplaced nodes:** Plans that should be under a different phase/category.
+   - **Duplicates:** Nodes with very similar titles that should be merged.
+   - **Orphaned nodes:** Nodes that don't logically belong where they are.
+   - **Missing groups:** Related nodes scattered across the tree that should be grouped.
+   - **Wrong types:** Nodes whose type doesn't match their role (e.g., a plan that's really a phase).
+   - **Empty containers:** Categories or phases with no children.
+4. Plan ALL changes before executing any MCP calls.
+
+## Step 3: Fix Hierarchy
+
+The expected hierarchy is: **project > category > phase > plan**
+
+Same-type nesting is allowed (category under category, phase under phase) for logical grouping.
+
+Fix violations:
+- **Plan directly under project:** Wrap in appropriate category > phase.
+- **Plan directly under category:** Wrap in appropriate phase.
+- **Phase directly under project:** Wrap in appropriate category.
+
+Group multiple violations under shared wrappers where logical.
+
+## Step 4: Group Related Nodes
+
+Look for nodes that logically belong together but are scattered:
+
+1. **Identify clusters** of related nodes (by title, description, or domain).
+2. **Create grouping nodes** (categories or phases) to hold them if none exist.
+3. **Move nodes** into their logical groups using `move_node`.
+4. Choose grouping names that are clear and descriptive.
+
+## Step 5: Merge Duplicates
+
+For sibling nodes with very similar titles:
+
+1. **Exact match** (case-insensitive): definite duplicate.
+2. **One title contains the other**: likely duplicate.
+3. **Same key words in different order**: probable duplicate.
+
+When merging A into B (B survives — pick the one with more children/progress):
+1. Move ALL children of A under B using `move_node`.
+2. Combine descriptions if A has unique content.
+3. Set B's status to the more advanced of the two.
+4. Set B's progress to `max(A.progress, B.progress)`.
+5. Delete A (now childless) using `delete_node`.
+
+When in doubt, do NOT merge.
+
+## Step 6: Cleanup
+
+1. Delete categories and phases with zero children.
+2. Flatten single-child wrappers where the wrapper title matches the child.
+3. Do NOT delete project nodes.
+
+## CRITICAL SAFETY RULE
+
+**Before calling `delete_node` on ANY node, you MUST first `move_node` ALL of its children to their new parent.**
+
+The database uses `ON DELETE CASCADE` on `parent_id`. Deleting a parent node **permanently destroys ALL descendants**. There is no undo.
+
+## Behavioral Rules
+
+- Do NOT rewrite existing node titles unless merging duplicates or fixing obvious typos.
+- Do NOT change node statuses or progress unless merging.
+- Fetch `get_tree` only ONCE (Step 2). Do not call it again.
+- Plan all changes mentally before executing any MCP calls.
+- Execute in order: hierarchy fixes → grouping → merging → cleanup.
+- Process silently — no verbose progress commentary during execution.
+
+## Step 7: Report
+
+After all operations, output a clean summary:
+
+```
+Sort complete for "[Project Name]"
+
+Moved: X nodes
+Merged: Y duplicate nodes
+Created: Z grouping nodes
+Deleted: W empty containers
+```
+
+Then show the key changes:
+```
+Changes:
+- Moved "Node" from "Old Parent" → "New Parent"
+- Merged "Duplicate" into "Survivor"
+- Created "New Category" to group related nodes
+- Deleted empty "Old Phase"
+```
+
+If nothing was changed, output:
+```
+No changes needed for "[Project Name]" — tree structure is already clean.
+```

package/commands/sly/sort-tasks.md

@@ -0,0 +1,90 @@
+---
+description: Sort "Sort Later" tasks into the correct places in the project tree
+argument-hint: "[project-name]"
+allowed-tools:
+  - mcp__slyplan__list_projects
+  - mcp__slyplan__set_project
+  - mcp__slyplan__get_tree
+  - mcp__slyplan__get_node
+  - mcp__slyplan__update_node
+  - mcp__slyplan__delete_node
+  - mcp__slyplan__move_node
+  - mcp__slyplan__add_node
+  - mcp__slyplan__search
+  - mcp__supabase__execute_sql
+---
+
+You are a task sorting agent for SlyPlan. Your job is to take all unsorted tasks from the "Sort Later" list (stored in project metadata) and create them as proper nodes in the correct places in the project tree for "$ARGUMENTS". Follow each step in order.
+
+## Step 1: Resolve Project
+
+1. Call `list_projects` to get all available projects.
+2. Find the project whose name best matches "$ARGUMENTS" (case-insensitive, fuzzy — partial match is acceptable).
+3. If no reasonable match is found, output: **"No project found matching '$ARGUMENTS'"** and stop.
+4. Call `set_project` with the matched project's ID.
+
+## Step 2: Find Sort Later Tasks
+
+1. Call `get_node` on the project to read its metadata.
+2. Look for `metadata.sortLaterTasks` — this is an array of tasks with `{ id, title, description, children: [{ id, title, description }] }`.
+3. If the array is empty or doesn't exist, output: **"No Sort Later tasks found — nothing to sort."** and stop.
+4. Note down all the tasks — their titles, descriptions, and children.
+
+## Step 3: Understand the Tree
+
+1. Call `get_tree` **once** to get the complete project hierarchy.
+2. Analyze the existing structure: categories, phases, and plans.
+3. For each Sort Later task, determine the best placement:
+   - Search for existing categories and phases that logically match the task.
+   - Consider the task's title and description to understand its intent.
+4. Plan ALL placements before executing any.
+
+## Step 4: Create Nodes for Each Task
+
+For each Sort Later task:
+
+1. **If an existing category > phase fits:** Create the task as a `plan` node under that phase using `add_node`.
+2. **If a category exists but no fitting phase:** Create a new `phase` with `add_node`, then create the task under it.
+3. **If no relevant category exists:** Create a new `category` with `add_node`, then a `phase` under it, then the task.
+4. **If a task could itself be a category or phase:** Create it with that type and restructure accordingly.
+5. **If a task has children:** Create the parent first, then create each child as a `plan` node under it.
+6. **If a task makes absolutely no sense:** Ask the user what they want to do with it before creating or discarding it.
+
+Use your intelligence to group things logically. Related tasks should be near each other.
+
+## Step 5: Clear Sort Later List
+
+After all tasks are created as nodes, clear the Sort Later list from project metadata:
+
+Use `execute_sql` to clear the sortLaterTasks from the project metadata:
+```sql
+UPDATE nodes SET metadata = metadata - 'sortLaterTasks' WHERE id = '<project-id>';
+```
+
+## Behavioral Rules
+
+- Do NOT modify existing nodes — only create new ones for the Sort Later tasks.
+- Ask the user about ambiguous tasks rather than guessing wrong.
+- Fetch `get_tree` only ONCE (Step 3). Work from the snapshot.
+- Plan all changes before executing MCP calls.
+- Process silently — no verbose progress commentary during execution.
+
+## Step 6: Report
+
+After all operations, output a clean summary:
+
+```
+Sort complete for "[Project Name]"
+
+Sorted: X tasks
+Created: Y new categories/phases
+Skipped: Z tasks (asked user)
+Sort Later list: [cleared | X tasks remaining]
+```
+
+Then list where each task was placed:
+```
+- "Task title" → Category > Phase
+- "Task title" → Category > Phase (new)
+- "Task title" → Skipped (asked user)
+```

package/dist/cli.js

@@ -49,7 +49,9 @@ process.stdin.on('end', () => {
             if (block.type !== 'tool_use') continue;
             const name = block.name || '';
             if (name.includes('set_project')) hasSetProject = true;
+            // Track add/remove — last action wins
             if (name.includes('add_to_work_mode')) hasWorkModeNode = true;
+            if (name.includes('remove_from_work_mode')) hasWorkModeNode = false;
           }
         }
       } catch {}
@@ -72,7 +74,7 @@ process.stdin.on('end', () => {
         suppressOutput: true,
         hookSpecificOutput: {
           hookEventName: "PreToolCall",
-          additionalContext: "SYNC NOW: You have a project set but no node in work mode. Call search + add_to_work_mode before continuing."
+          additionalContext: "BLOCKED: No node in work mode. Call search + add_to_work_mode before doing any work. This is not optional."
         }
       });
       process.stdout.write(output);
@@ -85,11 +87,13 @@ process.stdin.on('end', () => {
   }
 });
 `;
-// Smart transcript-aware hook: counts file changes since last SlyPlan sync.
-// Silent when synced, reminds with count when unsynced.
+// Smart transcript-aware hook: counts file changes SINCE last SlyPlan sync.
+// Silent when synced. Fires after 3+ unsynced file changes or a git commit.
 const POST_HOOK_FILE_CONTENT = `#!/usr/bin/env node
 const fs = require('fs');
 
+const BATCH_THRESHOLD = 3;
+
 let input = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', (chunk) => { input += chunk; });
@@ -108,9 +112,9 @@ process.stdin.on('end', () => {
     const FILE_TOOLS = ['Write', 'Edit', 'NotebookEdit'];
     const SLYPLAN_SYNC_TOOLS = ['update_node', 'add_node', 'add_to_work_mode'];
 
-    let lastFileChangeIdx = -1;
     let lastSlyplanSyncIdx = -1;
-    let fileChangeCount = 0;
+    let fileChangesSinceSync = 0;
+    let hasGitCommitSinceSync = false;
 
     for (let i = 0; i < lines.length; i++) {
       try {
@@ -120,36 +124,62 @@ process.stdin.on('end', () => {
             if (block.type !== 'tool_use') continue;
             const name = block.name || '';
 
-            if (FILE_TOOLS.includes(name)) {
-              lastFileChangeIdx = i;
-              fileChangeCount++;
+            // Track SlyPlan syncs — resets the counter
+            for (const st of SLYPLAN_SYNC_TOOLS) {
+              if (name.includes(st)) {
+                lastSlyplanSyncIdx = i;
+                fileChangesSinceSync = 0;
+                hasGitCommitSinceSync = false;
+              }
+            }
+
+            // Count file changes since last sync
+            if (FILE_TOOLS.includes(name) && i > lastSlyplanSyncIdx) {
+              fileChangesSinceSync++;
             }
+
+            // Detect git commit since last sync
             if (name === 'Bash' && block.input && typeof block.input.command === 'string') {
               const cmd = block.input.command;
-              if (cmd.includes('git commit') || cmd.includes('mkdir')) {
-                lastFileChangeIdx = i;
-                fileChangeCount++;
+              if (cmd.includes('git commit') && i > lastSlyplanSyncIdx) {
+                hasGitCommitSinceSync = true;
               }
             }
-            for (const st of SLYPLAN_SYNC_TOOLS) {
-              if (name.includes(st)) lastSlyplanSyncIdx = i;
-            }
           }
         }
       } catch {}
     }
 
-    if (fileChangeCount === 0) { process.exit(0); }
-    if (lastSlyplanSyncIdx > lastFileChangeIdx) { process.exit(0); }
-
-    const output = JSON.stringify({
-      suppressOutput: true,
-      hookSpecificOutput: {
-        hookEventName: "PostToolUse",
-        additionalContext: "SYNC NOW: " + fileChangeCount + " file change(s) since last SlyPlan sync. Call update_node with current progress before continuing."
-      }
-    });
-    process.stdout.write(output);
+    // No changes since last sync — stay silent
+    if (fileChangesSinceSync === 0 && !hasGitCommitSinceSync) { process.exit(0); }
+
+    // Fire on git commit
+    if (hasGitCommitSinceSync) {
+      const output = JSON.stringify({
+        suppressOutput: true,
+        hookSpecificOutput: {
+          hookEventName: "PostToolUse",
+          additionalContext: "SYNC NOW: Git commit detected \\u2014 update SlyPlan node with progress before continuing."
+        }
+      });
+      process.stdout.write(output);
+      process.exit(0);
+    }
+
+    // Fire when batch threshold reached
+    if (fileChangesSinceSync >= BATCH_THRESHOLD) {
+      const output = JSON.stringify({
+        suppressOutput: true,
+        hookSpecificOutput: {
+          hookEventName: "PostToolUse",
+          additionalContext: "SYNC NOW: " + fileChangesSinceSync + " file change(s) since last sync. Call update_node with current progress."
+        }
+      });
+      process.stdout.write(output);
+      process.exit(0);
+    }
+
+    // Under threshold — stay silent
     process.exit(0);
   } catch (e) {
     process.exit(0);
@@ -162,7 +192,7 @@ const CLAUDEMD_SECTION = `
 Hook messages containing **"BLOCKED"** or **"SYNC NOW"** are HARD REQUIREMENTS, not suggestions.
 
 - **BLOCKED:** You MUST stop what you're doing and follow the instruction BEFORE doing anything else. No exceptions — regardless of whether you're mid-workflow, running a GSD command, or in a multi-step task.
-- **SYNC NOW:** You MUST call \`update_node\` with updated progress BEFORE continuing with the next tool call. Max one file change between each sync.
+- **SYNC NOW:** You MUST call \`update_node\` with updated progress BEFORE continuing with the next tool call. Max 3 file changes between each sync.
 - Hooks are transcript-aware — they only fire when sync is actually missing. If you see a message, it means you have NOT done the work.
 - Ignoring hooks because you're "following a recipe" or "in the middle of something" is NEVER a valid reason.
 
@@ -175,17 +205,30 @@ You MUST keep SlyPlan updated. This is not optional. Follow these rules:
 - Match the project based on the cwd folder name or user context.
 - If ambiguous, ask the user. Cache the project ID for the rest of the session.
 
-### 2. Find or create a node BEFORE starting work
-- Call \`search\` to find the node matching your task.
-- If no node exists: create one with \`add_node\` immediately.
-- Call \`add_to_work_mode\` on the node BEFORE starting with Edit/Write/Bash.
+### 2. Find the right place in the tree BEFORE creating nodes
+Before creating any node, you MUST understand where it belongs:
+1. Call \`get_tree\` with \`max_depth: 2\` to see the project's top-level structure (categories and their immediate children).
+2. Identify the most relevant category or phase for your work.
+3. Call \`get_node\` on that parent with \`max_depth: 2\` to see its full children (2 levels deep).
+4. Now decide: create your node under the best-fitting parent.
+5. If nothing in step 1 was relevant, create a new category.
+
+Once you've found or created the right node:
+- Call \`add_to_work_mode\` on it BEFORE starting with Edit/Write/Bash.
 - **You must NEVER start work without an active work mode node.**
 
 ### 3. Update progress AS YOU GO
-- After each meaningful change: call \`update_node\` with updated \`progress\` (0-100).
-- Update \`description\` with what was actually done.
+- After each meaningful change: call \`update_node\` with updated \`progress\` (0-100) and a \`status_log\` entry.
+- The \`status_log\` parameter appends a log entry to the node — use it to describe what was just done.
+- Keep the node's \`description\` clean and static. Progress notes go in \`status_log\`.
 - Skip for trivial changes (typos, config tweaks).
 
+**Writing good descriptions:**
+- Explain what this node does and WHY it exists — not just a title repeat.
+- Show how it fits in the parent's flow (e.g. "Handles auth token refresh so the API layer can retry failed requests transparently").
+- Keep it concise: 1-3 sentences. Code references are fine when they add clarity (e.g. "Refactors \`useElkLayout.ts\` to support per-project circular layout"), but don't dump implementation details.
+- A non-developer should roughly understand the purpose from the description.
+
 ### 4. NEVER mark anything as done without asking
 - Use \`AskUserQuestion\` with choices: "Yes, mark as done" / "Not yet" / "Skip".
 - **No exceptions.** Auto-marking done is forbidden.
@@ -200,17 +243,28 @@ You MUST keep SlyPlan updated. This is not optional. Follow these rules:
 ### Node hierarchy
 \`project\` > \`category\` > \`phase\` > \`plan\`
 
+Organize nodes logically for readability. Use subcategories/subphases when it helps, but no hard limit on children count — use good judgement.
+
+**Node creation rules:**
+- Always place new nodes under existing logical parents — search first, don't create top-level orphans.
+- Split plans into 2-3 children when work touches multiple components/steps. Don't oversplit single changes.
+- NEVER create a new node to fix/debug an existing one. Update the original node instead (status, description, progress). Debugging is part of the original work, not a separate task.
+
 ### Performance rules
-- NEVER use \`get_tree\` (returns ~18k tokens). Use \`search\` instead.
+- NEVER use \`get_tree\` without \`max_depth\`. Always pass \`max_depth: 2\` or lower.
+- Use \`search\` for finding specific nodes by name.
+- Use \`get_node\` with \`max_depth: 2\` to explore a specific subtree.
 
 ### MCP tools
 | Tool | Usage |
 |------|-------|
 | \`list_projects\` | Find projects (session start) |
 | \`set_project\` | Select active project |
+| \`get_tree\` | See project structure (ALWAYS use \`max_depth: 2\`) |
+| \`get_node\` | Inspect a node + its children (use \`max_depth: 2\`) |
 | \`search\` | Find nodes by name/content |
 | \`add_node\` | Create new node (project/category/phase/plan) |
-| \`update_node\` | Update status, progress, description |
+| \`update_node\` | Update status, progress, description, \`status_log\` (appends log entry) |
 | \`add_to_work_mode\` | Mark node as active work |
 | \`remove_from_work_mode\` | Remove from active work |
 `;
@@ -344,16 +398,21 @@ function writeJsonFile(filePath, data) {
 }
 // --- Settings Merge ---
 // MCP server config goes in .mcp.json (Claude Code reads servers from here)
-function mergeMcpJson(existing, refreshToken) {
+function mergeMcpJson(existing, auth) {
     const result = { ...existing };
     if (!result.mcpServers)
         result.mcpServers = {};
+    const env = {};
+    if (auth.apiKey) {
+        env.SLYPLAN_API_KEY = auth.apiKey;
+    }
+    else if (auth.refreshToken) {
+        env.SLYPLAN_REFRESH_TOKEN = auth.refreshToken;
+    }
     result.mcpServers.slyplan = {
         command: 'npx',
         args: ['-y', 'slyplan-mcp@latest'],
-        env: {
-            SLYPLAN_REFRESH_TOKEN: refreshToken,
-        },
+        env,
     };
     return result;
 }
@@ -498,6 +557,26 @@ async function runSetup() {
         }
     }
     log('');
+    // Generate permanent API key (recommended over refresh tokens)
+    let apiKey = '';
+    const client = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
+        auth: { autoRefreshToken: false, persistSession: false },
+    });
+    await client.auth.refreshSession({ refresh_token: refreshToken });
+    const keyAnswer = await promptUser('  Generate a permanent API key? (recommended) [Y/n]: ');
+    if (keyAnswer.toLowerCase() !== 'n') {
+        const keyName = await promptUser('  Key name [Claude Code]: ');
+        const name = keyName.trim() || 'Claude Code';
+        const { data, error } = await client.rpc('create_api_key', { key_name: name });
+        if (!error && data?.key) {
+            apiKey = data.key;
+            log(`  [+] API key created: ${data.key_prefix}••••`);
+        }
+        else {
+            log(`  [!] Could not create API key: ${error?.message || 'unknown error'}`);
+            log('  Falling back to refresh token.');
+        }
+    }
     // 1. Create hook files
     fs.mkdirSync(hooksDir, { recursive: true });
     fs.writeFileSync(preHookFilePath, PRE_HOOK_FILE_CONTENT, 'utf8');
@@ -506,9 +585,12 @@ async function runSetup() {
     log('  [+] Created .claude/hooks/slyplan-post-tool-sync.cjs');
     // 2. Write MCP server config to .mcp.json
     const existingMcp = readJsonFile(mcpJsonPath) ?? {};
-    const mergedMcp = mergeMcpJson(existingMcp, refreshToken);
+    const auth = apiKey
+        ? { apiKey }
+        : { refreshToken };
+    const mergedMcp = mergeMcpJson(existingMcp, auth);
     writeJsonFile(mcpJsonPath, mergedMcp);
-    log('  [+] Updated .mcp.json');
+    log(`  [+] Updated .mcp.json (${apiKey ? 'API key' : 'refresh token'})`);
     // 3. Write hooks to .claude/settings.json
     let existingSettings = {};
     const rawSettings = readJsonFile(settingsPath);
@@ -525,7 +607,18 @@ async function runSetup() {
     const mergedSettings = mergeSettings(existingSettings);
     writeJsonFile(settingsPath, mergedSettings);
     log('  [+] Updated .claude/settings.json (hooks)');
-    // 4. Optional CLAUDE.md append
+    // 4. Install slash commands (.claude/commands/sly/)
+    const commandsSrcDir = path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')), '..', 'commands', 'sly');
+    const commandsDestDir = path.join(claudeDir, 'commands', 'sly');
+    if (fs.existsSync(commandsSrcDir)) {
+        fs.mkdirSync(commandsDestDir, { recursive: true });
+        const commandFiles = fs.readdirSync(commandsSrcDir).filter(f => f.endsWith('.md'));
+        for (const file of commandFiles) {
+            fs.copyFileSync(path.join(commandsSrcDir, file), path.join(commandsDestDir, file));
+        }
+        log(`  [+] Installed ${commandFiles.length} slash commands: ${commandFiles.map(f => '/sly:' + f.replace('.md', '')).join(', ')}`);
+    }
+    // 5. Optional CLAUDE.md append
     const appendAnswer = await promptUser('  Append SlyPlan sync instructions to CLAUDE.md? [Y/n]: ');
     if (appendAnswer.toLowerCase() !== 'n') {
         if (fs.existsSync(claudeMdPath)) {
@@ -595,7 +688,22 @@ async function runRemove() {
             log('  [-] Removed SlyPlan from .mcp.json');
         }
     }
-    // 3. Clean settings.json
+    // 3. Remove slash commands
+    const commandsDir = path.join(claudeDir, 'commands', 'sly');
+    if (fs.existsSync(commandsDir)) {
+        const files = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'));
+        for (const file of files) {
+            fs.unlinkSync(path.join(commandsDir, file));
+        }
+        // Remove empty dirs
+        try {
+            fs.rmdirSync(commandsDir);
+            fs.rmdirSync(path.join(claudeDir, 'commands'));
+        }
+        catch { }
+        log(`  [-] Removed ${files.length} slash commands`);
+    }
+    // 4. Clean settings.json
     const existing = readJsonFile(settingsPath);
     if (existing) {
         const cleaned = removeFromSettings(existing);

package/dist/db.d.ts

@@ -1,6 +1,6 @@
 import type { TreeNode, Link, NodeDependency } from './types.js';
-export declare function getTree(rootId?: string | null): Promise<TreeNode[]>;
-export declare function getNode(id: string): Promise<TreeNode | null>;
+export declare function getTree(rootId?: string | null, maxDepth?: number): Promise<TreeNode[]>;
+export declare function getNode(id: string, maxDepth?: number): Promise<TreeNode | null>;
 export declare function insertNode(data: {
     parentId: string | null;
     type: string;

package/dist/db.js

@@ -29,7 +29,7 @@ function dbLinkToLink(row) {
     };
 }
 // --- Node CRUD ---
-export async function getTree(rootId) {
+export async function getTree(rootId, maxDepth) {
     const { data: allNodes, error: nodesErr } = await supabase
         .from('nodes')
         .select('*')
@@ -56,10 +56,12 @@ export async function getTree(rootId) {
         arr.push(node);
         childrenMap.set(parentKey, arr);
     }
-    function buildSubtree(parentId) {
+    function buildSubtree(parentId, depth) {
         const children = childrenMap.get(parentId) || [];
         return children.map(node => {
-            const subtreeChildren = buildSubtree(node.id);
+            const subtreeChildren = (maxDepth !== undefined && depth >= maxDepth)
+                ? []
+                : buildSubtree(node.id, depth + 1);
             const links = linksByNode.get(node.id) || [];
             let progress = node.progress;
             if (subtreeChildren.length > 0) {
@@ -73,16 +75,16 @@ export async function getTree(rootId) {
         const rootNode = nodeMap.get(rootId);
         if (!rootNode)
             return [];
-        const children = buildSubtree(rootId);
+        const children = buildSubtree(rootId, 1);
         let progress = rootNode.progress;
         if (children.length > 0) {
             progress = Math.round(children.reduce((sum, c) => sum + c.progress, 0) / children.length);
         }
         return [dbNodeToTree({ ...rootNode, progress }, linksByNode.get(rootId) || [], children)];
     }
-    return buildSubtree(null);
+    return buildSubtree(null, 0);
 }
-export async function getNode(id) {
+export async function getNode(id, maxDepth = 1) {
     const { data: row, error } = await supabase
         .from('nodes')
         .select('*')
@@ -95,10 +97,18 @@ export async function getNode(id) {
         .select('*')
         .eq('node_id', id);
     const links = (linkRows || []).map(dbLinkToLink);
+    const children = maxDepth > 0 ? await getChildrenRecursive(id, maxDepth, 1) : [];
+    let progress = row.progress;
+    if (children.length > 0) {
+        progress = Math.round(children.reduce((sum, c) => sum + c.progress, 0) / children.length);
+    }
+    return dbNodeToTree({ ...row, progress }, links, children);
+}
+async function getChildrenRecursive(parentId, maxDepth, currentDepth) {
     const { data: childRows } = await supabase
         .from('nodes')
         .select('*')
-        .eq('parent_id', id)
+        .eq('parent_id', parentId)
         .order('sort_order', { ascending: true });
     const children = [];
     for (const child of (childRows || [])) {
@@ -106,13 +116,16 @@ export async function getNode(id) {
             .from('links')
             .select('*')
             .eq('node_id', child.id);
-        children.push(dbNodeToTree(child, (childLinkRows || []).map(dbLinkToLink), []));
-    }
-    let progress = row.progress;
-    if (children.length > 0) {
-        progress = Math.round(children.reduce((sum, c) => sum + c.progress, 0) / children.length);
+        const grandchildren = currentDepth < maxDepth
+            ? await getChildrenRecursive(child.id, maxDepth, currentDepth + 1)
+            : [];
+        let progress = child.progress;
+        if (grandchildren.length > 0) {
+            progress = Math.round(grandchildren.reduce((sum, c) => sum + c.progress, 0) / grandchildren.length);
+        }
+        children.push(dbNodeToTree({ ...child, progress }, (childLinkRows || []).map(dbLinkToLink), grandchildren));
     }
-    return dbNodeToTree({ ...row, progress }, links, children);
+    return children;
 }
 export async function insertNode(data) {
     const id = uuid();

package/dist/index.js

@@ -56,14 +56,20 @@ server.tool('set_project', 'Select which project to work in. All subsequent oper
         content: [{ type: 'text', text: `Active project set to: "${node.title}"\n\nAll add_node, get_tree and search operations will now apply to this project.\nUse get_tree to see the project structure.` }],
     };
 });
-server.tool('get_tree', 'Get the project tree. Shows the active project if set, or the full tree.', { root_id: z.string().optional().describe('Node ID to use as root. Omit for active project / full tree.') }, async ({ root_id }) => {
+server.tool('get_tree', 'Get the project tree. Shows the active project if set, or the full tree. Use max_depth to limit how deep the tree goes.', {
+    root_id: z.string().optional().describe('Node ID to use as root. Omit for active project / full tree.'),
+    max_depth: z.number().min(0).optional().describe('Max depth of children to include (0 = root only, 1 = direct children, 2 = grandchildren). Omit for full tree.'),
+}, async ({ root_id, max_depth }) => {
     const effectiveRoot = root_id ?? activeProjectId ?? null;
-    const tree = await getTree(effectiveRoot);
+    const tree = await getTree(effectiveRoot, max_depth);
     const ctx = activeProjectId ? `Project: ${await getActiveProjectName()}\n\n` : '';
     return { content: [{ type: 'text', text: `${ctx}${JSON.stringify(tree, null, 2)}` }] };
 });
-server.tool('get_node', 'Get details about a single node', { id: z.string().describe('Node ID to fetch') }, async ({ id }) => {
-    const node = await getNode(id);
+server.tool('get_node', 'Get details about a single node and its children', {
+    id: z.string().describe('Node ID to fetch'),
+    max_depth: z.number().min(0).optional().describe('How many levels of children to include (0 = node only, 1 = direct children, 2 = grandchildren). Default: 1.'),
+}, async ({ id, max_depth }) => {
+    const node = await getNode(id, max_depth ?? 1);
     if (!node)
         return { content: [{ type: 'text', text: 'Node not found' }], isError: true };
     return { content: [{ type: 'text', text: JSON.stringify(node, null, 2) }] };
@@ -97,7 +103,17 @@ server.tool('update_node', 'Update fields on an existing node', {
     status: z.enum(['not_started', 'in_progress', 'blocked', 'done']).optional().describe('New status'),
     progress: z.number().min(0).max(100).optional().describe('New progress (0-100)'),
     metadata: z.record(z.unknown()).optional().describe('New metadata'),
-}, async ({ id, ...updates }) => {
+    status_log: z.string().optional().describe('Append a status log entry (stored in metadata.statusLog array)'),
+}, async ({ id, status_log, ...updates }) => {
+    if (status_log) {
+        const current = await getNode(id);
+        if (!current)
+            return { content: [{ type: 'text', text: 'Node not found' }], isError: true };
+        const meta = (current.metadata || {});
+        const log = Array.isArray(meta.statusLog) ? [...meta.statusLog] : [];
+        log.push(status_log);
+        updates.metadata = { ...meta, ...(updates.metadata || {}), statusLog: log };
+    }
     const node = await updateNode(id, updates);
     if (!node)
         return { content: [{ type: 'text', text: 'Node not found' }], isError: true };

package/dist/supabase.js

@@ -33,10 +33,42 @@ supabase.auth.onAuthStateChange((event, session) => {
     }
 });
 export async function authenticate() {
+    const apiKey = process.env.SLYPLAN_API_KEY;
     const refreshToken = process.env.SLYPLAN_REFRESH_TOKEN;
     const email = process.env.SLYPLAN_EMAIL;
     const password = process.env.SLYPLAN_PASSWORD;
-    // Prefer refresh token (new browser-based flow)
+    // 1. Preferred: permanent API key (never expires)
+    //    Calls edge function to exchange API key → Supabase session tokens
+    if (apiKey) {
+        try {
+            const res = await fetch(`${SUPABASE_URL}/functions/v1/exchange-api-key`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ api_key: apiKey }),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: res.statusText }));
+                console.error(`API key authentication failed: ${err.error || res.statusText}`);
+                process.exit(1);
+            }
+            const tokens = await res.json();
+            const { error: sessionError } = await supabase.auth.setSession({
+                access_token: tokens.access_token,
+                refresh_token: tokens.refresh_token,
+            });
+            if (sessionError) {
+                console.error(`Failed to set session from API key: ${sessionError.message}`);
+                process.exit(1);
+            }
+            userId = tokens.user_id;
+        }
+        catch (err) {
+            console.error(`API key authentication failed: ${err.message}`);
+            process.exit(1);
+        }
+        return;
+    }
+    // 2. Refresh token (browser-based flow)
     if (refreshToken) {
         lastPersistedToken = refreshToken;
         const { data, error } = await supabase.auth.refreshSession({ refresh_token: refreshToken });
@@ -62,7 +94,7 @@ export async function authenticate() {
         userId = data.user.id;
         return;
     }
-    console.error('Missing SLYPLAN_REFRESH_TOKEN (or SLYPLAN_EMAIL + SLYPLAN_PASSWORD).');
+    console.error('Missing SLYPLAN_API_KEY, SLYPLAN_REFRESH_TOKEN, or SLYPLAN_EMAIL + SLYPLAN_PASSWORD.');
     console.error('Run "npx slyplan-mcp setup" to configure authentication.');
     process.exit(1);
 }

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "slyplan-mcp",
-  "version": "1.5.2",
+  "version": "1.6.3",
   "description": "MCP server for Slyplan — visual project management via Claude",
   "type": "module",
   "bin": {
     "slyplan-mcp": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "commands"
   ],
   "scripts": {
     "build": "tsc",