@cyanheads/git-mcp-server 2.0.10 → 2.0.12

package/README.md

@@ -1,8 +1,8 @@
 # Git MCP Server
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
-[![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.11.0-green.svg)](https://modelcontextprotocol.io/)
-[![Version](https://img.shields.io/badge/Version-2.0.10-blue.svg)](./CHANGELOG.md)
+[![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.12.0-green.svg)](https://modelcontextprotocol.io/)
+[![Version](https://img.shields.io/badge/Version-2.0.12-blue.svg)](./CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Stable-green.svg)](https://github.com/cyanheads/git-mcp-server/issues)
 [![GitHub](https://img.shields.io/github/stars/cyanheads/git-mcp-server?style=social)](https://github.com/cyanheads/git-mcp-server)
@@ -165,7 +165,7 @@ The Git MCP Server provides a suite of tools for interacting with Git repositori
 | `git_commit`            | Commits staged changes. Supports author override, signing control.                                       | `path?`, `message`, `author?`, `allowEmpty?`, `amend?`, `forceUnsignedOnFailure?`                               |
 | `git_diff`              | Shows changes between commits, working tree, etc.                                                        | `path?`, `commit1?`, `commit2?`, `staged?`, `file?`                                                             |
 | `git_fetch`             | Downloads objects and refs from other repositories.                                                      | `path?`, `remote?`, `prune?`, `tags?`, `all?`                                                                   |
-| `git_init`              | Initializes a new Git repository at the specified absolute path.                                         | `path`, `initialBranch?`, `bare?`, `quiet?`                                                                     |
+| `git_init`              | Initializes a new Git repository at the specified absolute path. Defaults to 'main' for initial branch.    | `path`, `initialBranch?`, `bare?`, `quiet?`                                                                     |
 | `git_log`               | Shows commit logs.                                                                                       | `path?`, `maxCount?`, `author?`, `since?`, `until?`, `branchOrFile?`                                            |
 | `git_merge`             | Merges the specified branch into the current branch.                                                     | `path?`, `branch`, `commitMessage?`, `noFf?`, `squash?`, `abort?`                                               |
 | `git_pull`              | Fetches from and integrates with another repository or local branch.                                     | `path?`, `remote?`, `branch?`, `rebase?`, `ffOnly?`                                                             |
@@ -173,19 +173,20 @@ The Git MCP Server provides a suite of tools for interacting with Git repositori
 | `git_rebase`            | Reapplies commits on top of another base tip.                                                            | `path?`, `mode?`, `upstream?`, `branch?`, `interactive?`, `strategy?`, `strategyOption?`, `onto?`               |
 | `git_remote`            | Manages remote repositories (list, add, remove, show).                                                   | `path?`, `mode`, `name?`, `url?`                                                                                |
 | `git_reset`             | Resets current HEAD to a specified state. Supports soft, mixed, hard modes. **USE 'hard' WITH CAUTION**. | `path?`, `mode?`, `commit?`                                                                                     |
-| `git_set_working_dir`   | Sets the default working directory for the current session. Requires absolute path.                      | `path`, `validateGitRepo?`                                                                                      |
+| `git_set_working_dir`   | Sets the default working directory. Can optionally initialize repo if not present. Requires absolute path. | `path`, `validateGitRepo?`, `initializeIfNotPresent?`                                                           |
 | `git_show`              | Shows information about Git objects (commits, tags, etc.).                                               | `path?`, `ref`, `filePath?`                                                                                     |
 | `git_stash`             | Manages stashed changes (list, apply, pop, drop, save).                                                  | `path?`, `mode`, `stashRef?`, `message?`                                                                        |
 | `git_status`            | Gets repository status (branch, staged, modified, untracked files).                                      | `path?`                                                                                                         |
 | `git_tag`               | Manages tags (list, create annotated/lightweight, delete).                                               | `path?`, `mode`, `tagName?`, `message?`, `commitRef?`, `annotate?`                                              |
+| `git_worktree`          | Manages Git worktrees (list, add, remove, move, prune).                                                  | `path?`, `mode`, `worktreePath?`, `commitish?`, `newBranch?`, `force?`, `detach?`, `newPath?`, `verbose?`, `dryRun?`, `expire?` |
 
 _Note: The `path` parameter for most tools defaults to the session's working directory if set via `git_set_working_dir`._
 
 ## Resources
 
-**MCP Resources are not implemented in this version (v2.0.8).**
+**MCP Resources are not implemented in this version (v2.0.12).**
 
-This version focuses on the refactored Git tools implementation based on the latest `mcp-ts-template` and MCP SDK v1.11.0. Resource capabilities, previously available, have been temporarily removed during this major update.
+This version focuses on the refactored Git tools implementation based on the latest `mcp-ts-template` and MCP SDK v1.12.0. Resource capabilities, previously available, have been temporarily removed during this major update.
 
 If you require MCP Resource access (e.g., for reading file content directly via the server), please use the stable **[v1.2.4 release](https://github.com/cyanheads/git-mcp-server/releases/tag/v1.2.4)**.
 

package/dist/mcp-server/server.js

@@ -18,31 +18,32 @@ import { config, environment } from '../config/index.js';
 // Import core utilities: ErrorHandler, logger, requestContextService.
 import { ErrorHandler, logger, requestContextService } from '../utils/index.js'; // Added RequestContext
 // Import registration AND state initialization functions for ALL Git tools (alphabetized)
-import { registerGitAddTool, initializeGitAddStateAccessors } from './tools/gitAdd/index.js';
-import { registerGitBranchTool, initializeGitBranchStateAccessors } from './tools/gitBranch/index.js';
-import { registerGitCheckoutTool, initializeGitCheckoutStateAccessors } from './tools/gitCheckout/index.js';
-import { registerGitCherryPickTool, initializeGitCherryPickStateAccessors } from './tools/gitCherryPick/index.js';
-import { registerGitCleanTool, initializeGitCleanStateAccessors } from './tools/gitClean/index.js';
-import { registerGitClearWorkingDirTool, initializeGitClearWorkingDirStateAccessors } from './tools/gitClearWorkingDir/index.js';
+import { initializeGitAddStateAccessors, registerGitAddTool } from './tools/gitAdd/index.js';
+import { initializeGitBranchStateAccessors, registerGitBranchTool } from './tools/gitBranch/index.js';
+import { initializeGitCheckoutStateAccessors, registerGitCheckoutTool } from './tools/gitCheckout/index.js';
+import { initializeGitCherryPickStateAccessors, registerGitCherryPickTool } from './tools/gitCherryPick/index.js';
+import { initializeGitCleanStateAccessors, registerGitCleanTool } from './tools/gitClean/index.js';
+import { initializeGitClearWorkingDirStateAccessors, registerGitClearWorkingDirTool } from './tools/gitClearWorkingDir/index.js';
 import { registerGitCloneTool } from './tools/gitClone/index.js'; // No initializer needed/available
-import { registerGitCommitTool, initializeGitCommitStateAccessors } from './tools/gitCommit/index.js';
-import { registerGitDiffTool, initializeGitDiffStateAccessors } from './tools/gitDiff/index.js';
-import { registerGitFetchTool, initializeGitFetchStateAccessors } from './tools/gitFetch/index.js';
-import { registerGitInitTool, initializeGitInitStateAccessors } from './tools/gitInit/index.js';
-import { registerGitLogTool, initializeGitLogStateAccessors } from './tools/gitLog/index.js';
-import { registerGitMergeTool, initializeGitMergeStateAccessors } from './tools/gitMerge/index.js';
-import { registerGitPullTool, initializeGitPullStateAccessors } from './tools/gitPull/index.js';
-import { registerGitPushTool, initializeGitPushStateAccessors } from './tools/gitPush/index.js';
-import { registerGitRebaseTool, initializeGitRebaseStateAccessors } from './tools/gitRebase/index.js';
-import { registerGitRemoteTool, initializeGitRemoteStateAccessors } from './tools/gitRemote/index.js';
-import { registerGitResetTool, initializeGitResetStateAccessors } from './tools/gitReset/index.js';
-import { registerGitSetWorkingDirTool, initializeGitSetWorkingDirStateAccessors } from './tools/gitSetWorkingDir/index.js';
-import { registerGitShowTool, initializeGitShowStateAccessors } from './tools/gitShow/index.js';
-import { registerGitStashTool, initializeGitStashStateAccessors } from './tools/gitStash/index.js';
-import { registerGitStatusTool, initializeGitStatusStateAccessors } from './tools/gitStatus/index.js';
-import { registerGitTagTool, initializeGitTagStateAccessors } from './tools/gitTag/index.js';
+import { initializeGitCommitStateAccessors, registerGitCommitTool } from './tools/gitCommit/index.js';
+import { initializeGitDiffStateAccessors, registerGitDiffTool } from './tools/gitDiff/index.js';
+import { initializeGitFetchStateAccessors, registerGitFetchTool } from './tools/gitFetch/index.js';
+import { initializeGitInitStateAccessors, registerGitInitTool } from './tools/gitInit/index.js';
+import { initializeGitLogStateAccessors, registerGitLogTool } from './tools/gitLog/index.js';
+import { initializeGitMergeStateAccessors, registerGitMergeTool } from './tools/gitMerge/index.js';
+import { initializeGitPullStateAccessors, registerGitPullTool } from './tools/gitPull/index.js';
+import { initializeGitPushStateAccessors, registerGitPushTool } from './tools/gitPush/index.js';
+import { initializeGitRebaseStateAccessors, registerGitRebaseTool } from './tools/gitRebase/index.js';
+import { initializeGitRemoteStateAccessors, registerGitRemoteTool } from './tools/gitRemote/index.js';
+import { initializeGitResetStateAccessors, registerGitResetTool } from './tools/gitReset/index.js';
+import { initializeGitSetWorkingDirStateAccessors, registerGitSetWorkingDirTool } from './tools/gitSetWorkingDir/index.js';
+import { initializeGitShowStateAccessors, registerGitShowTool } from './tools/gitShow/index.js';
+import { initializeGitStashStateAccessors, registerGitStashTool } from './tools/gitStash/index.js';
+import { initializeGitStatusStateAccessors, registerGitStatusTool } from './tools/gitStatus/index.js';
+import { initializeGitTagStateAccessors, registerGitTagTool } from './tools/gitTag/index.js';
+import { initializeGitWorktreeStateAccessors, registerGitWorktreeTool } from './tools/gitWorktree/index.js';
 // Import transport setup functions AND state accessors
-import { startHttpTransport, getHttpSessionWorkingDirectory, setHttpSessionWorkingDirectory } from './transports/httpTransport.js';
+import { getHttpSessionWorkingDirectory, setHttpSessionWorkingDirectory, startHttpTransport } from './transports/httpTransport.js';
 import { connectStdioTransport, getStdioWorkingDirectory, setStdioWorkingDirectory } from './transports/stdioTransport.js';
 /**
  * Creates and configures a new instance of the McpServer.
@@ -157,6 +158,7 @@ async function createMcpServerInstance() {
         initializeGitStashStateAccessors(getWorkingDirectory, getSessionIdFromContext);
         initializeGitStatusStateAccessors(getWorkingDirectory, getSessionIdFromContext);
         initializeGitTagStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitWorktreeStateAccessors(getWorkingDirectory, getSessionIdFromContext);
         logger.debug('State accessors initialized successfully.', context);
     }
     catch (initError) {
@@ -195,6 +197,7 @@ async function createMcpServerInstance() {
         await registerGitStashTool(server);
         await registerGitStatusTool(server);
         await registerGitTagTool(server);
+        await registerGitWorktreeTool(server);
         // Add calls to register other resources/tools here if needed in the future.
         logger.info('Git tools registered successfully', context);
     }

package/dist/mcp-server/tools/gitInit/logic.js

@@ -62,11 +62,9 @@ export async function gitInitLogic(input, context) {
         if (input.bare) {
             command += ' --bare';
         }
-        if (input.initialBranch) {
-            // Use -b for modern Git versions, older might need --initial-branch=
-            // Sticking with -b as it's common now. Add quotes around branch name.
-            command += ` -b "${input.initialBranch.replace(/"/g, '\\"')}"`;
-        }
+        // Determine the initial branch name, defaulting to 'main' if not provided
+        const branchNameToUse = input.initialBranch || 'main';
+        command += ` -b "${branchNameToUse.replace(/"/g, '\\"')}"`;
         // Add the target directory path at the end
         command += ` "${targetPath}"`;
         logger.debug(`Executing command: ${command}`, { ...context, operation });

package/dist/mcp-server/tools/gitSetWorkingDir/logic.js

@@ -9,6 +9,7 @@ const execAsync = promisify(exec);
 export const GitSetWorkingDirInputSchema = z.object({
     path: z.string().min(1, "Path cannot be empty.").describe("The absolute path to set as the default working directory for the current session. Set this before using other git_* tools."),
     validateGitRepo: z.boolean().default(true).describe("Whether to validate that the path is a Git repository"),
+    initializeIfNotPresent: z.boolean().optional().default(false).describe("If true and the directory is not a Git repository, attempt to initialize it with 'git init'.")
 });
 /**
  * Logic for the git_set_working_dir tool.
@@ -51,25 +52,37 @@ export async function gitSetWorkingDirLogic(input, context // Assuming context p
         logger.error('Failed to stat directory', error, { ...context, operation, path: sanitizedPath });
         throw new McpError(BaseErrorCode.INTERNAL_ERROR, `Failed to access path: ${error.message}`, { context, operation });
     }
-    // Optionally validate if it's a Git repository
-    if (input.validateGitRepo) {
-        logger.debug('Validating if path is a Git repository', { ...context, operation, path: sanitizedPath });
+    let isGitRepo = false;
+    let initializedRepo = false;
+    try {
+        const { stdout } = await execAsync('git rev-parse --is-inside-work-tree', { cwd: sanitizedPath });
+        if (stdout.trim() === 'true') {
+            isGitRepo = true;
+            logger.debug('Path is already a Git repository', { ...context, operation, path: sanitizedPath });
+        }
+    }
+    catch (error) {
+        logger.debug('Path is not a Git repository (rev-parse failed or returned non-true)', { ...context, operation, path: sanitizedPath, error: error.message });
+        isGitRepo = false;
+    }
+    if (!isGitRepo && input.initializeIfNotPresent) {
+        logger.info(`Path is not a Git repository. Attempting to initialize (initializeIfNotPresent=true) with initial branch 'main'.`, { ...context, operation, path: sanitizedPath });
         try {
-            // A common way to check is using 'git rev-parse --is-inside-work-tree'
-            // or checking for the existence of a .git directory/file.
-            // Using rev-parse is generally more robust.
-            const { stdout } = await execAsync('git rev-parse --is-inside-work-tree', { cwd: sanitizedPath });
-            if (stdout.trim() !== 'true') {
-                // This case should ideally not happen if rev-parse succeeds, but good to check.
-                throw new Error('Not a Git repository (rev-parse returned non-true)');
-            }
-            logger.debug('Path validated as Git repository', { ...context, operation, path: sanitizedPath });
+            await execAsync('git init --initial-branch=main', { cwd: sanitizedPath });
+            initializedRepo = true;
+            isGitRepo = true; // Now it is a git repo
+            logger.info('Successfully initialized Git repository with initial branch "main".', { ...context, operation, path: sanitizedPath });
         }
-        catch (error) {
-            logger.warning('Path is not a valid Git repository', { ...context, operation, path: sanitizedPath, error: error.message });
-            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Path is not a valid Git repository: ${sanitizedPath}. Error: ${error.message}`, { context, operation });
+        catch (initError) {
+            logger.error('Failed to initialize Git repository', initError, { ...context, operation, path: sanitizedPath });
+            throw new McpError(BaseErrorCode.INTERNAL_ERROR, `Failed to initialize Git repository at ${sanitizedPath}: ${initError.message}`, { context, operation });
         }
     }
+    // After potential initialization, if validateGitRepo is true, it must now be a Git repo.
+    if (input.validateGitRepo && !isGitRepo) {
+        logger.warning('Path is not a valid Git repository and initialization was not performed or failed.', { ...context, operation, path: sanitizedPath });
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Path is not a valid Git repository: ${sanitizedPath}.`, { context, operation });
+    }
     // --- Update Session State ---
     // This part needs access to the session state mechanism defined in server.ts
     // We assume the context provides a way to set the working directory for the current session.
@@ -82,9 +95,23 @@ export async function gitSetWorkingDirLogic(input, context // Assuming context p
         // This indicates an internal logic error in how state is passed/managed.
         throw new McpError(BaseErrorCode.INTERNAL_ERROR, 'Failed to update session state.', { context, operation });
     }
+    let message = `Working directory set to: ${sanitizedPath}`;
+    if (initializedRepo) {
+        message += ' (New Git repository initialized).';
+    }
+    else if (isGitRepo && input.validateGitRepo) { // Only state "Existing" if validation was on and it passed
+        message += ' (Existing Git repository).';
+    }
+    else if (isGitRepo && !input.validateGitRepo) { // It is a git repo, but we weren't asked to validate it
+        message += ' (Is a Git repository, validation skipped).';
+    }
+    else if (!isGitRepo && !input.validateGitRepo && !input.initializeIfNotPresent) { // Not a git repo, validation off, no init request
+        message += ' (Not a Git repository, validation skipped, no initialization requested).';
+    }
     return {
         success: true,
-        message: `Working directory set to: ${sanitizedPath}`,
+        message: message,
         path: sanitizedPath,
+        initialized: initializedRepo,
     };
 }

package/dist/mcp-server/tools/gitSetWorkingDir/registration.js

@@ -19,7 +19,7 @@ setWdFn, getSidFn) {
     logger.info('State accessors initialized for git_set_working_dir tool registration.');
 }
 const TOOL_NAME = 'git_set_working_dir';
-const TOOL_DESCRIPTION = "Sets the default working directory for the current session. Subsequent Git tool calls within this session can use '.' for the `path` parameter, which will resolve to this directory. Optionally validates if the path is a Git repository (`validateGitRepo: true`). Returns the result as a JSON object. IMPORTANT: The provided path must be absolute.";
+const TOOL_DESCRIPTION = "Sets the default working directory for the current session. Subsequent Git tool calls within this session can use '.' for the `path` parameter, which will resolve to this directory. Optionally validates if the path is a Git repository (`validateGitRepo: true`). Can optionally initialize a Git repository with 'git init' if it's not already one and `initializeIfNotPresent: true` is set. Returns the result as a JSON object. IMPORTANT: The provided path must be absolute.";
 /**
  * Registers the git_set_working_dir tool with the MCP server.
  *

package/dist/mcp-server/tools/gitWorktree/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for the git_worktree tool.
+ * Exports the registration function and state accessor initialization function.
+ */
+export { registerGitWorktreeTool, initializeGitWorktreeStateAccessors } from './registration.js';
+// Export types if needed elsewhere, e.g.:
+// export type { GitWorktreeInput, GitWorktreeResult } from './logic.js';

package/dist/mcp-server/tools/gitWorktree/logic.js

@@ -0,0 +1,239 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { z } from 'zod';
+import { logger, sanitization } from '../../../utils/index.js';
+import { BaseErrorCode, McpError } from '../../../types-global/errors.js';
+const execAsync = promisify(exec);
+// Define the BASE input schema for the git_worktree tool using Zod
+export const GitWorktreeBaseSchema = z.object({
+    path: z.string().min(1).optional().default('.').describe("Path to the local Git repository. Defaults to the directory set via `git_set_working_dir` for the session; set 'git_set_working_dir' if not set."),
+    mode: z.enum(['list', 'add', 'remove', 'move', 'prune']).describe("The worktree operation to perform: 'list', 'add', 'remove', 'move', 'prune'."),
+    // Common optional path for operations
+    worktreePath: z.string().min(1).optional().describe("Path of the worktree. Required for 'add', 'remove', 'move' modes."),
+    // 'add' mode specific
+    commitish: z.string().min(1).optional().describe("Branch or commit to checkout in the new worktree. Used only in 'add' mode. Defaults to HEAD."),
+    newBranch: z.string().min(1).optional().describe("Create a new branch in the worktree. Used only in 'add' mode."),
+    force: z.boolean().default(false).describe("Force the operation (e.g., for 'add' if branch exists, or 'remove' if uncommitted changes)."),
+    detach: z.boolean().default(false).describe("Detach HEAD in the new worktree. Used only in 'add' mode."),
+    // 'move' mode specific
+    newPath: z.string().min(1).optional().describe("The new path for the worktree. Required for 'move' mode."),
+    // 'prune' mode specific
+    verbose: z.boolean().default(false).describe("Provide more detailed output. Used in 'list' and 'prune' modes."),
+    dryRun: z.boolean().default(false).describe("Show what would be done without actually doing it. Used in 'prune' mode."),
+    expire: z.string().min(1).optional().describe("Prune entries older than this time (e.g., '1.month.ago'). Used in 'prune' mode."),
+});
+// Apply refinements and export the FINAL schema
+export const GitWorktreeInputSchema = GitWorktreeBaseSchema.refine(data => !(data.mode === 'add' && !data.worktreePath), {
+    message: "A 'worktreePath' is required for 'add' mode.", path: ["worktreePath"],
+}).refine(data => !(data.mode === 'remove' && !data.worktreePath), {
+    message: "A 'worktreePath' is required for 'remove' mode.", path: ["worktreePath"],
+}).refine(data => !(data.mode === 'move' && (!data.worktreePath || !data.newPath)), {
+    message: "Both 'worktreePath' (old path) and 'newPath' are required for 'move' mode.", path: ["worktreePath", "newPath"],
+});
+/**
+ * Parses the output of `git worktree list --porcelain`.
+ */
+function parsePorcelainWorktreeList(stdout) {
+    const worktrees = [];
+    const entries = stdout.trim().split('\n\n'); // Entries are separated by double newlines
+    for (const entry of entries) {
+        const lines = entry.trim().split('\n');
+        let path = '';
+        let head = '';
+        let branch;
+        let isBare = false;
+        let isLocked = false;
+        let isPrunable = false;
+        let prunableReason;
+        for (const line of lines) {
+            if (line.startsWith('worktree ')) {
+                path = line.substring('worktree '.length);
+            }
+            else if (line.startsWith('HEAD ')) {
+                head = line.substring('HEAD '.length);
+            }
+            else if (line.startsWith('branch ')) {
+                branch = line.substring('branch '.length);
+            }
+            else if (line.startsWith('bare')) {
+                isBare = true;
+            }
+            else if (line.startsWith('locked')) {
+                isLocked = true;
+                const reasonMatch = line.match(/locked(?: (.+))?/);
+                if (reasonMatch && reasonMatch[1]) {
+                    prunableReason = reasonMatch[1]; // Using prunableReason for lock reason too
+                }
+            }
+            else if (line.startsWith('prunable')) {
+                isPrunable = true;
+                const reasonMatch = line.match(/prunable(?: (.+))?/);
+                if (reasonMatch && reasonMatch[1]) {
+                    prunableReason = reasonMatch[1];
+                }
+            }
+        }
+        if (path) { // Only add if a path was found
+            worktrees.push({ path, head, branch, isBare, isLocked, isPrunable, prunableReason });
+        }
+    }
+    return worktrees;
+}
+/**
+ * Executes git worktree commands.
+ */
+export async function gitWorktreeLogic(input, context) {
+    const operation = `gitWorktreeLogic:${input.mode}`;
+    logger.debug(`Executing ${operation}`, { ...context, input });
+    let targetPath;
+    try {
+        const workingDir = context.getWorkingDirectory();
+        targetPath = (input.path && input.path !== '.')
+            ? input.path
+            : workingDir ?? '.';
+        if (targetPath === '.' && !workingDir) {
+            logger.warning("Executing git worktree in server's CWD as no path provided and no session WD set.", { ...context, operation });
+            targetPath = process.cwd();
+        }
+        else if (targetPath === '.' && workingDir) {
+            targetPath = workingDir;
+            logger.debug(`Using session working directory: ${targetPath}`, { ...context, operation, sessionId: context.sessionId });
+        }
+        else {
+            logger.debug(`Using provided path: ${targetPath}`, { ...context, operation });
+        }
+        targetPath = sanitization.sanitizePath(targetPath, { allowAbsolute: true }).sanitizedPath;
+    }
+    catch (error) {
+        logger.error('Path resolution or sanitization failed', { ...context, operation, error });
+        if (error instanceof McpError)
+            throw error;
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid path: ${error instanceof Error ? error.message : String(error)}`, { context, operation, originalError: error });
+    }
+    try {
+        let command = `git -C "${targetPath}" worktree `;
+        let result;
+        switch (input.mode) {
+            case 'list':
+                command += 'list';
+                if (input.verbose)
+                    command += ' --porcelain'; // Use porcelain for structured output
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                const { stdout: listStdout } = await execAsync(command);
+                if (input.verbose) {
+                    const worktrees = parsePorcelainWorktreeList(listStdout);
+                    result = { success: true, mode: 'list', worktrees };
+                }
+                else {
+                    // Simple list output parsing (less structured)
+                    const worktrees = listStdout.trim().split('\n').map(line => {
+                        const parts = line.split(/\s+/);
+                        return {
+                            path: parts[0],
+                            head: parts[1],
+                            branch: parts[2]?.replace(/[\[\]]/g, ''), // Remove brackets from branch name
+                            isBare: false, // Cannot determine from simple list
+                            isLocked: false, // Cannot determine
+                            isPrunable: false // Cannot determine
+                        };
+                    });
+                    result = { success: true, mode: 'list', worktrees };
+                }
+                break;
+            case 'add':
+                // worktreePath is guaranteed by refine
+                const sanitizedWorktreePathAdd = sanitization.sanitizePath(input.worktreePath, { allowAbsolute: true, rootDir: targetPath }).sanitizedPath;
+                command += `add `;
+                if (input.force)
+                    command += '--force ';
+                if (input.detach)
+                    command += '--detach ';
+                if (input.newBranch)
+                    command += `-b "${input.newBranch}" `;
+                command += `"${sanitizedWorktreePathAdd}"`;
+                if (input.commitish)
+                    command += ` "${input.commitish}"`;
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                await execAsync(command);
+                // To get the HEAD of the new worktree, we might need another command or parse output if available
+                // For simplicity, we'll report success. A more robust solution might `git -C new_worktree_path rev-parse HEAD`
+                result = {
+                    success: true,
+                    mode: 'add',
+                    worktreePath: sanitizedWorktreePathAdd,
+                    branch: input.newBranch,
+                    head: 'HEAD', // Placeholder, actual SHA would require another call
+                    message: `Worktree '${sanitizedWorktreePathAdd}' added successfully.`
+                };
+                break;
+            case 'remove':
+                // worktreePath is guaranteed by refine
+                const sanitizedWorktreePathRemove = sanitization.sanitizePath(input.worktreePath, { allowAbsolute: true, rootDir: targetPath }).sanitizedPath;
+                command += `remove `;
+                if (input.force)
+                    command += '--force ';
+                command += `"${sanitizedWorktreePathRemove}"`;
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                const { stdout: removeStdout } = await execAsync(command);
+                result = { success: true, mode: 'remove', worktreePath: sanitizedWorktreePathRemove, message: removeStdout.trim() || `Worktree '${sanitizedWorktreePathRemove}' removed successfully.` };
+                break;
+            case 'move':
+                // worktreePath and newPath are guaranteed by refine
+                const sanitizedOldPathMove = sanitization.sanitizePath(input.worktreePath, { allowAbsolute: true, rootDir: targetPath }).sanitizedPath;
+                const sanitizedNewPathMove = sanitization.sanitizePath(input.newPath, { allowAbsolute: true, rootDir: targetPath }).sanitizedPath;
+                command += `move "${sanitizedOldPathMove}" "${sanitizedNewPathMove}"`;
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                await execAsync(command);
+                result = { success: true, mode: 'move', oldPath: sanitizedOldPathMove, newPath: sanitizedNewPathMove, message: `Worktree moved from '${sanitizedOldPathMove}' to '${sanitizedNewPathMove}' successfully.` };
+                break;
+            case 'prune':
+                command += 'prune ';
+                if (input.dryRun)
+                    command += '--dry-run ';
+                if (input.verbose)
+                    command += '--verbose ';
+                if (input.expire)
+                    command += `--expire "${input.expire}" `;
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                const { stdout: pruneStdout, stderr: pruneStderr } = await execAsync(command);
+                // Prune often outputs to stderr even on success for verbose/dry-run
+                const pruneMessage = (pruneStdout.trim() || pruneStderr.trim()) || 'Worktree prune operation completed.';
+                result = { success: true, mode: 'prune', message: pruneMessage };
+                if (input.verbose && pruneStdout.trim()) {
+                    // Attempt to parse verbose output if needed, for now just return raw message
+                    // result.prunedItems = ...
+                }
+                break;
+            default:
+                throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid mode: ${input.mode}`, { context, operation });
+        }
+        logger.info(`${operation} executed successfully`, { ...context, path: targetPath });
+        return result;
+    }
+    catch (error) {
+        const errorMessage = error.stderr || error.stdout || (error.message || '');
+        logger.error(`Failed to execute git worktree command`, { ...context, path: targetPath, error: errorMessage, stderr: error.stderr, stdout: error.stdout });
+        if (errorMessage.toLowerCase().includes('not a git repository')) {
+            throw new McpError(BaseErrorCode.NOT_FOUND, `Path is not a Git repository: ${targetPath}`, { context, operation, originalError: error });
+        }
+        // Add more specific error handling based on `git worktree` messages
+        if (input.mode === 'add' && errorMessage.includes('already exists')) {
+            return { success: false, mode: 'add', message: `Failed to add worktree: Path '${input.worktreePath}' already exists or is a worktree.`, error: errorMessage };
+        }
+        if (input.mode === 'add' && errorMessage.includes('is a submodule')) {
+            return { success: false, mode: 'add', message: `Failed to add worktree: Path '${input.worktreePath}' is a submodule.`, error: errorMessage };
+        }
+        if (input.mode === 'remove' && errorMessage.includes('cannot remove the current worktree')) {
+            return { success: false, mode: 'remove', message: `Failed to remove worktree: Cannot remove the current worktree.`, error: errorMessage };
+        }
+        if (input.mode === 'remove' && errorMessage.includes('has unclean changes')) {
+            return { success: false, mode: 'remove', message: `Failed to remove worktree: '${input.worktreePath}' has uncommitted changes. Use force=true to remove.`, error: errorMessage };
+        }
+        return {
+            success: false,
+            mode: input.mode,
+            message: `Git worktree ${input.mode} failed for path: ${targetPath}.`,
+            error: errorMessage
+        };
+    }
+}

package/dist/mcp-server/tools/gitWorktree/registration.js

@@ -0,0 +1,67 @@
+import { logger, ErrorHandler, requestContextService } from '../../../utils/index.js';
+import { BaseErrorCode } from '../../../types-global/errors.js';
+import { GitWorktreeBaseSchema, gitWorktreeLogic } from './logic.js';
+let _getWorkingDirectory;
+let _getSessionId;
+/**
+ * Initializes the state accessors needed by the git_worktree tool registration.
+ * @param getWdFn - Function to get the working directory for a session.
+ * @param getSidFn - Function to get the session ID from context.
+ */
+export function initializeGitWorktreeStateAccessors(getWdFn, getSidFn) {
+    _getWorkingDirectory = getWdFn;
+    _getSessionId = getSidFn;
+    logger.info('State accessors initialized for git_worktree tool registration.');
+}
+const TOOL_NAME = 'git_worktree';
+const TOOL_DESCRIPTION = 'Manages Git worktrees. Supports listing, adding, removing, moving, and pruning worktrees. Returns results as a JSON object.';
+/**
+ * Registers the git_worktree tool with the MCP server.
+ *
+ * @param {McpServer} server - The McpServer instance to register the tool with.
+ * @returns {Promise<void>}
+ * @throws {Error} If registration fails or state accessors are not initialized.
+ */
+export const registerGitWorktreeTool = async (server) => {
+    if (!_getWorkingDirectory || !_getSessionId) {
+        throw new Error('State accessors for git_worktree must be initialized before registration.');
+    }
+    const operation = 'registerGitWorktreeTool';
+    const context = requestContextService.createRequestContext({ operation });
+    await ErrorHandler.tryCatch(async () => {
+        server.tool(TOOL_NAME, TOOL_DESCRIPTION, GitWorktreeBaseSchema.shape, async (validatedArgs, callContext) => {
+            const toolInput = validatedArgs; // Cast for use
+            const toolOperation = `tool:${TOOL_NAME}:${toolInput.mode}`;
+            const requestContext = requestContextService.createRequestContext({ operation: toolOperation, parentContext: callContext });
+            const sessionId = _getSessionId(requestContext);
+            const getWorkingDirectoryForSession = () => _getWorkingDirectory(sessionId);
+            const logicContext = {
+                ...requestContext,
+                sessionId: sessionId,
+                getWorkingDirectory: getWorkingDirectoryForSession,
+            };
+            logger.info(`Executing tool: ${TOOL_NAME} (mode: ${toolInput.mode})`, logicContext);
+            return await ErrorHandler.tryCatch(async () => {
+                const worktreeResult = await gitWorktreeLogic(toolInput, logicContext);
+                const resultContent = {
+                    type: 'text',
+                    text: JSON.stringify(worktreeResult, null, 2), // Pretty-print JSON
+                    contentType: 'application/json',
+                };
+                if (worktreeResult.success) {
+                    logger.info(`Tool ${TOOL_NAME} (mode: ${toolInput.mode}) executed successfully, returning JSON`, logicContext);
+                }
+                else {
+                    logger.warning(`Tool ${TOOL_NAME} (mode: ${toolInput.mode}) failed: ${worktreeResult.message}`, { ...logicContext, errorDetails: worktreeResult.error });
+                }
+                return { content: [resultContent] };
+            }, {
+                operation: toolOperation,
+                context: logicContext,
+                input: validatedArgs,
+                errorCode: BaseErrorCode.INTERNAL_ERROR,
+            });
+        });
+        logger.info(`Tool registered: ${TOOL_NAME}`, context);
+    }, { operation, context, critical: true });
+};

package/dist/mcp-server/transports/authentication/authMiddleware.js

@@ -1,145 +1,167 @@
 /**
- * MCP Authentication Middleware: Bearer Token Validation (JWT).
+ * @fileoverview MCP Authentication Middleware for Bearer Token Validation (JWT).
  *
  * This middleware validates JSON Web Tokens (JWT) passed via the 'Authorization' header
  * using the 'Bearer' scheme (e.g., "Authorization: Bearer <your_token>").
  * It verifies the token's signature and expiration using the secret key defined
- * in the configuration (MCP_AUTH_SECRET_KEY).
+ * in the configuration (`config.mcpAuthSecretKey`).
  *
- * If the token is valid, the decoded payload is attached to `req.auth` for potential
- * use in downstream authorization logic (e.g., checking scopes or permissions).
+ * If the token is valid, an object conforming to the MCP SDK's `AuthInfo` type
+ * (expected to contain `token`, `clientId`, and `scopes`) is attached to `req.auth`.
  * If the token is missing, invalid, or expired, it sends an HTTP 401 Unauthorized response.
  *
- * --- Scope and Relation to MCP Authorization Spec (2025-03-26) ---
- * - This middleware handles the *validation* of an already obtained Bearer token,
- *   as required by Section 2.6 of the MCP Auth Spec.
- * - It does *NOT* implement the full OAuth 2.1 authorization flows (e.g., Authorization
- *   Code Grant with PKCE), token endpoints (/token), authorization endpoints (/authorize),
- *   metadata discovery (/.well-known/oauth-authorization-server), or dynamic client
- *   registration (/register) described in the specification. It assumes the client
- *   obtained the JWT through an external process compliant with the spec or another
- *   agreed-upon mechanism.
- * - It correctly returns HTTP 401 errors for invalid/missing tokens as per Section 2.8.
- *
- * --- Implementation Details & Requirements ---
- * - Requires the 'jsonwebtoken' package (`npm install jsonwebtoken @types/jsonwebtoken`).
- * - The `MCP_AUTH_SECRET_KEY` environment variable MUST be set to a strong, secret value
- *   in production. The middleware includes a startup check for this.
- * - In non-production environments, if the secret key is missing, authentication checks
- *   are bypassed for development convenience (a warning is logged). THIS IS INSECURE FOR PRODUCTION.
- * - The structure of the JWT payload (e.g., containing user ID, scopes) depends on the
- *   token issuer and is not dictated by this middleware itself, but the payload is made
- *   available on `req.auth`.
- *
  * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
+ * @module src/mcp-server/transports/authentication/authMiddleware
  */
-import jwt from 'jsonwebtoken';
-// Import config, environment constants, and logger
-import { config, environment } from '../../../config/index.js';
-import { logger } from '../../../utils/index.js';
-// --- Startup Validation ---
-// Validate secret key presence on module load (fail fast principle).
-// This prevents the server starting insecurely in production without the key.
-if (environment === 'production' && !config.security.mcpAuthSecretKey) {
-    logger.fatal('CRITICAL: MCP_AUTH_SECRET_KEY is not set in production environment. Authentication cannot proceed securely.');
-    // Throwing an error here will typically stop the Node.js process.
-    throw new Error('MCP_AUTH_SECRET_KEY must be set in production environment for JWT authentication.');
+import jwt from "jsonwebtoken";
+import { config, environment } from "../../../config/index.js";
+import { logger, requestContextService } from "../../../utils/index.js";
+// Startup Validation: Validate secret key presence on module load.
+if (environment === "production" && !config.security.mcpAuthSecretKey) {
+    logger.fatal("CRITICAL: MCP_AUTH_SECRET_KEY is not set in production environment. Authentication cannot proceed securely.");
+    throw new Error("MCP_AUTH_SECRET_KEY must be set in production environment for JWT authentication.");
 }
 else if (!config.security.mcpAuthSecretKey) {
-    // Log a clear warning if running without a key in non-production environments.
-    logger.warning('MCP_AUTH_SECRET_KEY is not set. Authentication middleware will bypass checks (DEVELOPMENT ONLY). This is insecure for production.');
+    logger.warning("MCP_AUTH_SECRET_KEY is not set. Authentication middleware will bypass checks (DEVELOPMENT ONLY). This is insecure for production.");
 }
 /**
- * Express middleware function for verifying JWT Bearer token authentication.
- * Checks the `Authorization` header, verifies the token, and attaches the payload to `req.auth`.
- *
- * @param {Request} req - Express request object.
- * @param {Response} res - Express response object.
- * @param {NextFunction} next - Express next middleware function.
+ * Express middleware for verifying JWT Bearer token authentication.
  */
 export function mcpAuthMiddleware(req, res, next) {
-    // Establish context for logging associated with this middleware execution.
-    const context = { operation: 'mcpAuthMiddleware', method: req.method, path: req.path };
-    logger.debug('Running MCP Authentication Middleware (Bearer Token Validation)...', context);
-    // --- Development Mode Bypass ---
-    // If the secret key is missing (and not in production), bypass authentication.
+    const context = requestContextService.createRequestContext({
+        operation: "mcpAuthMiddleware",
+        method: req.method,
+        path: req.path,
+    });
+    logger.debug("Running MCP Authentication Middleware (Bearer Token Validation)...", context);
+    // Development Mode Bypass
     if (!config.security.mcpAuthSecretKey) {
-        // Double-check environment for safety, although the startup check should prevent this in prod.
-        if (environment !== 'production') {
-            logger.warning('Bypassing JWT authentication: MCP_AUTH_SECRET_KEY is not set (DEVELOPMENT ONLY).', context);
-            // Attach a dummy auth object to indicate bypass for potential downstream checks.
-            req.auth = { devMode: true, warning: 'Auth bypassed due to missing secret key' };
-            return next(); // Proceed without authentication.
+        if (environment !== "production") {
+            logger.warning("Bypassing JWT authentication: MCP_AUTH_SECRET_KEY is not set (DEVELOPMENT ONLY).", context);
+            // Populate req.auth strictly according to SDK's AuthInfo
+            req.auth = {
+                token: "dev-mode-placeholder-token",
+                clientId: "dev-client-id",
+                scopes: ["dev-scope"],
+            };
+            // Log dev mode details separately, not attaching to req.auth if not part of AuthInfo
+            logger.debug("Dev mode auth object created.", {
+                ...context,
+                authDetails: req.auth,
+            });
+            return next();
         }
         else {
-            // Defensive coding: Should be caught by startup check, but handle anyway.
-            logger.error('FATAL: MCP_AUTH_SECRET_KEY is missing in production. Cannot bypass auth.', context);
-            // Send a server error response as this indicates a critical configuration issue.
-            res.status(500).json({ error: 'Server configuration error: Authentication key missing.' });
-            return; // Halt processing.
+            logger.error("FATAL: MCP_AUTH_SECRET_KEY is missing in production. Cannot bypass auth.", context);
+            res.status(500).json({
+                error: "Server configuration error: Authentication key missing.",
+            });
+            return;
         }
     }
-    // --- Standard JWT Bearer Token Verification ---
     const authHeader = req.headers.authorization;
-    logger.debug(`Authorization header present: ${!!authHeader}`, context);
-    // Check for the presence and correct format ('Bearer <token>') of the Authorization header.
-    if (!authHeader || !authHeader.startsWith('Bearer ')) {
-        logger.warning('Authentication failed: Missing or malformed Authorization header (Bearer scheme required).', context);
-        // Respond with 401 Unauthorized as per RFC 6750 (Bearer Token Usage).
-        res.status(401).json({ error: 'Unauthorized: Missing or invalid authentication token format.' });
-        return; // Halt processing.
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+        logger.warning("Authentication failed: Missing or malformed Authorization header (Bearer scheme required).", context);
+        res.status(401).json({
+            error: "Unauthorized: Missing or invalid authentication token format.",
+        });
+        return;
     }
-    // Extract the token part from the "Bearer <token>" string.
-    const token = authHeader.split(' ')[1];
-    // Avoid logging the token itself for security reasons.
-    logger.debug('Extracted token from Bearer header.', context);
-    // Check if a token was actually present after the split.
-    if (!token) {
-        logger.warning('Authentication failed: Token missing after Bearer split (Malformed header).', context);
-        res.status(401).json({ error: 'Unauthorized: Malformed authentication token.' });
-        return; // Halt processing.
+    const tokenParts = authHeader.split(" ");
+    if (tokenParts.length !== 2 || tokenParts[0] !== "Bearer" || !tokenParts[1]) {
+        logger.warning("Authentication failed: Malformed Bearer token.", context);
+        res
+            .status(401)
+            .json({ error: "Unauthorized: Malformed authentication token." });
+        return;
     }
+    const rawToken = tokenParts[1];
     try {
-        // Verify the token's signature and expiration using the configured secret key.
-        // `jwt.verify` throws errors for invalid signature, expiration, etc.
-        const decoded = jwt.verify(token, config.security.mcpAuthSecretKey);
-        // Avoid logging the decoded payload directly unless necessary for specific debugging,
-        // as it might contain sensitive information.
-        logger.debug('JWT verified successfully.', { ...context });
-        // Attach the decoded payload (which can be an object or string based on JWT content)
-        // to the request object (`req.auth`) for use in subsequent middleware or route handlers
-        // (e.g., for fine-grained authorization checks based on payload claims like user ID or scopes).
-        req.auth = decoded;
-        // Authentication successful, proceed to the next middleware or the main route handler.
+        const decoded = jwt.verify(rawToken, config.security.mcpAuthSecretKey);
+        if (typeof decoded === "string") {
+            logger.warning("Authentication failed: JWT decoded to a string, expected an object payload.", context);
+            res
+                .status(401)
+                .json({ error: "Unauthorized: Invalid token payload format." });
+            return;
+        }
+        // Extract and validate fields for SDK's AuthInfo
+        const clientIdFromToken = typeof decoded.cid === "string"
+            ? decoded.cid
+            : typeof decoded.client_id === "string"
+                ? decoded.client_id
+                : undefined;
+        if (!clientIdFromToken) {
+            logger.warning("Authentication failed: JWT 'cid' or 'client_id' claim is missing or not a string.", { ...context, jwtPayloadKeys: Object.keys(decoded) });
+            res.status(401).json({
+                error: "Unauthorized: Invalid token, missing client identifier.",
+            });
+            return;
+        }
+        let scopesFromToken;
+        if (Array.isArray(decoded.scp) &&
+            decoded.scp.every((s) => typeof s === "string")) {
+            scopesFromToken = decoded.scp;
+        }
+        else if (typeof decoded.scope === "string" &&
+            decoded.scope.trim() !== "") {
+            scopesFromToken = decoded.scope.split(" ").filter((s) => s);
+            if (scopesFromToken.length === 0 && decoded.scope.trim() !== "") {
+                // handles case " " -> [""]
+                scopesFromToken = [decoded.scope.trim()];
+            }
+            else if (scopesFromToken.length === 0 && decoded.scope.trim() === "") {
+                // If scope is an empty string, treat as no scopes rather than erroring, or use a default.
+                // Depending on strictness, could also error here. For now, allow empty array if scope was empty string.
+                logger.debug("JWT 'scope' claim was an empty string, resulting in empty scopes array.", context);
+            }
+        }
+        else {
+            // If scopes are strictly mandatory and not found or invalid format
+            logger.warning("Authentication failed: JWT 'scp' or 'scope' claim is missing, not an array of strings, or not a valid space-separated string. Assigning default empty array.", { ...context, jwtPayloadKeys: Object.keys(decoded) });
+            scopesFromToken = []; // Default to empty array if scopes are mandatory but not found/invalid
+            // Or, if truly mandatory and must be non-empty:
+            // res.status(401).json({ error: "Unauthorized: Invalid token, missing or invalid scopes." });
+            // return;
+        }
+        // Construct req.auth with only the properties defined in SDK's AuthInfo
+        // All other claims from 'decoded' are not part of req.auth for type safety.
+        req.auth = {
+            token: rawToken,
+            clientId: clientIdFromToken,
+            scopes: scopesFromToken,
+        };
+        // Log separately if other JWT claims like 'sub' (sessionId) are needed for app logic
+        const subClaimForLogging = typeof decoded.sub === "string" ? decoded.sub : undefined;
+        logger.debug("JWT verified successfully. AuthInfo attached to request.", {
+            ...context,
+            mcpSessionIdContext: subClaimForLogging,
+            clientId: req.auth.clientId,
+            scopes: req.auth.scopes,
+        });
         next();
     }
     catch (error) {
-        // Handle errors thrown by `jwt.verify`.
-        let errorMessage = 'Invalid token'; // Default error message.
+        let errorMessage = "Invalid token";
         if (error instanceof jwt.TokenExpiredError) {
-            // Specific error for expired tokens.
-            errorMessage = 'Token expired';
-            // After instanceof check, 'error' is typed as TokenExpiredError
-            logger.warning('Authentication failed: Token expired.', { ...context, expiredAt: error.expiredAt }); // Log specific details here
+            errorMessage = "Token expired";
+            logger.warning("Authentication failed: Token expired.", {
+                ...context,
+                expiredAt: error.expiredAt,
+            });
         }
         else if (error instanceof jwt.JsonWebTokenError) {
-            // General JWT errors (e.g., invalid signature, malformed token).
-            // After instanceof check, 'error' is typed as JsonWebTokenError
-            errorMessage = `Invalid token: ${error.message}`; // Include specific JWT error message
-            logger.warning(`Authentication failed: ${errorMessage}`, { ...context }); // Log specific details here
+            errorMessage = `Invalid token: ${error.message}`;
+            logger.warning(`Authentication failed: ${errorMessage}`, { ...context });
         }
         else if (error instanceof Error) {
-            // Handle other standard JavaScript errors
             errorMessage = `Verification error: ${error.message}`;
-            logger.error('Authentication failed: Unexpected error during token verification.', { ...context, error: error.message }); // Log specific details here
+            logger.error("Authentication failed: Unexpected error during token verification.", { ...context, error: error.message });
         }
         else {
-            // Handle non-Error exceptions
-            errorMessage = 'Unknown verification error';
-            logger.error('Authentication failed: Unexpected non-error exception during token verification.', { ...context, error });
+            errorMessage = "Unknown verification error";
+            logger.error("Authentication failed: Unexpected non-error exception during token verification.", { ...context, error });
         }
-        // Respond with 401 Unauthorized for any token validation failure.
         res.status(401).json({ error: `Unauthorized: ${errorMessage}.` });
-        // Do not call next() - halt processing for this request.
     }
 }

package/dist/mcp-server/transports/httpTransport.js

@@ -339,6 +339,13 @@ export async function startHttpTransport(createServerInstanceFn, context) {
             logger.debug(`Processing POST request content for session ${currentSessionId}...`, { ...basePostContext, sessionId: currentSessionId, isInitReq });
             // Delegate the actual handling (parsing, routing, response/SSE generation) to the SDK transport instance.
             // The SDK transport handles returning 202 for notification/response-only POSTs internally.
+            // --- Type modification for req.auth compatibility ---
+            const tempReqPost = req; // Allow modification
+            if (tempReqPost.auth && (typeof tempReqPost.auth === 'string' || (typeof tempReqPost.auth === 'object' && 'devMode' in tempReqPost.auth))) {
+                logger.debug('Sanitizing req.auth for SDK compatibility (POST)', { ...basePostContext, sessionId: currentSessionId, originalAuthType: typeof tempReqPost.auth });
+                tempReqPost.auth = undefined;
+            }
+            // --- End modification ---
             await transport.handleRequest(req, res, req.body);
             logger.debug(`Finished processing POST request content for session ${currentSessionId}.`, { ...basePostContext, sessionId: currentSessionId });
         }
@@ -390,6 +397,13 @@ export async function startHttpTransport(createServerInstanceFn, context) {
             // MCP Spec (GET): Client SHOULD include Last-Event-ID for resumption. Resumption handling depends on SDK transport.
             // MCP Spec (DELETE): Client SHOULD send DELETE to terminate. Server MAY respond 405 if not supported.
             // This implementation supports DELETE via the SDK transport's handleRequest.
+            // --- Type modification for req.auth compatibility ---
+            const tempReqSession = req; // Allow modification
+            if (tempReqSession.auth && (typeof tempReqSession.auth === 'string' || (typeof tempReqSession.auth === 'object' && 'devMode' in tempReqSession.auth))) {
+                logger.debug(`Sanitizing req.auth for SDK compatibility (${method})`, { ...baseSessionReqContext, sessionId, originalAuthType: typeof tempReqSession.auth });
+                tempReqSession.auth = undefined;
+            }
+            // --- End modification ---
             await transport.handleRequest(req, res);
             logger.info(`Successfully handled ${method} request for session ${sessionId}`, { ...baseSessionReqContext, sessionId });
             // Note: For DELETE, the transport's handleRequest should trigger the 'onclose' handler for cleanup.
@@ -422,8 +436,8 @@ export async function startHttpTransport(createServerInstanceFn, context) {
         // Determine protocol for logging (basic assumption based on HSTS possibility)
         const protocol = config.environment === 'production' ? 'https' : 'http';
         const serverAddress = `${protocol}://${config.mcpHttpHost}:${actualPort}${MCP_ENDPOINT_PATH}`;
-        // Use console.log for prominent startup message.
-        console.log(`\n🚀 MCP Server running in HTTP mode at: ${serverAddress}\n   (MCP Spec: 2025-03-26 Streamable HTTP Transport)\n`);
+        // Use logger.notice for startup message to ensure MCP compliance and proper handling by clients.
+        logger.notice(`\n🚀 MCP Server running in HTTP mode at: ${serverAddress}\n   (MCP Spec: 2025-03-26 Streamable HTTP Transport)\n`, transportContext);
     }
     catch (err) {
         logger.fatal('HTTP server failed to start after multiple port retries.', { ...transportContext, error: err instanceof Error ? err.message : String(err) });

package/dist/mcp-server/transports/stdioTransport.js

@@ -74,8 +74,8 @@ export async function connectStdioTransport(server, context) {
         await server.connect(transport);
         // Log successful connection. The server is now ready to process messages via stdio.
         logger.info('MCP Server connected and listening via stdio transport.', operationContext);
-        // Use console.log for prominent startup message visibility when run directly.
-        console.log(`\n🚀 MCP Server running in STDIO mode.\n   (MCP Spec: 2025-03-26 Stdio Transport)\n`);
+        // Use logger.notice for startup message to ensure MCP compliance and proper handling by clients.
+        logger.notice(`\n🚀 MCP Server running in STDIO mode.\n   (MCP Spec: 2025-03-26 Stdio Transport)\n`, operationContext);
     }
     catch (err) {
         // Catch and handle any critical errors during the transport connection setup.

package/dist/utils/internal/logger.js

@@ -31,8 +31,40 @@ const logsDir = path.join(projectRoot, 'logs');
 const resolvedLogsDir = path.resolve(logsDir);
 const isLogsDirSafe = resolvedLogsDir === projectRoot || resolvedLogsDir.startsWith(projectRoot + path.sep);
 if (!isLogsDirSafe) {
-    // Use console.error here as logger might not be initialized or safe
-    console.error(`FATAL: logs directory "${resolvedLogsDir}" is outside project root "${projectRoot}". File logging disabled.`);
+    // Use console.error for critical pre-init errors.
+    // Only log to console if TTY to avoid polluting stdout for stdio MCP clients.
+    if (process.stdout.isTTY) {
+        console.error(`FATAL: logs directory "${resolvedLogsDir}" is outside project root "${projectRoot}". File logging disabled.`);
+    }
+}
+/**
+ * Helper function to create the Winston console format.
+ * This is extracted to avoid duplication between initialize and setLevel.
+ */
+function createWinstonConsoleFormat() {
+    return winston.format.combine(winston.format.colorize(), winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }), winston.format.printf(({ timestamp, level, message, ...meta }) => {
+        let metaString = '';
+        const metaCopy = { ...meta };
+        if (metaCopy.error && typeof metaCopy.error === 'object') {
+            const errorObj = metaCopy.error;
+            if (errorObj.message)
+                metaString += `\n  Error: ${errorObj.message}`;
+            if (errorObj.stack)
+                metaString += `\n  Stack: ${String(errorObj.stack).split('\n').map((l) => `    ${l}`).join('\n')}`;
+            delete metaCopy.error;
+        }
+        if (Object.keys(metaCopy).length > 0) {
+            try {
+                const remainingMetaJson = JSON.stringify(metaCopy, null, 2);
+                if (remainingMetaJson !== '{}')
+                    metaString += `\n  Meta: ${remainingMetaJson}`;
+            }
+            catch (stringifyError) {
+                metaString += `\n  Meta: [Error stringifying metadata: ${stringifyError.message}]`;
+            }
+        }
+        return `${timestamp} ${level}: ${message}${metaString}`;
+    }));
 }
 /**
  * Singleton Logger wrapping Winston, adapted for MCP.
@@ -53,21 +85,25 @@ class Logger {
      */
     async initialize(level = 'info') {
         if (this.initialized) {
-            console.warn('Logger already initialized.');
+            this.warning('Logger already initialized.', { loggerSetup: true });
             return;
         }
         this.currentMcpLevel = level;
         this.currentWinstonLevel = mcpToWinstonLevel[level];
+        let logsDirCreatedMessage = null;
         // Ensure logs directory exists
         if (isLogsDirSafe) {
             try {
                 if (!fs.existsSync(resolvedLogsDir)) {
                     fs.mkdirSync(resolvedLogsDir, { recursive: true });
-                    console.log(`Created logs directory: ${resolvedLogsDir}`);
+                    logsDirCreatedMessage = `Created logs directory: ${resolvedLogsDir}`;
                 }
             }
             catch (err) {
-                console.error(`Error creating logs directory at ${resolvedLogsDir}: ${err.message}. File logging disabled.`);
+                // Conditional console output for pre-init errors to avoid issues with stdio MCP clients.
+                if (process.stdout.isTTY) {
+                    console.error(`Error creating logs directory at ${resolvedLogsDir}: ${err.message}. File logging disabled.`);
+                }
             }
         }
         // Common format for files
@@ -78,43 +114,26 @@ class Logger {
             transports.push(new winston.transports.File({ filename: path.join(resolvedLogsDir, 'error.log'), level: 'error', format: fileFormat }), new winston.transports.File({ filename: path.join(resolvedLogsDir, 'warn.log'), level: 'warn', format: fileFormat }), new winston.transports.File({ filename: path.join(resolvedLogsDir, 'info.log'), level: 'info', format: fileFormat }), new winston.transports.File({ filename: path.join(resolvedLogsDir, 'debug.log'), level: 'debug', format: fileFormat }), new winston.transports.File({ filename: path.join(resolvedLogsDir, 'combined.log'), format: fileFormat }));
         }
         else {
-            console.warn("File logging disabled due to unsafe logs directory path.");
+            // Conditional console output for pre-init warnings.
+            if (process.stdout.isTTY) {
+                console.warn("File logging disabled due to unsafe logs directory path.");
+            }
         }
+        let consoleLoggingEnabledMessage = null;
+        let consoleLoggingSkippedMessage = null;
         // Conditionally add Console transport only if:
         // 1. MCP level is 'debug'
         // 2. stdout is a TTY (interactive terminal, not piped)
         if (this.currentMcpLevel === 'debug' && process.stdout.isTTY) {
-            const consoleFormat = winston.format.combine(winston.format.colorize(), winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }), winston.format.printf(({ timestamp, level, message, ...meta }) => {
-                let metaString = '';
-                const metaCopy = { ...meta };
-                if (metaCopy.error && typeof metaCopy.error === 'object') {
-                    const errorObj = metaCopy.error;
-                    if (errorObj.message)
-                        metaString += `\n  Error: ${errorObj.message}`;
-                    if (errorObj.stack)
-                        metaString += `\n  Stack: ${String(errorObj.stack).split('\n').map((l) => `    ${l}`).join('\n')}`;
-                    delete metaCopy.error;
-                }
-                if (Object.keys(metaCopy).length > 0) {
-                    try {
-                        const remainingMetaJson = JSON.stringify(metaCopy, null, 2);
-                        if (remainingMetaJson !== '{}')
-                            metaString += `\n  Meta: ${remainingMetaJson}`;
-                    }
-                    catch (stringifyError) {
-                        metaString += `\n  Meta: [Error stringifying metadata: ${stringifyError.message}]`;
-                    }
-                }
-                return `${timestamp} ${level}: ${message}${metaString}`;
-            }));
+            const consoleFormat = createWinstonConsoleFormat();
             transports.push(new winston.transports.Console({
                 level: 'debug',
                 format: consoleFormat,
             }));
-            console.log(`Console logging enabled at level: debug (stdout is TTY)`);
+            consoleLoggingEnabledMessage = 'Console logging enabled at level: debug (stdout is TTY)';
         }
         else if (this.currentMcpLevel === 'debug' && !process.stdout.isTTY) {
-            console.log(`Console logging skipped: Level is debug, but stdout is not a TTY (likely stdio transport).`);
+            consoleLoggingSkippedMessage = 'Console logging skipped: Level is debug, but stdout is not a TTY (likely stdio transport).';
         }
         // Create logger with the initial Winston level and configured transports
         this.winstonLogger = winston.createLogger({
@@ -122,9 +141,19 @@ class Logger {
             transports,
             exitOnError: false
         });
+        // Log deferred messages now that winstonLogger is initialized
+        if (logsDirCreatedMessage) {
+            this.info(logsDirCreatedMessage, { loggerSetup: true });
+        }
+        if (consoleLoggingEnabledMessage) {
+            this.info(consoleLoggingEnabledMessage, { loggerSetup: true });
+        }
+        if (consoleLoggingSkippedMessage) {
+            this.info(consoleLoggingSkippedMessage, { loggerSetup: true });
+        }
         this.initialized = true;
         await Promise.resolve(); // Yield to event loop
-        this.info(`Logger initialized. File logging level: ${this.currentWinstonLevel}. MCP logging level: ${this.currentMcpLevel}. Console logging: ${process.stdout.isTTY && this.currentMcpLevel === 'debug' ? 'enabled' : 'disabled'}`);
+        this.info(`Logger initialized. File logging level: ${this.currentWinstonLevel}. MCP logging level: ${this.currentMcpLevel}. Console logging: ${process.stdout.isTTY && this.currentMcpLevel === 'debug' ? 'enabled' : 'disabled'}`, { loggerSetup: true });
     }
     /**
      * Sets the function used to send MCP 'notifications/message'.
@@ -132,14 +161,17 @@ class Logger {
     setMcpNotificationSender(sender) {
         this.mcpNotificationSender = sender;
         const status = sender ? 'enabled' : 'disabled';
-        this.info(`MCP notification sending ${status}.`);
+        this.info(`MCP notification sending ${status}.`, { loggerSetup: true });
     }
     /**
      * Dynamically sets the minimum logging level.
      */
     setLevel(newLevel) {
         if (!this.ensureInitialized()) {
-            console.error("Cannot set level: Logger not initialized.");
+            // Conditional console output if logger not usable.
+            if (process.stdout.isTTY) {
+                console.error("Cannot set level: Logger not initialized.");
+            }
             return;
         }
         if (!(newLevel in mcpLevelSeverity)) {
@@ -155,17 +187,17 @@ class Logger {
         const shouldHaveConsole = newLevel === 'debug' && process.stdout.isTTY;
         if (shouldHaveConsole && !consoleTransport) {
             // Add console transport
-            const consoleFormat = winston.format.combine( /* ... same format as in initialize ... */); // TODO: Extract format to avoid duplication
+            const consoleFormat = createWinstonConsoleFormat();
             this.winstonLogger.add(new winston.transports.Console({ level: 'debug', format: consoleFormat }));
-            this.info('Console logging dynamically enabled.');
+            this.info('Console logging dynamically enabled.', { loggerSetup: true });
         }
         else if (!shouldHaveConsole && consoleTransport) {
             // Remove console transport
             this.winstonLogger.remove(consoleTransport);
-            this.info('Console logging dynamically disabled.');
+            this.info('Console logging dynamically disabled.', { loggerSetup: true });
         }
         if (oldLevel !== newLevel) {
-            this.info(`Log level changed. File logging level: ${this.currentWinstonLevel}. MCP logging level: ${this.currentMcpLevel}. Console logging: ${shouldHaveConsole ? 'enabled' : 'disabled'}`);
+            this.info(`Log level changed. File logging level: ${this.currentWinstonLevel}. MCP logging level: ${this.currentMcpLevel}. Console logging: ${shouldHaveConsole ? 'enabled' : 'disabled'}`, { loggerSetup: true });
         }
     }
     /** Get singleton instance. */
@@ -178,7 +210,10 @@ class Logger {
     /** Ensures the logger has been initialized. */
     ensureInitialized() {
         if (!this.initialized || !this.winstonLogger) {
-            console.warn('Logger not initialized; message dropped.');
+            // Conditional console output if logger not usable.
+            if (process.stdout.isTTY) {
+                console.warn('Logger not initialized; message dropped.');
+            }
             return false;
         }
         return true;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@cyanheads/git-mcp-server",
-  "version": "2.0.10",
-  "description": "An MCP (Model Context Protocol) server providing tools to interact with Git repositories. Enables LLMs and AI agents to perform Git operations like clone, commit, push, pull, branch, diff, log, status, and more via the MCP standard.",
+  "version": "2.0.12",
+  "description": "An MCP (Model Context Protocol) server enabling LLMs and AI agents to interact with Git repositories. Provides tools for comprehensive Git operations including clone, commit, branch, diff, log, status, push, pull, merge, rebase, worktree, tag management, and more, via the MCP standard. STDIO & HTTP.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "Casey Hand @cyanheads",
   "repository": {
     "type": "git",
-    "url": "https://github.com/cyanheads/git-mcp-server"
+    "url": "git+https://github.com/cyanheads/git-mcp-server.git"
   },
   "homepage": "https://github.com/cyanheads/git-mcp-server#readme",
   "bugs": {
@@ -17,7 +17,7 @@
     "node": ">=18.0.0"
   },
   "bin": {
-    "git-mcp-server": "./dist/index.js"
+    "git-mcp-server": "dist/index.js"
   },
   "files": [
     "dist"
@@ -37,20 +37,20 @@
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/inspector": "^0.11.0",
-    "@modelcontextprotocol/sdk": "^1.11.0",
+    "@modelcontextprotocol/inspector": "^0.13.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
     "@types/jsonwebtoken": "^9.0.9",
-    "@types/node": "^22.15.15",
+    "@types/node": "^22.15.21",
     "@types/sanitize-html": "^2.16.0",
-    "@types/validator": "^13.15.0",
-    "chrono-node": "^2.8.0",
+    "@types/validator": "^13.15.1",
+    "chrono-node": "2.8.0",
     "dotenv": "^16.5.0",
     "express": "^5.1.0",
     "ignore": "^7.0.4",
     "jsonwebtoken": "^9.0.2",
-    "openai": "^4.97.0",
+    "openai": "^4.103.0",
     "partial-json": "^0.1.7",
-    "sanitize-html": "^2.16.0",
+    "sanitize-html": "^2.17.0",
     "tiktoken": "^1.0.21",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.3",
@@ -58,32 +58,44 @@
     "winston": "^3.17.0",
     "winston-daily-rotate-file": "^5.0.0",
     "yargs": "^17.7.2",
-    "zod": "^3.24.4"
+    "zod": "^3.25.28"
   },
   "keywords": [
     "typescript",
     "MCP",
     "model-context-protocol",
+    "mcp-server",
+    "llm-tools",
+    "git-tools",
     "LLM",
     "AI-integration",
     "server",
     "git",
     "version-control",
     "repository",
-    "commit",
     "branch",
+    "cherry-pick",
+    "clone",
+    "commit",
+    "devops",
     "diff",
+    "fetch",
     "log",
-    "status",
-    "push",
+    "llm-tools",
+    "merge",
     "pull",
-    "clone",
-    "automation",
-    "devops",
+    "push",
+    "rebase",
+    "remote",
+    "reset",
+    "stash",
+    "status",
+    "tag",
+    "worktree",
     "ai-agent",
-    "llm-tools"
+    "automation"
   ],
   "devDependencies": {
-    "@types/express": "^5.0.1"
+    "@types/express": "^5.0.2"
   }
 }