internaltool-mcp 1.5.4 → 1.5.5

package/index.js

@@ -17,6 +17,7 @@
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { execSync } from 'child_process'
 import { z } from 'zod'
 import { api, login, configure } from './api-client.js'
 
@@ -541,12 +542,7 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
         })),
         movedToInProgress: moved,
         suggestedBranch,
-        preflightBeforeBranch: {
-          message: 'Before creating the branch, check your local git state first.',
-          commands: ['git status', 'git stash list'],
-          instruction: 'If you have uncommitted changes, stash or commit them before switching branches. Then call create_branch with your localState.',
-        },
-        nextStep: `Use create_branch to create "${suggestedBranch}" on GitHub — it will ask for your local git state first.`,
+        nextStep: `Use create_branch to create "${suggestedBranch}" on GitHub — it will automatically check your local git state before creating.`,
       })
     }
   )
@@ -780,12 +776,103 @@ function registerGithubTools(server, { scopedProjectId }) {
   )
 }
 
+// ── Local git helper ──────────────────────────────────────────────────────────
+// MCP runs as a local process — it can shell out to git directly.
+
+function runGit(args, cwd) {
+  return execSync(`git ${args}`, {
+    cwd:      cwd || process.cwd(),
+    encoding: 'utf8',
+    timeout:  8000,
+    stdio:    ['pipe', 'pipe', 'pipe'],
+  }).trim()
+}
+
+function parseGitStatus(porcelain) {
+  const lines = porcelain.split('\n').filter(Boolean)
+  const staged     = lines.filter(l => !' ?!'.includes(l[0])).map(l => ({ xy: l.slice(0, 2), file: l.slice(3) }))
+  const unstaged   = lines.filter(l => !' ?!'.includes(l[1])).map(l => ({ xy: l.slice(0, 2), file: l.slice(3) }))
+  const untracked  = lines.filter(l => l.startsWith('??')).map(l => l.slice(3))
+  const modified   = [...new Set([...staged, ...unstaged].map(f => f.file))]
+
+  let localState
+  if (modified.length > 0)       localState = 'modified'   // tracked changes — must stash or commit
+  else if (untracked.length > 0) localState = 'untracked'  // only untracked — safe to switch
+  else                           localState = 'clean'       // nothing at all
+
+  return { staged, unstaged, untracked, modified, localState }
+}
+
 // ── 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 } = {}) {
 
+  // ── check_local_git_state ────────────────────────────────────────────────────
+  server.tool(
+    'check_local_git_state',
+    `Check the local git repository state on the developer's machine by running git commands directly.
+
+Returns: current branch, whether the working tree is clean, modified/staged/untracked files,
+stash list, and a recommendation for what to do before creating or switching branches.
+
+ALWAYS call this before create_branch, stash_changes, or pop_stash.
+The developer does not need to run any commands manually — this tool reads local state automatically.`,
+    {
+      repoPath: z.string().optional().describe('Absolute path to the local git repo. Defaults to the MCP process working directory.'),
+    },
+    async ({ repoPath } = {}) => {
+      const cwd = repoPath || process.cwd()
+      try {
+        const porcelain    = runGit('status --porcelain=v1', cwd)
+        const branch       = runGit('branch --show-current', cwd)
+        const stashListRaw = runGit('stash list', cwd)
+        const remoteStatus = runGit('status --short --branch', cwd).split('\n')[0] // ## main...origin/main [ahead 1]
+
+        const { staged, unstaged, untracked, modified, localState } = parseGitStatus(porcelain)
+        const stashes = stashListRaw ? stashListRaw.split('\n').filter(Boolean) : []
+
+        const recommendation =
+          localState === 'modified'
+            ? `You have ${modified.length} modified tracked file(s). Before switching branches you must either:\n  a) git stash push -m "wip: <message>"   (reversible, stays local)\n  b) git add . && git commit -m "chore: wip"  (safer, survives crashes)`
+            : localState === 'untracked'
+              ? `Only untracked files present (${untracked.length} file(s)). Safe to create or switch branches — untracked files stay in place and do NOT follow you to another branch.`
+              : 'Working tree is clean. Safe to create or switch branches.'
+
+        return text({
+          currentBranch:  branch || '(detached HEAD)',
+          remoteStatus:   remoteStatus.replace(/^## /, ''),
+          localState,
+          clean:          localState === 'clean',
+          summary: {
+            stagedFiles:    staged.map(f => f.file),
+            unstagedFiles:  unstaged.map(f => f.file),
+            untrackedFiles: untracked,
+            modifiedCount:  modified.length,
+            untrackedCount: untracked.length,
+          },
+          stashes: {
+            count: stashes.length,
+            list:  stashes.slice(0, 5),
+          },
+          recommendation,
+          nextStep: localState === 'modified'
+            ? 'Stash or commit your changes, then call create_branch with localState="stashed" or "committed".'
+            : 'Call create_branch with localState="' + localState + '" — you are ready to proceed.',
+        })
+      } catch (e) {
+        if (e.message.includes('not a git repository')) {
+          return errorText(`"${cwd}" is not a git repository. Pass the correct repoPath or cd into your project.`)
+        }
+        if (e.message.includes('not found') || e.message.includes('ENOENT')) {
+          return errorText('git is not installed or not on PATH.')
+        }
+        return errorText(`Could not check git state: ${e.message.split('\n')[0]}`)
+      }
+    }
+  )
+
   // ── list_my_tasks ────────────────────────────────────────────────────────────
   server.tool(
     'list_my_tasks',
@@ -836,12 +923,14 @@ Use this at the start of a session or when switching tasks.`,
   // ── get_task_context ─────────────────────────────────────────────────────────
   server.tool(
     'get_task_context',
-    `Get everything needed to resume a task: full details, park notes, recent activity, and git state.
+    `Get everything needed to resume a task: full details, park notes, recent activity, and local git state.
+Auto-detects the developer's current branch and git state — no manual commands needed.
 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"),
+      taskId:   z.string().describe("Task's MongoDB ObjectId"),
+      repoPath: z.string().optional().describe('Absolute path to the local git repo (defaults to MCP process working directory)'),
     },
-    async ({ taskId }) => {
+    async ({ taskId, repoPath }) => {
       const [taskRes, activityRes] = await Promise.all([
         api.get(`/api/tasks/${taskId}`),
         api.get(`/api/tasks/${taskId}/activity`).catch(() => null),
@@ -850,11 +939,41 @@ Use this when returning to a task after a break, or when Claude needs the full p
       const task = taskRes.data.task
       const recentActivity = (activityRes?.data?.activity || []).slice(-10)
 
+      // Auto-detect local git state
+      let localGitState = null
+      try {
+        const cwd          = repoPath || process.cwd()
+        const porcelain    = runGit('status --porcelain=v1', cwd)
+        const branch       = runGit('branch --show-current', cwd)
+        const stashListRaw = runGit('stash list', cwd)
+        const { modified, untracked, localState } = parseGitStatus(porcelain)
+        const stashes = stashListRaw ? stashListRaw.split('\n').filter(Boolean) : []
+        localGitState = {
+          currentBranch:  branch || '(detached HEAD)',
+          state:          localState,
+          modifiedFiles:  modified,
+          untrackedFiles: untracked,
+          stashes:        stashes.slice(0, 3),
+          onTaskBranch:   task.github?.headBranch ? branch === task.github.headBranch : null,
+        }
+      } catch {
+        // non-fatal — git may not be available or path may differ
+      }
+
       let coachingPrompt = null
       if (task.column === 'in_progress' && !task.github?.headBranch) {
-        coachingPrompt = 'No branch yet. Before create_branch: run "git status" in your terminal first — stash or commit any local changes, then call create_branch with your localState.'
+        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}`
       } 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.`
+        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.`
       } else if (task.column === 'in_review') {
         coachingPrompt = `PR #${task.github?.prNumber} is open. Waiting for reviewer feedback.`
       } else if (task.parkNote?.parkedAt) {
@@ -876,7 +995,8 @@ Use this when returning to a task after a break, or when Claude needs the full p
           subtasks:       task.subtasks,
           readmeMarkdown: task.readmeMarkdown,
         },
-        recentActivity: recentActivity.map(a => ({ action: a.action, createdAt: a.createdAt, meta: a.meta })),
+        recentActivity:  recentActivity.map(a => ({ action: a.action, createdAt: a.createdAt, meta: a.meta })),
+        localGitState,
         coachingPrompt,
       })
     }
@@ -891,27 +1011,20 @@ Use this when returning to a task after a break, or when Claude needs the full p
 
 WHEN TO USE: Immediately after a task moves to in_progress.
 
-THREE-STEP FLOW — do not skip steps:
-  1. confirmed=false              → preview branch name + get pre-flight git commands to run locally
-  2. Run the pre-flight commands  → check local state, stash if needed, report back with localState
-  3. confirmed=true + localState  → branch is created on GitHub
+TWO-STEP FLOW:
+  1. confirmed=false → auto-detects your local git state + shows the branch name preview
+  2. confirmed=true  → creates the branch on GitHub (blocks automatically if tracked changes are present)
 
-localState must be one of:
-  "clean"     — git status shows nothing to commit, working tree clean
-  "stashed"   — had changes, ran git stash, now clean
-  "committed" — had changes, did a WIP commit, now clean
-
-Never skip the localState check — switching branches with uncommitted changes
-can cause conflicts or silently carry changes onto the new branch.`,
+You do NOT need to run git status manually — this tool checks it for you.
+If you have uncommitted tracked changes, it will tell you exactly what to do before retrying.`,
     {
-      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 only after running pre-flight commands and setting localState'),
-      localState: z.enum(['clean', 'untracked', 'stashed', 'committed']).optional()
-                   .describe('Your local git state after running git status. Required when confirmed=true. Use "untracked" if git status shows only untracked files with no modified tracked files.'),
+      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 after reviewing the preview to create the branch'),
+      repoPath:  z.string().optional().describe('Absolute path to the local git repo (defaults to MCP process working directory)'),
     },
-    async ({ taskId, projectId, fromRef, confirmed = false, localState }) => {
+    async ({ taskId, projectId, fromRef, confirmed = false, repoPath }) => {
       if (scopedProjectId && projectId !== scopedProjectId) {
         return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
       }
@@ -929,8 +1042,42 @@ can cause conflicts or silently carry changes onto the new branch.`,
         .slice(0, 35)
       const branchName = `${prefix}/${task.key.toLowerCase()}-${slug}`
 
-      // Step 1 — preview + pre-flight commands
+      // Auto-detect local git state
+      let gitState = null
+      let gitStateError = null
+      const cwd = repoPath || process.cwd()
+      try {
+        const porcelain    = runGit('status --porcelain=v1', cwd)
+        const branch       = runGit('branch --show-current', cwd)
+        const stashListRaw = runGit('stash list', cwd)
+        const { staged, unstaged, untracked, modified, localState } = parseGitStatus(porcelain)
+        const stashes = stashListRaw ? stashListRaw.split('\n').filter(Boolean) : []
+        gitState = { currentBranch: branch, localState, modified, untracked, stashes }
+      } catch (e) {
+        gitStateError = e.message.includes('not a git repository')
+          ? `"${cwd}" is not a git repository. Pass repoPath to the correct local project directory.`
+          : `Could not read local git state: ${e.message.split('\n')[0]}`
+      }
+
+      // Step 1 — preview with auto-detected local state
       if (!confirmed) {
+        const stateMsg = gitStateError
+          ? `⚠️  Could not auto-detect git state: ${gitStateError}`
+          : gitState.localState === 'modified'
+            ? `⚠️  You have ${gitState.modified.length} modified tracked file(s) on branch "${gitState.currentBranch}". You must stash or commit them before switching branches.`
+            : gitState.localState === 'untracked'
+              ? `✅  Only untracked files present (${gitState.untracked.length} file(s)) on branch "${gitState.currentBranch}". Safe to switch — untracked files stay in place.`
+              : `✅  Working tree is clean on branch "${gitState.currentBranch}". Safe to create the branch.`
+
+        const requiredAction = gitState?.localState === 'modified'
+          ? {
+              mustDo: 'Stash or commit your tracked changes before confirming.',
+              option_a: `git stash push -m "wip: switching to ${branchName}"`,
+              option_b: 'git add . && git commit -m "chore: wip"',
+              thenDo: 'After doing one of the above, call create_branch again with confirmed=true.',
+            }
+          : null
+
         return text({
           preview: {
             action:     'create_branch',
@@ -938,35 +1085,40 @@ can cause conflicts or silently carry changes onto the new branch.`,
             basedOn:    fromRef || '(project default branch)',
             task:       { key: task.key, title: task.title },
           },
-          preflightRequired: true,
-          preflightCommands: [
-            'git status',
-            'git stash list',
-            'git diff --stat',
-          ],
-          preflightInstructions: [
-            'Run the three commands above in your terminal right now.',
-            'Read your git status output and pick the matching localState:',
-            '  "clean"     — "nothing to commit, working tree clean"',
-            '  "untracked" — only untracked files listed, no modified tracked files. Safe to proceed — untracked files stay in place when you switch branches, they do NOT follow you.',
-            '  "stashed"   — you had modified tracked files; run: git stash push -m "wip: switching to ' + branchName + '" — then set this.',
-            '  "committed" — you had changes; run: git add . && git commit -m "chore: wip" — then set this.',
-          ],
-          message: `Run the pre-flight commands above, read the output, then call create_branch again with confirmed=true and localState set to one of: clean | untracked | stashed | committed.`,
+          localGitState: gitState
+            ? {
+                currentBranch:  gitState.currentBranch,
+                state:          gitState.localState,
+                modifiedFiles:  gitState.modified,
+                untrackedFiles: gitState.untracked,
+                stashes:        gitState.stashes.slice(0, 3),
+              }
+            : { error: gitStateError },
+          statusMessage: stateMsg,
+          requiredAction,
+          requiresConfirmation: true,
+          message: gitState?.localState === 'modified'
+            ? `Cannot proceed — stash or commit your changes first (see requiredAction above), then call create_branch with confirmed=true.`
+            : `Local state is clear. Call create_branch again with confirmed=true to create the branch on GitHub.`,
         })
       }
 
-      // Step 2 — localState gate: block if developer skipped the check
-      if (!localState) {
+      // Step 2 — block automatically if there are tracked changes
+      if (gitState?.localState === 'modified') {
         return text({
           blocked: true,
-          reason: 'localState is required when confirmed=true.',
-          message: 'You must run "git status" first and tell me your local state. Set localState to "clean", "stashed", or "committed" depending on what you found.',
-          preflightCommands: ['git status', 'git stash list'],
+          reason: `You have ${gitState.modified.length} modified tracked file(s). Creating a branch while tracked changes are present can carry them onto the new branch.`,
+          modifiedFiles: gitState.modified,
+          fixOptions: {
+            stash:  `git stash push -m "wip: switching to ${branchName}"`,
+            commit: 'git add . && git commit -m "chore: wip"',
+          },
+          message: 'Stash or commit your changes, then call create_branch again with confirmed=true.',
         })
       }
 
       // Step 3 — create branch on GitHub
+      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')
@@ -976,12 +1128,12 @@ can cause conflicts or silently carry changes onto the new branch.`,
           `git checkout ${branchName}`,
         ]
 
-        // State-specific notes
         const localStateNote = {
           clean:     null,
-          untracked: 'Your untracked files (.cursor/, docs, etc.) will stay in your working directory after checkout — they are not tracked by git so they do not follow branches. They will not appear in commits on the new branch unless you explicitly git add them.',
-          stashed:   'You stashed changes before switching. After checkout, decide: does your stash belong on this new branch? If yes: git stash pop. If it belongs to a different branch, leave it and pop it there later.',
-          committed: 'You made a WIP commit before switching. That commit stays on the branch you were on — it will not appear on the new branch.',
+          untracked: `Your untracked files (${gitState?.untracked?.length || 0} file(s)) will stay in your working directory after checkout — they are not tracked by git so they do not follow branches.`,
+          stashed:   'You have stashed changes. After checkout, decide: does your stash belong on this new branch? If yes: git stash pop.',
+          committed: 'You have a WIP commit on the previous branch — it will not appear on the new branch.',
+          unknown:   null,
         }[localState] || null
 
         return text({

package/package.json

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