internaltool-mcp 1.5.5 → 1.6.0

package/index.js

@@ -356,56 +356,433 @@ Set confirmed=false first to preview, then confirmed=true to actually save.`,
   )
 }
 
+// ── Standup activity formatter ────────────────────────────────────────────────
+// Converts raw activity {action, meta} into a human-readable sentence.
+function formatActivityLine(a) {
+  const m = a.meta || {}
+  switch (a.action) {
+    case 'task.created':    return 'Task created'
+    case 'task.updated':    return m.fields?.length ? `Updated: ${m.fields.join(', ')}` : 'Task updated'
+    case 'task.moved':      return `Moved from ${m.from} → ${m.to}`
+    case 'task.branch_linked': return `Branch linked: ${m.headBranch}`
+    case 'comment.created': return 'Comment posted'
+    case 'approval.submitted': return `Sent for approval → ${m.reviewerName || 'reviewer'}`
+    case 'approval.approved':  return `Plan approved${m.note ? ': ' + m.note : ''}`
+    case 'approval.rejected':  return `Plan rejected${m.note ? ': ' + m.note : ''}`
+    case 'task.merged_from_github':      return `PR #${m.prNumber} merged → done`
+    case 'task.pr_opened_to_review':     return `PR #${m.prNumber} opened — moved to in_review`
+    case 'task.pr_linked_in_review':     return `PR #${m.prNumber} linked (already in review)`
+    case 'task.pr_changes_requested':    return `PR #${m.prNumber} — changes requested by ${m.reviewerLogin || 'reviewer'}`
+    case 'task.pr_closed_without_merge': return `PR #${m.prNumber} closed without merging`
+    case 'issue.created':   return `Issue logged: "${m.title || '?'}"`
+    case 'issue.updated':   return `Issue updated`
+    default:                return a.action
+  }
+}
+
 function registerProductivityTools(server) {
   server.tool(
     'generate_standup',
-    `Generate a daily standup for the current user.
-Fetches all assigned tasks and their recent activity, then formats:
-- What was done yesterday (based on activity + park notes)
-- What is planned today (in_progress / todo tasks)
-- Any blockers
+    `Generate a full daily standup — covers both the current user's tasks AND the entire project board.
 
-Call this when the developer says "prepare my standup", "what did I do yesterday", or opens Cursor in the morning.`,
+Returns:
+- yesterday: readable activity lines for the last 24 h per task
+- today: all active tasks grouped by assignee, sorted by priority (critical first)
+- blockers: park notes + tasks without branches/PRs that are overdue
+- risks: critical/high tasks with no branch, tasks with PR changes requested
+- copy-paste: a ready-to-post standup snippet
+
+Call this when the developer says "generate standup", "what did I do yesterday", or "morning standup".`,
     {},
     async () => {
-      // Fetch all my tasks
-      const tasksRes = await api.get('/api/users/me/tasks')
-      if (!tasksRes?.success) return errorText('Could not fetch tasks')
+      const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000)
+      const PRIORITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 }
+
+      // 1. Who am I?
+      const meRes = await api.get('/api/auth/me')
+      const me = meRes?.data?.user || {}
+
+      // 2. My tasks (all columns)
+      const myTasksRes = await api.get('/api/users/me/tasks')
+      const myTasks = myTasksRes?.data?.tasks || []
+
+      // 3. All my projects (to get project-wide board)
+      const projectsRes = await api.get('/api/projects')
+      const projects = projectsRes?.data?.projects || []
+
+      // 4. For each project, fetch full board to get all tasks (not just mine)
+      const projectBoards = await Promise.all(
+        projects.map(async (p) => {
+          try {
+            const r = await api.get(`/api/projects/${p._id}`)
+            return r?.data?.project || null
+          } catch { return null }
+        })
+      )
 
-      const tasks = tasksRes.data.tasks
-      if (!tasks.length) return text({ standup: 'No assigned tasks found.', tasks: [] })
+      // 5. Collect all unique tasks across all projects
+      const allTasksMap = new Map()
+      for (const board of projectBoards.filter(Boolean)) {
+        for (const t of (board.tasks || [])) {
+          allTasksMap.set(t._id, { ...t, projectName: board.name, projectId: board._id })
+        }
+      }
+      const allTasks = [...allTasksMap.values()]
 
-      // Fetch activity for each task (parallel)
+      // 6. Fetch recent activity for active tasks (parallel, capped at 20 tasks to avoid rate limits)
+      const activeTasks = allTasks.filter(t => ['in_progress', 'in_review', 'todo'].includes(t.column))
       const withActivity = await Promise.all(
-        tasks.map(async (t) => {
+        activeTasks.map(async (t) => {
           try {
-            const actRes = await api.get(`/api/tasks/${t._id}/activity`)
-            return { ...t, activity: actRes?.data?.activity || [] }
+            const r = await api.get(`/api/tasks/${t._id}/activity`)
+            const activity = r?.data?.activity || []
+            const recentLines = activity
+              .filter(a => new Date(a.createdAt) > yesterday)
+              .map(a => formatActivityLine(a))
+            return { ...t, recentActivityLines: recentLines, allActivity: activity }
           } catch {
-            return { ...t, activity: [] }
+            return { ...t, recentActivityLines: [], allActivity: [] }
           }
         })
       )
 
-      // Summarise for standup
-      const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000)
-      const standup = withActivity.map((t) => {
-        const recentActivity = t.activity.filter(
-          (a) => new Date(a.createdAt) > yesterday
-        )
-        return {
-          taskId:      t._id,
-          key:         t.key,
-          title:       t.title,
-          column:      t.column,
-          priority:    t.priority,
-          project:     t.project?.name,
-          parkNote:    t.parkNote,
-          recentActivity: recentActivity.map((a) => a.message || a.type),
+      // 7. Group by assignee
+      const byAssignee = {}
+      for (const t of withActivity) {
+        const assigneeList = (t.assignees || [])
+        if (!assigneeList.length) {
+          const key = 'Unassigned'
+          if (!byAssignee[key]) byAssignee[key] = []
+          byAssignee[key].push(t)
+        }
+        for (const a of assigneeList) {
+          const name = a.name || a.email || String(a)
+          if (!byAssignee[name]) byAssignee[name] = []
+          byAssignee[name].push(t)
+        }
+      }
+      // Sort each person's tasks by priority
+      for (const name of Object.keys(byAssignee)) {
+        byAssignee[name].sort((a, b) => (PRIORITY_ORDER[a.priority] ?? 99) - (PRIORITY_ORDER[b.priority] ?? 99))
+      }
+
+      // 8. Build "yesterday" section — tasks with recent activity
+      const yesterdayItems = withActivity
+        .filter(t => t.recentActivityLines.length > 0)
+        .map(t => ({
+          key:      t.key,
+          title:    t.title,
+          project:  t.projectName,
+          assignee: (t.assignees || []).map(a => a.name || a.email).join(', ') || 'Unassigned',
+          activity: t.recentActivityLines,
+        }))
+
+      // 9. Risks + blockers
+      const risks = []
+      for (const t of withActivity) {
+        if (t.priority === 'critical' && t.column === 'todo') {
+          risks.push(`⚠️  ${t.key} (${t.projectName}) — CRITICAL but still in todo — needs kickoff now`)
         }
+        if (t.priority === 'critical' && t.column === 'in_progress' && !t.github?.headBranch) {
+          risks.push(`⚠️  ${t.key} — CRITICAL, in_progress but no branch linked`)
+        }
+        if (t.github?.changesRequestedAt) {
+          risks.push(`🔁 ${t.key} — PR has changes requested — developer needs to fix and re-push`)
+        }
+        if (t.column === 'in_review' && !t.github?.prUrl) {
+          risks.push(`❓ ${t.key} — in_review column but no PR URL recorded`)
+        }
+      }
+
+      const blockers = withActivity
+        .filter(t => t.parkNote?.blockers && t.parkNote.blockers.trim())
+        .map(t => `${t.key}: ${t.parkNote.blockers}`)
+
+      // 10. My personal section (my tasks with readable status)
+      const mySection = myTasks
+        .filter(t => ['in_progress', 'in_review', 'todo'].includes(t.column))
+        .map(t => {
+          const status = t.github?.headBranch
+            ? (t.github.prUrl ? `PR open → ${t.github.prUrl}` : `branch: ${t.github.headBranch}, no PR yet`)
+            : 'no branch yet'
+          return `${t.key} — ${t.title} [${t.column}, ${t.priority}] — ${status}`
+        })
+
+      // 11. Copy-paste snippet
+      const todayFocus = Object.entries(byAssignee)
+        .map(([person, tasks]) => `  ${person}: ${tasks.map(t => `${t.key} (${t.priority})`).join(', ')}`)
+        .join('\n')
+      const copyPaste = [
+        `**Yesterday:** ${yesterdayItems.length
+          ? yesterdayItems.map(i => `${i.key} — ${i.activity.slice(0,2).join('; ')}`).join('. ')
+          : 'No recorded activity in last 24 h.'}`,
+        `**Today:**\n${todayFocus || '  No active tasks.'}`,
+        blockers.length ? `**Blockers:** ${blockers.join(' | ')}` : '**Blockers:** None.',
+        risks.length    ? `**Risks:** ${risks.join(' | ')}` : null,
+      ].filter(Boolean).join('\n')
+
+      return text({
+        me:          { name: me.name, email: me.email, role: me.role },
+        yesterday:   yesterdayItems.length ? yesterdayItems : '(no activity logged in last 24 h)',
+        today: {
+          byAssignee: Object.fromEntries(
+            Object.entries(byAssignee).map(([person, tasks]) => [
+              person,
+              tasks.map(t => ({
+                key:        t.key,
+                title:      t.title,
+                column:     t.column,
+                priority:   t.priority,
+                project:    t.projectName,
+                branch:     t.github?.headBranch || null,
+                prUrl:      t.github?.prUrl || null,
+                parkNote:   t.parkNote?.summary || null,
+                needsFix:   !!t.github?.changesRequestedAt,
+              }))
+            ])
+          ),
+        },
+        myTasks:     mySection,
+        blockers:    blockers.length ? blockers : ['None recorded'],
+        risks:       risks.length    ? risks    : ['None'],
+        copyPaste,
       })
+    }
+  )
+
+  // ── what_should_i_work_on ─────────────────────────────────────────────────────
+  server.tool(
+    'what_should_i_work_on',
+    `Recommend the single most important task to work on right now.
+
+Scores all assigned tasks by: priority, urgency (PR needs fix), column state, branch readiness.
+Returns the #1 pick with a clear reason and the exact next MCP call to make.
+
+Use this when the developer says "what should I do next", "I'm free", or "what's my priority".`,
+    {},
+    async () => {
+      const res = await api.get('/api/users/me/tasks')
+      if (!res?.success) return errorText('Could not fetch tasks')
+      const tasks = (res.data.tasks || []).filter(t => t.column !== 'done')
+
+      if (!tasks.length) return text({ recommendation: 'No open tasks assigned to you. Ask your project lead for work.' })
+
+      function scoreTask(t) {
+        const PRIORITY = { critical: 100, high: 60, medium: 30, low: 10 }
+        let score = PRIORITY[t.priority] ?? 0
+        if (t.github?.changesRequestedAt)  score += 80  // PR needs fix — most urgent
+        if (t.column === 'in_progress')    score += 25  // already in flight, keep momentum
+        if (t.column === 'in_review')      score += 10  // waiting on reviewer, low action needed
+        if (t.column === 'todo')           score += 15  // ready to start
+        if (t.column === 'backlog')        score -= 10  // not yet planned
+        if (t.parkNote?.parkedAt)          score -= 20  // intentionally paused
+        if (t.github?.headBranch)          score += 5   // branch already set up
+        return score
+      }
 
-      return text({ standup })
+      const scored = tasks
+        .map(t => ({ ...t, _score: scoreTask(t) }))
+        .sort((a, b) => b._score - a._score)
+
+      const top = scored[0]
+
+      // Build the reason and next step
+      let reason, nextStep
+      if (top.github?.changesRequestedAt) {
+        reason   = `PR has changes requested — this blocks the merge and the reviewer is waiting.`
+        nextStep = `Call fix_pr_feedback with taskAId="${top._id}" to get the full fix plan.`
+      } else if (top.column === 'in_progress' && top.github?.headBranch) {
+        reason   = `Already in progress on branch ${top.github.headBranch} — keep the momentum going.`
+        nextStep = `Continue coding on ${top.github.headBranch}. When commits are pushed, call raise_pr.`
+      } else if (top.column === 'in_progress' && !top.github?.headBranch) {
+        reason   = `In progress but no branch yet — needs a branch to start committing.`
+        nextStep = `Call create_branch with taskId="${top._id}" and projectId="${top.project?._id || top.project}".`
+      } else if (top.column === 'todo') {
+        reason   = `Highest priority unstarted task — ready to kick off.`
+        nextStep = `Call kickoff_task with taskId="${top._id}" to read the plan and move to in_progress.`
+      } else {
+        reason   = `Highest priority available task.`
+        nextStep = `Call get_task_context with taskId="${top._id}" for full details.`
+      }
+
+      // Show the queue (top 3)
+      const queue = scored.slice(0, 3).map((t, i) => ({
+        rank:     i + 1,
+        key:      t.key,
+        title:    t.title,
+        priority: t.priority,
+        column:   t.column,
+        score:    t._score,
+        branch:   t.github?.headBranch || null,
+        needsFix: !!t.github?.changesRequestedAt,
+      }))
+
+      return text({
+        recommendation: {
+          taskId:   top._id,
+          key:      top.key,
+          title:    top.title,
+          priority: top.priority,
+          column:   top.column,
+          project:  top.project?.name || top.project,
+          reason,
+          nextStep,
+        },
+        queue,
+      })
+    }
+  )
+
+  // ── task_health_check ────────────────────────────────────────────────────────
+  server.tool(
+    'task_health_check',
+    `Scan the entire project board for health issues and surface them with severity levels.
+
+Detects:
+- Critical tasks sitting in todo without a branch (needs kickoff now)
+- Tasks in review for 3+ days (reviewer may be stuck)
+- Tasks in progress for 2+ days with no updates (possibly stale or blocked)
+- In-progress tasks with no branch linked
+- Active tasks with no README/implementation plan
+- PRs with changes requested that haven't been fixed
+
+Use this when the developer or team lead asks "how's the board?", "any blockers?", or for a weekly health review.`,
+    {},
+    async () => {
+      const projectsRes = await api.get('/api/projects')
+      const projects = projectsRes?.data?.projects || []
+
+      const boards = await Promise.all(
+        projects.map(async p => {
+          try {
+            const r = await api.get(`/api/projects/${p._id}`)
+            return r?.data?.project || null
+          } catch { return null }
+        })
+      )
+
+      const now = Date.now()
+      const MS_PER_DAY = 1000 * 60 * 60 * 24
+      const flags = []
+
+      for (const board of boards.filter(Boolean)) {
+        for (const t of (board.tasks || [])) {
+          if (t.column === 'done') continue
+          const ageDays = (now - new Date(t.updatedAt).getTime()) / MS_PER_DAY
+          const assignees = (t.assignees || []).map(a => a.name || a.email).join(', ') || 'Unassigned'
+
+          // PR changes requested — top priority
+          if (t.github?.changesRequestedAt) {
+            const daysSince = (now - new Date(t.github.changesRequestedAt).getTime()) / MS_PER_DAY
+            flags.push({
+              severity:   'critical',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      `PR has had changes requested for ${Math.floor(daysSince)} day(s) — developer needs to fix and re-push`,
+              suggestion: `Use fix_pr_feedback with taskAId="${t._id}"`,
+            })
+          }
+
+          // Critical task stuck in todo
+          if (t.priority === 'critical' && t.column === 'todo') {
+            flags.push({
+              severity:   'critical',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      `CRITICAL priority — stuck in todo for ${Math.floor(ageDays)} day(s)`,
+              suggestion: `Use kickoff_task with taskId="${t._id}" to start immediately`,
+            })
+          }
+
+          // High priority in todo for more than 1 day
+          if (t.priority === 'high' && t.column === 'todo' && ageDays > 1) {
+            flags.push({
+              severity:   'warning',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      `HIGH priority — in todo for ${Math.floor(ageDays)} day(s) without being started`,
+              suggestion: `Use kickoff_task to start`,
+            })
+          }
+
+          // In review for 3+ days
+          if (t.column === 'in_review' && ageDays > 3) {
+            flags.push({
+              severity:   'warning',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      `In review for ${Math.floor(ageDays)} days — reviewer may be stuck or PR is forgotten`,
+              suggestion: `Check PR status on GitHub or ping the reviewer`,
+            })
+          }
+
+          // In progress for 2+ days with no updates
+          if (t.column === 'in_progress' && ageDays > 2) {
+            flags.push({
+              severity:   'warning',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      `In progress for ${Math.floor(ageDays)} day(s) with no board updates — possibly stale or silently blocked`,
+              suggestion: `Ask ${assignees} for a status update or check git log on ${t.github?.headBranch || 'their branch'}`,
+            })
+          }
+
+          // In progress but no branch linked
+          if (t.column === 'in_progress' && !t.github?.headBranch) {
+            flags.push({
+              severity:   'warning',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      'In progress but no branch linked — commits may be going to the wrong branch',
+              suggestion: `Use create_branch with taskId="${t._id}" to create and link a branch`,
+            })
+          }
+
+          // Active task with no README
+          if (['in_progress', 'in_review'].includes(t.column) && !t.readmeMarkdown?.trim()) {
+            flags.push({
+              severity:   'info',
+              task:       t.key,
+              title:      t.title,
+              project:    board.name,
+              assignee:   assignees,
+              issue:      'No implementation plan (README) — harder to review and hard to resume if parked',
+              suggestion: `Use update_task to add a readmeMarkdown implementation plan`,
+            })
+          }
+        }
+      }
+
+      // Sort: critical → warning → info
+      const SEV = { critical: 0, warning: 1, info: 2 }
+      flags.sort((a, b) => (SEV[a.severity] ?? 9) - (SEV[b.severity] ?? 9))
+
+      const counts = {
+        critical: flags.filter(f => f.severity === 'critical').length,
+        warning:  flags.filter(f => f.severity === 'warning').length,
+        info:     flags.filter(f => f.severity === 'info').length,
+      }
+
+      return text({
+        summary: flags.length === 0
+          ? '✅ Board is healthy — no issues found.'
+          : `⚠️  ${flags.length} issue(s): ${counts.critical} critical, ${counts.warning} warnings, ${counts.info} info`,
+        counts,
+        flags,
+        healthy: flags.length === 0,
+      })
     }
   )
 
@@ -962,18 +1339,43 @@ Use this when returning to a task after a break, or when Claude needs the full p
 
       let coachingPrompt = null
       if (task.column === 'in_progress' && !task.github?.headBranch) {
-        const stateHint = localGitState?.state === 'modified'
-          ? ` Your working tree has ${localGitState.modifiedFiles.length} modified file(s) — stash or commit them first, then call create_branch.`
-          : ` Your working tree is ${localGitState?.state || 'unknown'} — ready to call create_branch.`
-        coachingPrompt = `No branch yet.${stateHint}`
+        let stateHint
+        if (localGitState?.state === 'modified') {
+          const files = localGitState.modifiedFiles.join(', ')
+          stateHint = [
+            `You have ${localGitState.modifiedFiles.length} modified file(s): ${files}`,
+            `Before creating the task branch, handle these changes — pick one:`,
+            `  Option A — Stash (recommended, keeps changes safe):`,
+            `    git stash push -m "wip: before starting ${task.key}"`,
+            `  Option B — Commit as WIP:`,
+            `    git add . && git commit -m "chore: wip before ${task.key}"`,
+            `Then call create_branch — it will detect the clean state automatically.`,
+          ].join('\n')
+        } else {
+          stateHint = `Your working tree is ${localGitState?.state || 'unknown'} — ready to call create_branch.`
+        }
+        coachingPrompt = `No branch yet.\n${stateHint}`
       } else if (task.column === 'in_progress' && task.github?.headBranch) {
         const onBranch = localGitState?.onTaskBranch
-        const branchHint = onBranch === true
-          ? ` (you are already on it)`
-          : onBranch === false
-            ? ` (you are on "${localGitState?.currentBranch}" — run: git checkout ${task.github.headBranch})`
-            : ''
-        coachingPrompt = `Branch: ${task.github.headBranch}${branchHint}. When commits are pushed, use raise_pr to open a PR.`
+        if (onBranch === false) {
+          const lines = [
+            `Branch exists: ${task.github.headBranch}`,
+            `You are currently on "${localGitState?.currentBranch}".`,
+          ]
+          if (localGitState?.state === 'modified') {
+            lines.push(`You have ${localGitState.modifiedFiles.length} modified file(s): ${localGitState.modifiedFiles.join(', ')}`)
+            lines.push(`Handle them before switching:`)
+            lines.push(`  git stash push -m "wip: switching to ${task.github.headBranch}"`)
+            lines.push(`  — or — git add . && git commit -m "chore: wip"`)
+            lines.push(`Then switch:  git fetch origin && git checkout ${task.github.headBranch}`)
+          } else {
+            lines.push(`Switch to the task branch:  git fetch origin && git checkout ${task.github.headBranch}`)
+          }
+          lines.push(`When commits are pushed, use raise_pr.`)
+          coachingPrompt = lines.join('\n')
+        } else {
+          coachingPrompt = `Branch: ${task.github.headBranch}${onBranch === true ? ' (you are already on it)' : ''}. When commits are pushed, use raise_pr to open a PR.`
+        }
       } else if (task.column === 'in_review') {
         coachingPrompt = `PR #${task.github?.prNumber} is open. Waiting for reviewer feedback.`
       } else if (task.parkNote?.parkedAt) {
@@ -1117,12 +1519,17 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
         })
       }
 
-      // Step 3 — create branch on GitHub
+      // Step 3 — create branch on GitHub, then link it to the task
       const localState = gitState?.localState || 'unknown'
       try {
         const res = await api.post(`/api/projects/${projectId}/github/branches`, { branchName, fromRef })
         if (!res?.success) return errorText(res?.message || 'Could not create branch')
 
+        // Link the branch name back to the task so get_task_context / list_my_tasks reflect it immediately
+        try {
+          await api.patch(`/api/tasks/${taskId}/github/branch`, { headBranch: branchName })
+        } catch { /* non-fatal — branch was still created on GitHub */ }
+
         const checkoutSteps = [
           'git fetch origin',
           `git checkout ${branchName}`,
@@ -1440,6 +1847,231 @@ Set confirmed=false first to preview the full PR content, then confirmed=true to
       }
     }
   )
+
+  // ── commit_helper ─────────────────────────────────────────────────────────────
+  server.tool(
+    'commit_helper',
+    `Analyse local git changes and suggest a ready-to-run conventional commit command.
+
+Reads git diff --stat and git status locally — no manual commands needed.
+Generates a commit message following: <type>(<scope>): <description>
+  type  = feat | fix | refactor | chore | docs | test | style
+  scope = task key (e.g. TASK-003) when taskId is provided
+
+Set confirmed=false to preview the suggested message, confirmed=true to get the final copy-paste command.
+
+Use this when the developer asks "help me commit", "what should my commit message be", or "how do I commit this".`,
+    {
+      taskId:    z.string().optional().describe("Task's MongoDB ObjectId — used to set the commit scope to the task key"),
+      repoPath:  z.string().optional().describe('Absolute path to the local git repo (defaults to MCP process working directory)'),
+      confirmed: z.boolean().optional().default(false).describe('Set true to get the final runnable command'),
+    },
+    async ({ taskId, repoPath, confirmed = false }) => {
+      const cwd = repoPath || process.cwd()
+
+      // Read local git state
+      let porcelain = '', diffStat = '', currentBranch = ''
+      try {
+        porcelain     = runGit('status --porcelain=v1', cwd)
+        diffStat      = runGit('diff --stat HEAD', cwd)
+        currentBranch = runGit('branch --show-current', cwd)
+      } catch (e) {
+        return errorText(`Could not read git state: ${e.message.split('\n')[0]}`)
+      }
+
+      const { staged, unstaged, untracked, modified } = parseGitStatus(porcelain)
+
+      if (modified.length === 0 && untracked.length === 0) {
+        return text({ message: 'Nothing to commit — working tree is clean.', currentBranch })
+      }
+
+      // Fetch task context for scope/type hints
+      let task = null
+      if (taskId) {
+        try {
+          const r = await api.get(`/api/tasks/${taskId}`)
+          if (r?.success) task = r.data.task
+        } catch { /* non-fatal */ }
+      }
+
+      // Infer commit type from branch name + diff content
+      const branchLower = currentBranch.toLowerCase()
+      const diffLower   = diffStat.toLowerCase()
+      let commitType = 'chore'
+      if (branchLower.startsWith('feature/') || branchLower.startsWith('feat/'))      commitType = 'feat'
+      else if (branchLower.startsWith('fix/') || branchLower.startsWith('hotfix/'))   commitType = 'fix'
+      else if (branchLower.startsWith('refactor/'))                                   commitType = 'refactor'
+      else if (branchLower.startsWith('docs/'))                                       commitType = 'docs'
+      else if (branchLower.startsWith('test/'))                                       commitType = 'test'
+      else if (diffLower.includes('test') || diffLower.includes('spec'))              commitType = 'test'
+      else if (diffLower.includes('readme') || diffLower.includes('.md'))             commitType = 'docs'
+      else if (task) {
+        const titleLower = (task.title || '').toLowerCase()
+        if (/\b(fix|bug|hotfix|patch)\b/.test(titleLower)) commitType = 'fix'
+        else if (/\b(refactor|cleanup|clean up)\b/.test(titleLower)) commitType = 'refactor'
+        else commitType = 'feat'
+      }
+
+      // Build scope
+      const scope = task?.key?.toLowerCase() || ''
+
+      // Build description from task title or changed files
+      let description = ''
+      if (task) {
+        description = task.title
+          .toLowerCase()
+          .replace(/[^a-z0-9 ]+/g, '')
+          .replace(/\s+/g, ' ')
+          .trim()
+          .slice(0, 60)
+      } else {
+        // Summarise from changed files
+        const allFiles = [...modified, ...untracked]
+        if (allFiles.length === 1) {
+          description = `update ${allFiles[0].split('/').pop()}`
+        } else {
+          description = `update ${allFiles.length} file(s)`
+        }
+      }
+
+      const commitMsg  = scope
+        ? `${commitType}(${scope}): ${description}`
+        : `${commitType}: ${description}`
+
+      // Staged vs not staged — build the right add command
+      const hasUnstaged  = unstaged.length > 0 || untracked.length > 0
+      const hasStaged    = staged.length > 0
+      const addCmd       = hasUnstaged ? 'git add .' : null
+      const commitCmd    = `git commit -m "${commitMsg}"`
+      const pushCmd      = `git push origin ${currentBranch}`
+
+      const changedFiles = [
+        ...staged.map(f => `  staged:    ${f.file}`),
+        ...unstaged.map(f => `  unstaged:  ${f.file}`),
+        ...untracked.map(f => `  untracked: ${f}`),
+      ]
+
+      if (!confirmed) {
+        return text({
+          preview: {
+            suggestedMessage: commitMsg,
+            type:        commitType,
+            scope,
+            description,
+            currentBranch,
+            changedFiles,
+            diffSummary: diffStat || '(no tracked changes yet)',
+          },
+          commands: [addCmd, commitCmd, pushCmd].filter(Boolean),
+          requiresConfirmation: true,
+          message: `Suggested commit message: "${commitMsg}". Call commit_helper again with confirmed=true to get the final runnable commands.`,
+          tip: 'You can edit the description before running — the type and scope are auto-detected but the description can be more specific.',
+        })
+      }
+
+      return text({
+        commitMessage: commitMsg,
+        commands:      [addCmd, commitCmd, pushCmd].filter(Boolean),
+        changedFiles,
+        message:       `Copy-paste these commands in order. Edit the commit message description if needed before running.`,
+        nextStep:      'After pushing, call raise_pr to open the pull request.',
+      })
+    }
+  )
+
+  // ── branch_cleanup ────────────────────────────────────────────────────────────
+  server.tool(
+    'branch_cleanup',
+    `Find merged branches that are safe to delete — both on GitHub and locally.
+
+Checks GitHub branches against tasks that have been merged (github.mergedAt set).
+Also runs "git branch --merged origin/main" locally to find stale local branches.
+
+Set confirmed=false to preview the list, confirmed=true to get the exact delete commands.
+
+Use this when the developer says "clean up branches", "delete merged branches", or after a sprint ends.`,
+    {
+      projectId: z.string().describe("Project's MongoDB ObjectId"),
+      repoPath:  z.string().optional().describe('Absolute path to the local git repo'),
+      confirmed: z.boolean().optional().default(false).describe('Set true to get the delete commands'),
+    },
+    async ({ projectId, repoPath, confirmed = false }) => {
+      if (scopedProjectId && projectId !== scopedProjectId) {
+        return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
+      }
+
+      // Fetch GitHub branches
+      const branchesRes = await api.get(`/api/projects/${projectId}/github/branches`)
+      if (!branchesRes?.success) return errorText('Could not fetch GitHub branches')
+      const remoteBranches = (branchesRes.data.branches || []).map(b => b.name || b)
+
+      // Fetch all tasks to find which branches are merged
+      const projectRes = await api.get(`/api/projects/${projectId}`)
+      const tasks = projectRes?.data?.project?.tasks || []
+      const defaultBranch = projectRes?.data?.project?.githubDefaultBranch || 'main'
+
+      // Branches linked to merged tasks
+      const mergedTaskBranches = new Set(
+        tasks
+          .filter(t => t.github?.mergedAt && t.github?.headBranch)
+          .map(t => t.github.headBranch)
+      )
+
+      // Remote branches safe to delete (merged task branch, not the default branch)
+      const remoteToDelete = remoteBranches.filter(b =>
+        mergedTaskBranches.has(b) && b !== defaultBranch && b !== 'main' && b !== 'master' && b !== 'dev'
+      )
+
+      // Local merged branches
+      const cwd = repoPath || process.cwd()
+      let localMerged = []
+      try {
+        const localRaw = runGit(`branch --merged origin/${defaultBranch}`, cwd)
+        localMerged = localRaw
+          .split('\n')
+          .map(b => b.replace(/^\*?\s+/, '').trim())
+          .filter(b => b && b !== defaultBranch && b !== 'main' && b !== 'master' && b !== 'dev')
+      } catch { /* git may not be available or no upstream */ }
+
+      if (!confirmed) {
+        return text({
+          preview: {
+            remoteBranchesToDelete: remoteToDelete,
+            localBranchesToDelete:  localMerged,
+            defaultBranch,
+            remoteCount: remoteToDelete.length,
+            localCount:  localMerged.length,
+          },
+          requiresConfirmation: true,
+          message: remoteToDelete.length === 0 && localMerged.length === 0
+            ? 'No merged branches found to clean up. Repository is already clean.'
+            : `Found ${remoteToDelete.length} remote and ${localMerged.length} local branch(es) to delete. Call branch_cleanup again with confirmed=true to get the delete commands.`,
+          safetyNote: 'Only branches linked to tasks with a merged PR are included. Default branch, main, master, and dev are always excluded.',
+        })
+      }
+
+      const remoteDeleteCmds = remoteToDelete.map(b => `git push origin --delete ${b}`)
+      const localDeleteCmds  = localMerged.map(b => `git branch -d ${b}`)
+      const allCmds = [
+        '# Fetch latest remote state first',
+        `git fetch origin --prune`,
+        '',
+        remoteDeleteCmds.length ? '# Delete merged remote branches' : null,
+        ...remoteDeleteCmds,
+        '',
+        localDeleteCmds.length ? '# Delete merged local branches' : null,
+        ...localDeleteCmds,
+      ].filter(v => v !== null)
+
+      return text({
+        commands:              allCmds,
+        remoteBranchesDeleted: remoteToDelete,
+        localBranchesDeleted:  localMerged,
+        message: `Run the commands above to clean up ${remoteToDelete.length} remote and ${localMerged.length} local branch(es).`,
+        tip: 'git fetch --prune also removes stale remote-tracking refs automatically.',
+      })
+    }
+  )
 }
 
 function registerAdminTools(server) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "internaltool-mcp",
-  "version": "1.5.5",
+  "version": "1.6.0",
   "description": "MCP server for InternalTool — connect AI assistants (Claude Code, Cursor) to your project and task management platform",
   "type": "module",
   "main": "index.js",