internaltool-mcp 1.4.0 → 1.5.1

package/index.js

@@ -264,14 +264,30 @@ function registerTaskTools(server, { isAdmin, scopedProjectId }) {
 
   server.tool(
     'move_task',
-    'Move a task to a different column. Requires approved README to move from planning to execution columns.',
+    'Move a task to a different column. Requires approved README to move from planning to execution columns. Set confirmed=false first to preview.',
     {
-      taskId:  z.string().describe("Task's MongoDB ObjectId"),
-      column:  z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done']),
-      toIndex: z.number().int().min(0).default(0).describe('Position in column (0 = top)'),
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+      column:    z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done']),
+      toIndex:   z.number().int().min(0).default(0).describe('Position in column (0 = top)'),
+      confirmed: z.boolean().optional().default(false).describe('Set true to execute after reviewing the preview'),
     },
-    async ({ taskId, column, toIndex }) =>
-      call(() => api.post(`/api/tasks/${taskId}/move`, { column, toIndex }))
+    async ({ taskId, column, toIndex, confirmed = false }) => {
+      if (!confirmed) {
+        const taskRes = await api.get(`/api/tasks/${taskId}`)
+        const task    = taskRes?.data?.task
+        return text({
+          preview: {
+            action:      'move_task',
+            task:        task ? { key: task.key, title: task.title, currentColumn: task.column } : { taskId },
+            moveTo:      column,
+            atPosition:  toIndex,
+          },
+          requiresConfirmation: true,
+          message: `This will move the task to "${column}". Call move_task again with confirmed=true to proceed.`,
+        })
+      }
+      return call(() => api.post(`/api/tasks/${taskId}/move`, { column, toIndex }))
+    }
   )
 
   server.tool(
@@ -286,22 +302,56 @@ function registerTaskTools(server, { isAdmin, scopedProjectId }) {
     `Pause a task and save your current work context.
 IMPORTANT: Before calling this, run "git diff HEAD" and "git status" in the terminal to see what has changed.
 Use that output to write precise summary/remaining/blockers fields — not generic text.
-This is the developer's saved mental state; make it detailed enough to resume cold tomorrow.`,
+This is the developer's saved mental state; make it detailed enough to resume cold tomorrow.
+
+Set confirmed=false first to preview, then confirmed=true to actually save.`,
     {
       taskId:    z.string().describe("Task's MongoDB ObjectId"),
       summary:   z.string().optional().describe('What was built/changed — include file names and what was done'),
       remaining: z.string().optional().describe('Specific next steps to complete this task'),
       blockers:  z.string().optional().describe('Anything blocking progress'),
+      confirmed: z.boolean().optional().default(false).describe('Set true to execute after reviewing the preview'),
     },
-    async ({ taskId, summary = '', remaining = '', blockers = '' }) =>
-      call(() => api.patch(`/api/tasks/${taskId}/park`, { summary, remaining, blockers }))
+    async ({ taskId, summary = '', remaining = '', blockers = '', confirmed = false }) => {
+      if (!confirmed) {
+        return text({
+          preview: {
+            action:    'park_task',
+            taskId,
+            willSave:  { summary: summary || '(empty)', remaining: remaining || '(empty)', blockers: blockers || '(empty)' },
+          },
+          requiresConfirmation: true,
+          message: 'Review the park note above. Call park_task again with confirmed=true to save it.',
+        })
+      }
+      return call(() => api.patch(`/api/tasks/${taskId}/park`, { summary, remaining, blockers }))
+    }
   )
 
   server.tool(
     'unpark_task',
-    'Resume a parked task.',
-    { taskId: z.string().describe("Task's MongoDB ObjectId") },
-    async ({ taskId }) => call(() => api.patch(`/api/tasks/${taskId}/unpark`, {}))
+    'Resume a parked task. Set confirmed=false first to preview, then confirmed=true to execute.',
+    {
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+      confirmed: z.boolean().optional().default(false).describe('Set true to execute after reviewing the preview'),
+    },
+    async ({ taskId, confirmed = false }) => {
+      if (!confirmed) {
+        const taskRes = await api.get(`/api/tasks/${taskId}`)
+        const task    = taskRes?.data?.task
+        return text({
+          preview: {
+            action:    'unpark_task',
+            taskId,
+            task:      task ? { key: task.key, title: task.title, parkNote: task.parkNote } : null,
+            willDo:    'Clear park note and mark task as active again',
+          },
+          requiresConfirmation: true,
+          message: 'Call unpark_task again with confirmed=true to resume this task.',
+        })
+      }
+      return call(() => api.patch(`/api/tasks/${taskId}/unpark`, {}))
+    }
   )
 }
 
@@ -398,62 +448,100 @@ Use this when the developer says "wrap up", "end of day", or "I'm done for today
 
   server.tool(
     'kickoff_task',
-    `Kick off a task — brief the developer and move it to in_progress.
-Fetches the full task details plus recent project commits for context.
-Returns everything needed to start: task plan, what recently changed in the repo, and the git branch command to run.
+    `Kick off a task — read the implementation plan (README) and brief the developer, then move the task to in_progress.
+
+The README/implementation plan IS the brief. Always read it fully and present it to the developer
+before they write a single line of code. If no README exists, warn the developer that the plan is
+missing and suggest they write one before starting.
+
+Workflow:
+1. confirmed=false  → show the full README brief + subtask checklist so developer can read the plan
+2. confirmed=true   → move task to in_progress, return branch name and recent repo commits
+
 Use this when a developer says "start task", "brief me on", or "what do I need to do for TASK-X".`,
     {
-      taskId: z.string().describe("Task's MongoDB ObjectId"),
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+      confirmed: z.boolean().optional().default(false).describe('Set true after reading the plan to move the task to in_progress'),
     },
-    async ({ taskId }) => {
-      // Get full task
+    async ({ taskId, confirmed = false }) => {
       const taskRes = await api.get(`/api/tasks/${taskId}`)
       if (!taskRes?.success) return errorText('Task not found')
       const task = taskRes.data.task
 
-      // Get recent commits from the project
+      const suggestedBranch = `feature/${task.key?.toLowerCase()}-${task.title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .slice(0, 40)}`
+
+      const hasReadme   = !!(task.readmeMarkdown && task.readmeMarkdown.trim().length > 0)
+      const subtasks    = (task.subtasks || []).map(s => ({
+        title: s.title,
+        done:  s.done,
+        status: s.done ? '✅' : '⬜',
+      }))
+      const subtasksDone  = subtasks.filter(s => s.done).length
+      const subtasksTotal = subtasks.length
+
+      // ── Preview: show the full plan before touching anything ──
+      if (!confirmed) {
+        return text({
+          brief: {
+            key:         task.key,
+            title:       task.title,
+            priority:    task.priority,
+            description: task.description || '(no description)',
+            // The implementation plan — Claude must read and present this to the developer
+            implementationPlan: hasReadme
+              ? task.readmeMarkdown
+              : '⚠️  No implementation plan (README) found for this task. The developer should write one before starting work.',
+            subtasks: subtasksTotal > 0
+              ? { items: subtasks, progress: `${subtasksDone}/${subtasksTotal} done` }
+              : null,
+            approvalState: task.approval?.state || 'none',
+          },
+          meta: {
+            currentColumn:  task.column,
+            willMoveTo:     'in_progress',
+            suggestedBranch,
+          },
+          requiresConfirmation: true,
+          message: hasReadme
+            ? `Read the implementation plan above carefully, then call kickoff_task again with confirmed=true to start the task.`
+            : `⚠️ This task has no implementation plan. Consider writing one first (use update_task with readmeMarkdown), then confirm to start anyway.`,
+        })
+      }
+
+      // ── Confirmed: move to in_progress and fetch recent commits ──
       let recentCommits = []
       try {
-        const commitsRes = await api.get(
-          `/api/projects/${task.project}/github/commits?per_page=10`
-        )
+        const commitsRes = await api.get(`/api/projects/${task.project}/github/commits?per_page=10`)
         if (commitsRes?.success) recentCommits = commitsRes.data.commits || []
       } catch { /* GitHub may not be linked */ }
 
-      // Move to in_progress
       let moved = false
       try {
-        const moveRes = await api.post(`/api/tasks/${taskId}/move`, {
-          column: 'in_progress',
-          toIndex: 0,
-        })
+        const moveRes = await api.post(`/api/tasks/${taskId}/move`, { column: 'in_progress', toIndex: 0 })
         moved = moveRes?.success ?? false
       } catch { /* might already be in_progress */ }
 
       return text({
-        task: {
-          id:          task._id,
-          key:         task.key,
-          title:       task.title,
-          description: task.description,
-          priority:    task.priority,
-          column:      moved ? 'in_progress' : task.column,
-          readme:      task.readmeMarkdown,
-          subtasks:    task.subtasks,
-          parkNote:    task.parkNote,
-          approval:    task.approval,
+        started: {
+          key:      task.key,
+          title:    task.title,
+          priority: task.priority,
+          column:   moved ? 'in_progress' : task.column,
+          subtasks,
         },
-        recentCommits: recentCommits.slice(0, 5).map((c) => ({
+        implementationPlan: hasReadme ? task.readmeMarkdown : null,
+        recentCommits: recentCommits.slice(0, 5).map(c => ({
           sha:     c.sha?.slice(0, 7),
           message: c.commit?.message?.split('\n')[0],
           author:  c.commit?.author?.name,
           date:    c.commit?.author?.date,
         })),
         movedToInProgress: moved,
-        suggestedBranch: `feature/${task.key?.toLowerCase()}-${task.title
-          .toLowerCase()
-          .replace(/[^a-z0-9]+/g, '-')
-          .slice(0, 40)}`,
+        suggestedBranch,
+        nextStep: `Use create_branch to create "${suggestedBranch}" on GitHub, then run:\n  git fetch origin\n  git checkout ${suggestedBranch}`,
       })
     }
   )
@@ -509,14 +597,17 @@ Call this when the developer asks "what have I been neglecting" or "any stale ta
     'link_pr_to_task',
     `Link a pull request to a task, post a comment, and move the task to in_review.
 Use this when a developer pushes a branch and opens a PR.
-Keeps the board in sync with git automatically.`,
+Keeps the board in sync with git automatically.
+
+Set confirmed=false first to preview, then confirmed=true to execute.`,
     {
       taskId:    z.string().describe("Task's MongoDB ObjectId"),
       prUrl:     z.string().describe('Full GitHub PR URL'),
       prTitle:   z.string().optional().describe('PR title'),
       branch:    z.string().optional().describe('Branch name'),
+      confirmed: z.boolean().optional().default(false).describe('Set true to execute after reviewing the preview'),
     },
-    async ({ taskId, prUrl, prTitle, branch }) => {
+    async ({ taskId, prUrl, prTitle, branch, confirmed = false }) => {
       const commentBody = [
         `## Pull Request Opened`,
         `**PR:** [${prTitle || prUrl}](${prUrl})`,
@@ -524,16 +615,23 @@ Keeps the board in sync with git automatically.`,
         `**Status:** Ready for review`,
       ].filter(Boolean).join('\n')
 
-      // Post comment
-      const commentRes = await api.post(`/api/tasks/${taskId}/comments`, {
-        body: commentBody,
-      })
+      if (!confirmed) {
+        const taskRes = await api.get(`/api/tasks/${taskId}`)
+        const task    = taskRes?.data?.task
+        return text({
+          preview: {
+            action:       'link_pr_to_task',
+            task:         task ? { key: task.key, title: task.title } : { taskId },
+            willPost:     commentBody,
+            willMoveTo:   'in_review',
+          },
+          requiresConfirmation: true,
+          message: 'This will post the comment above and move the task to in_review. Call link_pr_to_task again with confirmed=true to proceed.',
+        })
+      }
 
-      // Move to in_review
-      const moveRes = await api.post(`/api/tasks/${taskId}/move`, {
-        column: 'in_review',
-        toIndex: 0,
-      })
+      const commentRes = await api.post(`/api/tasks/${taskId}/comments`, { body: commentBody })
+      const moveRes    = await api.post(`/api/tasks/${taskId}/move`, { column: 'in_review', toIndex: 0 })
 
       return text({
         commented:      commentRes?.success ?? false,
@@ -677,6 +775,472 @@ function registerGithubTools(server, { scopedProjectId }) {
   )
 }
 
+// ── Git Workflow Tools ─────────────────────────────────────────────────────────
+// All write operations require confirmed=true after showing a preview.
+// This gives developers full visibility before anything is executed.
+
+function registerGitWorkflowTools(server, { scopedProjectId } = {}) {
+
+  // ── list_my_tasks ────────────────────────────────────────────────────────────
+  server.tool(
+    'list_my_tasks',
+    `List your assigned tasks sorted by priority (critical → high → medium → low).
+Each task includes a suggested next git action so Claude can guide you step by step.
+Use this at the start of a session or when switching tasks.`,
+    {
+      includeColumns: z.array(
+        z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done'])
+      ).optional().default(['todo', 'in_progress', 'in_review'])
+       .describe('Which columns to include. Default excludes backlog and done.'),
+    },
+    async ({ includeColumns = ['todo', 'in_progress', 'in_review'] } = {}) => {
+      const res = await api.get('/api/users/me/tasks')
+      if (!res?.success) return errorText('Could not fetch tasks')
+
+      const PRIORITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 }
+      const tasks = (res.data.tasks || [])
+        .filter(t => includeColumns.includes(t.column))
+        .sort((a, b) => (PRIORITY_ORDER[a.priority] ?? 99) - (PRIORITY_ORDER[b.priority] ?? 99))
+        .map(t => {
+          let suggestedAction = null
+          if (t.column === 'todo') {
+            suggestedAction = 'Use kickoff_task to start — it will brief you and move the task to in_progress'
+          } else if (t.column === 'in_progress' && !t.github?.headBranch) {
+            suggestedAction = 'No branch yet — use create_branch to create one before coding'
+          } else if (t.column === 'in_progress' && t.github?.headBranch) {
+            suggestedAction = `Branch exists (${t.github.headBranch}). Pushed commits? Use raise_pr to open a PR`
+          } else if (t.column === 'in_review') {
+            suggestedAction = `PR #${t.github?.prNumber || '?'} is open — waiting for reviewer feedback`
+          }
+          return {
+            id:             t._id,
+            key:            t.key,
+            title:          t.title,
+            column:         t.column,
+            priority:       t.priority,
+            project:        t.project?.name || t.project,
+            github:         t.github ? { headBranch: t.github.headBranch, prNumber: t.github.prNumber, mergedAt: t.github.mergedAt } : null,
+            parked:         !!t.parkNote?.parkedAt,
+            suggestedAction,
+          }
+        })
+
+      return text({ tasks, count: tasks.length })
+    }
+  )
+
+  // ── get_task_context ─────────────────────────────────────────────────────────
+  server.tool(
+    'get_task_context',
+    `Get everything needed to resume a task: full details, park notes, recent activity, and git state.
+Use this when returning to a task after a break, or when Claude needs the full picture before suggesting next steps.`,
+    {
+      taskId: z.string().describe("Task's MongoDB ObjectId"),
+    },
+    async ({ taskId }) => {
+      const [taskRes, activityRes] = await Promise.all([
+        api.get(`/api/tasks/${taskId}`),
+        api.get(`/api/tasks/${taskId}/activity`).catch(() => null),
+      ])
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+      const recentActivity = (activityRes?.data?.activity || []).slice(-10)
+
+      let coachingPrompt = null
+      if (task.column === 'in_progress' && !task.github?.headBranch) {
+        coachingPrompt = 'No branch created yet. Use create_branch before writing code.'
+      } else if (task.column === 'in_progress' && task.github?.headBranch) {
+        coachingPrompt = `Branch: ${task.github.headBranch}. 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) {
+        coachingPrompt = `Task was parked. Park note: "${task.parkNote.summary}". Use pop_stash if you stashed changes.`
+      }
+
+      return text({
+        task: {
+          id:             task._id,
+          key:            task.key,
+          title:          task.title,
+          description:    task.description,
+          priority:       task.priority,
+          column:         task.column,
+          assignees:      (task.assignees || []).map(a => ({ id: a._id, name: a.name })),
+          reviewer:       task.reviewer ? { id: task.reviewer._id, name: task.reviewer.name } : null,
+          parkNote:       task.parkNote,
+          github:         task.github,
+          subtasks:       task.subtasks,
+          readmeMarkdown: task.readmeMarkdown,
+        },
+        recentActivity: recentActivity.map(a => ({ action: a.action, createdAt: a.createdAt, meta: a.meta })),
+        coachingPrompt,
+      })
+    }
+  )
+
+  // ── create_branch ────────────────────────────────────────────────────────────
+  server.tool(
+    'create_branch',
+    `Create a Git branch on GitHub for a task using the naming convention:
+  feature/TASK-XXX-short-description  (for new features)
+  fix/TASK-XXX-short-description      (for bug fixes / patches)
+
+WHEN TO USE: Immediately after a task moves to in_progress.
+Claude will suggest this automatically after kickoff_task.
+
+Set confirmed=false first to preview the branch name, then confirmed=true to create it.
+After creation, run locally:
+  git fetch origin
+  git checkout <branchName>`,
+    {
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+      projectId: z.string().describe("Project's MongoDB ObjectId"),
+      fromRef:   z.string().optional().describe("Base ref to branch from (default: project's default branch)"),
+      confirmed: z.boolean().optional().default(false).describe('Set true to create the branch after reviewing the preview'),
+    },
+    async ({ taskId, projectId, fromRef, confirmed = false }) => {
+      if (scopedProjectId && projectId !== scopedProjectId) {
+        return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
+      }
+
+      const taskRes = await api.get(`/api/tasks/${taskId}`)
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      const isFix = /\b(fix|bug|hotfix|patch)\b/i.test(task.title + ' ' + (task.description || ''))
+      const prefix = isFix ? 'fix' : 'feature'
+      const slug = task.title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 35)
+      const branchName = `${prefix}/${task.key.toLowerCase()}-${slug}`
+
+      // Preview
+      if (!confirmed) {
+        return text({
+          preview: {
+            action:     'create_branch',
+            branchName,
+            fromRef:    fromRef || '(project default branch)',
+            repo:       '(resolved from project)',
+            task:       { key: task.key, title: task.title },
+          },
+          requiresConfirmation: true,
+          message: `Will create branch "${branchName}" on GitHub. Call create_branch again with confirmed=true to proceed.`,
+        })
+      }
+
+      try {
+        const res = await api.post(`/api/projects/${projectId}/github/branches`, { branchName, fromRef })
+        if (!res?.success) return errorText(res?.message || 'Could not create branch')
+        return text({
+          branchName,
+          url:      res.data.url,
+          message:  'Branch created on GitHub.',
+          gitSteps: [
+            'git fetch origin',
+            `git checkout ${branchName}`,
+          ],
+          nextStep: 'Start coding! When your commits are ready to review, use raise_pr to open a pull request.',
+        })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+
+  // ── stash_changes ────────────────────────────────────────────────────────────
+  server.tool(
+    'stash_changes',
+    `Save your current uncommitted work before switching to a higher-priority task.
+
+WHEN TO USE: When an urgent task arrives while you are mid-work on another task.
+Claude suggests this automatically when you say "I need to switch to TASK-XYZ".
+
+This tool parks the current task in InternalTool (saves your context) and returns the
+exact git stash command to run in your terminal — MCP cannot run git commands directly.
+
+Set confirmed=false first to preview, then confirmed=true to park the task.`,
+    {
+      taskId:    z.string().describe("Task's MongoDB ObjectId of the task you are pausing"),
+      summary:   z.string().optional().describe('What you were doing — include file names and what changed'),
+      reason:    z.string().optional().describe('Why you are switching (e.g. "urgent fix for TASK-042")'),
+      confirmed: z.boolean().optional().default(false).describe('Set true to park the task after reviewing the preview'),
+    },
+    async ({ taskId, summary = '', reason = '', confirmed = false }) => {
+      const taskRes = await api.get(`/api/tasks/${taskId}`)
+      const task    = taskRes?.data?.task
+
+      const stashMsg = summary
+        ? `wip: ${summary.slice(0, 60).replace(/"/g, "'")}`
+        : 'wip: pausing for priority switch'
+
+      const parkNote = {
+        summary:   summary || 'Work in progress — stashing before switching tasks',
+        remaining: reason ? `Switched to: ${reason}` : 'Resume after priority task is done',
+        blockers:  '',
+      }
+
+      if (!confirmed) {
+        return text({
+          preview: {
+            action:       'stash_changes',
+            task:         task ? { key: task.key, title: task.title } : { taskId },
+            willPark:     parkNote,
+            gitCommand:   `git stash push -m "${stashMsg}"`,
+          },
+          requiresConfirmation: true,
+          message: 'This will park the task in InternalTool. Run the git stash command yourself in the terminal. Call stash_changes again with confirmed=true to save the park note.',
+        })
+      }
+
+      try {
+        await api.patch(`/api/tasks/${taskId}/park`, parkNote)
+      } catch (e) {
+        return errorText(`Failed to park task: ${e.message}`)
+      }
+
+      return text({
+        taskParked:  true,
+        gitCommand:  `git stash push -m "${stashMsg}"`,
+        message:     'Task parked. Run the git command above in your terminal to stash your changes.',
+        nextStep:    'Use kickoff_task or create_branch to start the priority task. Use pop_stash to return here.',
+      })
+    }
+  )
+
+  // ── pop_stash ────────────────────────────────────────────────────────────────
+  server.tool(
+    'pop_stash',
+    `Restore stashed work when returning to a previously paused task.
+
+WHEN TO USE: When returning to a task you paused with stash_changes.
+Claude suggests this automatically when you resume a parked task.
+
+Returns the git commands to run in your terminal and unparks the task in InternalTool.
+
+Set confirmed=false first to review the park note, then confirmed=true to unpark.`,
+    {
+      taskId:     z.string().describe("Task's MongoDB ObjectId of the task you are resuming"),
+      stashIndex: z.number().int().min(0).optional().default(0)
+                   .describe("Stash index to pop (0 = most recent). Run 'git stash list' to see all."),
+      confirmed:  z.boolean().optional().default(false).describe('Set true to unpark the task after reviewing'),
+    },
+    async ({ taskId, stashIndex = 0, confirmed = false }) => {
+      const taskRes = await api.get(`/api/tasks/${taskId}`)
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      const stashCmd = stashIndex === 0 ? 'git stash pop' : `git stash pop stash@{${stashIndex}}`
+      const gitSteps = ['git fetch origin', 'git rebase origin/main', stashCmd]
+
+      if (!confirmed) {
+        return text({
+          preview: {
+            action:      'pop_stash',
+            task:        { key: task.key, title: task.title, column: task.column },
+            parkNote:    task.parkNote || null,
+            gitCommands: gitSteps,
+            willDo:      'Clear park note and mark task active in InternalTool',
+          },
+          requiresConfirmation: true,
+          message: 'Review your park note above. Call pop_stash again with confirmed=true to unpark and get the git commands.',
+        })
+      }
+
+      try {
+        await api.patch(`/api/tasks/${taskId}/unpark`, {})
+      } catch (e) {
+        return errorText(`Failed to unpark task: ${e.message}`)
+      }
+
+      return text({
+        taskUnparked: true,
+        parkNote:     task.parkNote || null,
+        gitCommands:  gitSteps,
+        message:      'Task unparked. Run the git commands above in your terminal to restore your work.',
+        nextStep:     'Review your park note for context, then continue where you left off.',
+      })
+    }
+  )
+
+  // ── fix_pr_feedback ──────────────────────────────────────────────────────────
+  server.tool(
+    'fix_pr_feedback',
+    `Guide the developer through fixing a PR that has "changes requested" or was closed,
+while they are mid-work on a different task.
+
+WHEN TO USE: When a notification says "PR needs changes" on Task A while working on Task B.
+Claude will suggest this automatically when it detects a task with github.changesRequestedAt set.
+
+The tool shows exactly what to do — stash Task B, switch to Task A's branch, fix, push, return.
+All git commands are returned for the developer to run in their terminal.
+
+Set confirmed=false first to preview the full plan, then confirmed=true to save the stash note.`,
+    {
+      taskAId:       z.string().describe("Task's MongoDB ObjectId of the task whose PR needs fixing (Task A)"),
+      taskBId:       z.string().optional().describe("Task's MongoDB ObjectId of the task currently being worked on (Task B), if any"),
+      confirmed:     z.boolean().optional().default(false).describe('Set true to park Task B and get the full command sequence'),
+    },
+    async ({ taskAId, taskBId, confirmed = false }) => {
+      const taskARes = await api.get(`/api/tasks/${taskAId}`)
+      if (!taskARes?.success) return errorText('Task A not found')
+      const taskA = taskARes.data.task
+
+      let taskB = null
+      if (taskBId) {
+        const taskBRes = await api.get(`/api/tasks/${taskBId}`)
+        taskB = taskBRes?.data?.task || null
+      }
+
+      const taskABranch = taskA.github?.headBranch || `feature/${taskA.key?.toLowerCase()}-${taskA.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 30)}`
+      const taskBBranch = taskB?.github?.headBranch || (taskB ? `feature/${taskB.key?.toLowerCase()}` : null)
+
+      const plan = {
+        situation: taskB
+          ? `PR for Task A (${taskA.key}) needs changes while you're working on Task B (${taskB.key}).`
+          : `PR for Task A (${taskA.key}) needs changes.`,
+        taskA: { key: taskA.key, title: taskA.title, branch: taskABranch, prNumber: taskA.github?.prNumber, prUrl: taskA.github?.prUrl },
+        taskB: taskB ? { key: taskB.key, title: taskB.title, branch: taskBBranch } : null,
+        steps: [
+          taskB ? `1. Stash Task B work: git stash push -m "wip: ${taskBBranch} — switching to fix ${taskA.key} PR"` : null,
+          `${taskB ? 2 : 1}. Switch to Task A branch: git checkout ${taskABranch}`,
+          `${taskB ? 3 : 2}. Fetch and rebase: git fetch origin && git rebase origin/main`,
+          `${taskB ? 4 : 3}. Read reviewer feedback on GitHub: ${taskA.github?.prUrl || 'open the PR'}`,
+          `${taskB ? 5 : 4}. Fix issues, commit: git add . && git commit -m "fix(${taskA.key?.toLowerCase()}): address review feedback"`,
+          `${taskB ? 6 : 5}. Push to update PR: git push origin ${taskABranch}`,
+          taskB ? `7. Return to Task B: git checkout ${taskBBranch} && git stash pop` : null,
+        ].filter(Boolean),
+      }
+
+      if (!confirmed) {
+        return text({
+          preview: plan,
+          requiresConfirmation: true,
+          message: taskB
+            ? `This will park Task B and guide you to fix the PR for Task A. Call fix_pr_feedback again with confirmed=true to proceed.`
+            : `Here's the plan to fix the PR. Call fix_pr_feedback again with confirmed=true to proceed.`,
+        })
+      }
+
+      // Park Task B if provided
+      if (taskB && taskBId) {
+        try {
+          await api.patch(`/api/tasks/${taskBId}/park`, {
+            summary:   `Working on fix for ${taskA.key} PR review`,
+            remaining: `Resume ${taskB.key} after PR fix is pushed`,
+            blockers:  '',
+          })
+        } catch { /* non-fatal — developer can park manually */ }
+      }
+
+      return text({
+        plan,
+        taskBParked: !!(taskB && taskBId),
+        gitCommands: [
+          taskBBranch ? `git stash push -m "wip: ${taskBBranch} — switching to fix ${taskA.key} PR"` : null,
+          `git checkout ${taskABranch}`,
+          'git fetch origin',
+          'git rebase origin/main',
+          `# Read feedback at: ${taskA.github?.prUrl || '(open the PR on GitHub)'}`,
+          `# Make your fixes, then:`,
+          `git add .`,
+          `git commit -m "fix(${taskA.key?.toLowerCase()}): address review feedback — <describe what changed>"`,
+          `git push origin ${taskABranch}`,
+          taskBBranch ? `# When done — return to Task B:` : null,
+          taskBBranch ? `git checkout ${taskBBranch}` : null,
+          taskBBranch ? `git stash pop` : null,
+        ].filter(Boolean),
+        nextStep: `Fix the issues on Task A's branch, push, then return to Task B. The PR updates automatically when you push.`,
+      })
+    }
+  )
+
+  // ── raise_pr ─────────────────────────────────────────────────────────────────
+  server.tool(
+    'raise_pr',
+    `Create a GitHub Pull Request for a task with auto-generated title and description.
+
+WHEN TO USE: After pushing commits on a feature/fix branch and ready for review.
+Claude suggests this automatically when a task is in_progress and you indicate commits are pushed.
+
+The PR title and body are built from the task data (title, key, description, park notes).
+After the PR is created, the GitHub webhook will automatically move the task to in_review
+and notify the assigned reviewer.
+
+Set confirmed=false first to preview the full PR content, then confirmed=true to create it.`,
+    {
+      taskId:          z.string().describe("Task's MongoDB ObjectId"),
+      projectId:       z.string().describe("Project's MongoDB ObjectId"),
+      headBranch:      z.string().describe('Your feature/fix branch (e.g. feature/task-001-my-feature)'),
+      additionalNotes: z.string().optional().describe('Extra context to add to the PR body'),
+      draft:           z.boolean().optional().default(false).describe('Open as a draft PR (not yet ready for review)'),
+      confirmed:       z.boolean().optional().default(false).describe('Set true to create the PR after reviewing the preview'),
+    },
+    async ({ taskId, projectId, headBranch, additionalNotes = '', draft = false, confirmed = false }) => {
+      if (scopedProjectId && projectId !== scopedProjectId) {
+        return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
+      }
+
+      const taskRes = await api.get(`/api/tasks/${taskId}`)
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      const prTitle = `[${task.key}] ${task.title}`
+      const bodyParts = [
+        `## ${task.key}: ${task.title}`,
+        '',
+        task.description ? `### Description\n${task.description}` : null,
+        task.readmeMarkdown ? `### Implementation Notes\n${task.readmeMarkdown.slice(0, 600)}` : null,
+        task.parkNote?.summary ? `### Work Summary\n${task.parkNote.summary}` : null,
+        task.parkNote?.remaining ? `### What Remains\n${task.parkNote.remaining}` : null,
+        additionalNotes ? `### Additional Notes\n${additionalNotes}` : null,
+        '',
+        '---',
+        `*Auto-generated by InternalTool MCP — task: ${task.key}*`,
+      ].filter(v => v !== null).join('\n')
+
+      if (!confirmed) {
+        return text({
+          preview: {
+            action:     'raise_pr',
+            prTitle,
+            prBody:     bodyParts,
+            headBranch,
+            draft,
+            task:       { key: task.key, title: task.title },
+          },
+          requiresConfirmation: true,
+          message: `Will open a${draft ? ' draft' : ''} PR titled "${prTitle}". Call raise_pr again with confirmed=true to create it.`,
+        })
+      }
+
+      try {
+        const res = await api.post(`/api/projects/${projectId}/github/pull-requests`, {
+          title: prTitle,
+          body:  bodyParts,
+          head:  headBranch,
+          draft,
+        })
+        if (!res?.success) return errorText(res?.message || 'Could not create PR')
+        return text({
+          prNumber: res.data.prNumber,
+          prUrl:    res.data.prUrl,
+          title:    prTitle,
+          draft,
+          message:  `PR #${res.data.prNumber} created.`,
+          nextStep: draft
+            ? 'PR is a draft. Mark it ready for review on GitHub when you want reviewer notifications to fire.'
+            : 'PR is live. The GitHub webhook will move the task to in_review and notify the reviewer within seconds.',
+        })
+      } catch (e) {
+        return errorText(e.message)
+      }
+    }
+  )
+}
+
 function registerAdminTools(server) {
   server.tool(
     'admin_list_users',
@@ -728,6 +1292,7 @@ async function main() {
   registerCommentTools(server)
   registerNotificationTools(server)
   registerGithubTools(server, ctx)
+  registerGitWorkflowTools(server, ctx)
 
   if (isAdmin) {
     registerAdminTools(server)

package/package.json

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