@cyanheads/git-mcp-server 2.0.1 → 2.0.3

package/dist/mcp-server/server.js

@@ -0,0 +1,296 @@
+/**
+ * Main entry point for the MCP (Model Context Protocol) server.
+ * This file orchestrates the server's lifecycle:
+ * 1. Initializes the core McpServer instance with its identity and capabilities.
+ * 2. Registers available resources and tools, making them discoverable and usable by clients.
+ * 3. Selects and starts the appropriate communication transport (stdio or Streamable HTTP)
+ *    based on configuration.
+ * 4. Handles top-level error management during startup.
+ *
+ * MCP Specification References:
+ * - Lifecycle: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/lifecycle.mdx
+ * - Overview (Capabilities): https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/index.mdx
+ * - Transports: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+// Import validated configuration and environment details.
+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 (assuming pattern)
+import { registerGitAddTool, initializeGitAddStateAccessors } from './tools/gitAdd/index.js';
+import { registerGitBranchTool, initializeGitBranchStateAccessors } from './tools/gitBranch/index.js';
+import { registerGitCheckoutTool, initializeGitCheckoutStateAccessors } from './tools/gitCheckout/index.js'; // Assumed initializer
+import { registerGitCherryPickTool, initializeGitCherryPickStateAccessors } from './tools/gitCherryPick/index.js'; // Assumed initializer
+import { registerGitCleanTool, initializeGitCleanStateAccessors } from './tools/gitClean/index.js'; // Assumed initializer
+import { registerGitClearWorkingDirTool, initializeGitClearWorkingDirStateAccessors } from './tools/gitClearWorkingDir/index.js'; // Assumed initializer
+import { registerGitCloneTool } from './tools/gitClone/index.js'; // Removed initializer import
+import { registerGitCommitTool, initializeGitCommitStateAccessors } from './tools/gitCommit/index.js'; // Assumed initializer
+import { registerGitDiffTool, initializeGitDiffStateAccessors } from './tools/gitDiff/index.js'; // Assumed initializer
+import { registerGitFetchTool, initializeGitFetchStateAccessors } from './tools/gitFetch/index.js';
+import { registerGitInitTool, initializeGitInitStateAccessors } from './tools/gitInit/index.js'; // Added initializer import
+import { registerGitLogTool, initializeGitLogStateAccessors } from './tools/gitLog/index.js'; // Assumed initializer
+import { registerGitMergeTool, initializeGitMergeStateAccessors } from './tools/gitMerge/index.js'; // Assumed initializer
+import { registerGitPullTool, initializeGitPullStateAccessors } from './tools/gitPull/index.js';
+import { registerGitPushTool, initializeGitPushStateAccessors } from './tools/gitPush/index.js';
+import { registerGitRebaseTool, initializeGitRebaseStateAccessors } from './tools/gitRebase/index.js'; // Assumed initializer
+import { registerGitRemoteTool, initializeGitRemoteStateAccessors } from './tools/gitRemote/index.js'; // Assumed initializer
+import { registerGitResetTool, initializeGitResetStateAccessors } from './tools/gitReset/index.js'; // Assumed initializer
+import { registerGitSetWorkingDirTool, initializeGitSetWorkingDirStateAccessors } from './tools/gitSetWorkingDir/index.js';
+import { registerGitShowTool, initializeGitShowStateAccessors } from './tools/gitShow/index.js'; // Assumed initializer
+import { registerGitStashTool, initializeGitStashStateAccessors } from './tools/gitStash/index.js'; // Assumed initializer
+import { registerGitStatusTool, initializeGitStatusStateAccessors } from './tools/gitStatus/index.js'; // Assumed initializer
+import { registerGitTagTool, initializeGitTagStateAccessors } from './tools/gitTag/index.js'; // Assumed initializer
+// Import transport setup functions AND state accessors
+import { startHttpTransport, getHttpSessionWorkingDirectory, setHttpSessionWorkingDirectory } from './transports/httpTransport.js';
+import { connectStdioTransport, getStdioWorkingDirectory, setStdioWorkingDirectory } from './transports/stdioTransport.js';
+/**
+ * Creates and configures a new instance of the McpServer.
+ *
+ * This function is central to defining the server's identity and functionality
+ * as presented to connecting clients during the MCP initialization phase.
+ *
+ * MCP Spec Relevance:
+ * - Server Identity (`serverInfo`): The `name` and `version` provided here are part
+ *   of the `ServerInformation` object returned in the `InitializeResult` message,
+ *   allowing clients to identify the server they are connected to.
+ * - Capabilities Declaration: The `capabilities` object declares the features this
+ *   server supports, enabling clients to tailor their interactions.
+ *   - `logging: {}`: Indicates the server can receive `logging/setLevel` requests
+ *     and may send `notifications/message` log messages (handled by the logger utility).
+ *   - `resources: { listChanged: true }`: Signals that the server supports dynamic
+ *     resource lists and will send `notifications/resources/list_changed` if the
+ *     available resources change after initialization. (Currently no resources registered)
+ *   - `tools: { listChanged: true }`: Signals support for dynamic tool lists and
+ *     `notifications/tools/list_changed`.
+ * - Resource/Tool Registration: This function calls specific registration functions
+ *   (e.g., `registerGitAdd`) which use SDK methods (`server.resource`, `server.tool`)
+ *   to make capabilities available for discovery (`resources/list`, `tools/list`) and
+ *   invocation (`resources/read`, `tools/call`).
+ *
+ * Design Note: This factory function is used to create server instances. For the 'stdio'
+ * transport, it's called once. For the 'http' transport, it's passed to `startHttpTransport`
+ * and called *per session* to ensure session isolation.
+ *
+ * @returns {Promise<McpServer>} A promise resolving with the configured McpServer instance.
+ * @throws {Error} If any resource or tool registration fails.
+ */
+// Removed sessionId parameter, it will be retrieved from context within tool handlers
+async function createMcpServerInstance() {
+    const context = { operation: 'createMcpServerInstance' };
+    logger.info('Initializing MCP server instance', context);
+    // Configure the request context service (used for correlating logs/errors).
+    requestContextService.configure({
+        appName: config.mcpServerName,
+        appVersion: config.mcpServerVersion,
+        environment,
+    });
+    // Instantiate the core McpServer using the SDK.
+    // Provide server identity (name, version) and declare supported capabilities.
+    // Note: Resources capability declared, but none are registered currently.
+    logger.debug('Instantiating McpServer with capabilities', { ...context, serverInfo: { name: config.mcpServerName, version: config.mcpServerVersion }, capabilities: { logging: {}, resources: { listChanged: true }, tools: { listChanged: true } } });
+    const server = new McpServer({ name: config.mcpServerName, version: config.mcpServerVersion }, // ServerInformation part of InitializeResult
+    { capabilities: { logging: {}, resources: { listChanged: true }, tools: { listChanged: true } } } // Declared capabilities
+    );
+    // --- Define Unified State Accessor Functions ---
+    // These functions abstract away the transport type to get/set session state.
+    /** Gets the session ID from the tool's execution context. */
+    const getSessionIdFromContext = (toolContext) => {
+        // The RequestContext created by the tool registration wrapper should contain the sessionId.
+        return toolContext?.sessionId;
+    };
+    /** Gets the working directory based on transport type and session ID. */
+    const getWorkingDirectory = (sessionId) => {
+        if (config.mcpTransportType === 'http') {
+            if (!sessionId) {
+                logger.warning('Attempted to get HTTP working directory without session ID', { ...context, caller: 'getWorkingDirectory' });
+                return undefined;
+            }
+            return getHttpSessionWorkingDirectory(sessionId);
+        }
+        else {
+            // For stdio, there's only one implicit session, ID is not needed.
+            return getStdioWorkingDirectory();
+        }
+    };
+    /** Sets the working directory based on transport type and session ID. */
+    const setWorkingDirectory = (sessionId, dir) => {
+        if (config.mcpTransportType === 'http') {
+            if (!sessionId) {
+                logger.error('Attempted to set HTTP working directory without session ID', { ...context, caller: 'setWorkingDirectory', dir });
+                // Optionally throw an error or just log
+                return;
+            }
+            setHttpSessionWorkingDirectory(sessionId, dir);
+        }
+        else {
+            // For stdio, set the single session's directory.
+            setStdioWorkingDirectory(dir);
+        }
+    };
+    // --- Initialize Tool State Accessors BEFORE Registration ---
+    // Pass the defined unified accessor functions to the initializers.
+    logger.debug('Initializing state accessors for tools...', context);
+    try {
+        // Call initializers for all tools that likely need state access.
+        // If an initializer doesn't exist, the import would have failed earlier (or build will fail).
+        initializeGitAddStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitBranchStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitCheckoutStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitCherryPickStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitCleanStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitClearWorkingDirStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        // initializeGitCloneStateAccessors(getWorkingDirectory, getSessionIdFromContext); // Removed call
+        initializeGitCommitStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitDiffStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitFetchStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitInitStateAccessors(getWorkingDirectory, getSessionIdFromContext); // Added call
+        initializeGitLogStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitMergeStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitPullStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitPushStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitRebaseStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitRemoteStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitResetStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitSetWorkingDirStateAccessors(getWorkingDirectory, setWorkingDirectory, getSessionIdFromContext); // Special case
+        initializeGitShowStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitStashStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitStatusStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        initializeGitTagStateAccessors(getWorkingDirectory, getSessionIdFromContext);
+        logger.debug('State accessors initialized successfully.', context);
+    }
+    catch (initError) {
+        // Catch errors specifically during initialization phase
+        logger.error('Failed during state accessor initialization', {
+            ...context,
+            error: initError instanceof Error ? initError.message : String(initError),
+            stack: initError instanceof Error ? initError.stack : undefined,
+        });
+        throw initError; // Re-throw to prevent server starting incorrectly
+    }
+    try {
+        // Register all defined Git tools. These calls populate the server's
+        // internal registry, making them available via MCP methods like 'tools/list'.
+        logger.debug('Registering Git tools...', context);
+        await registerGitAddTool(server);
+        await registerGitBranchTool(server);
+        await registerGitCheckoutTool(server);
+        await registerGitCherryPickTool(server);
+        await registerGitCleanTool(server);
+        await registerGitClearWorkingDirTool(server);
+        await registerGitCloneTool(server);
+        await registerGitCommitTool(server);
+        await registerGitDiffTool(server);
+        await registerGitFetchTool(server);
+        await registerGitInitTool(server);
+        await registerGitLogTool(server);
+        await registerGitMergeTool(server);
+        await registerGitPullTool(server);
+        await registerGitPushTool(server);
+        await registerGitRebaseTool(server);
+        await registerGitRemoteTool(server);
+        await registerGitResetTool(server);
+        await registerGitSetWorkingDirTool(server);
+        await registerGitShowTool(server);
+        await registerGitStashTool(server);
+        await registerGitStatusTool(server);
+        await registerGitTagTool(server);
+        // Add calls to register other resources/tools here if needed in the future.
+        logger.info('Git tools registered successfully', context);
+    }
+    catch (err) {
+        // Registration is critical; log and re-throw errors.
+        logger.error('Failed to register resources/tools', {
+            ...context,
+            error: err instanceof Error ? err.message : String(err),
+            stack: err instanceof Error ? err.stack : undefined, // Include stack for debugging
+        });
+        throw err; // Propagate error to prevent server starting with incomplete capabilities.
+    }
+    return server;
+}
+/**
+ * Selects, sets up, and starts the appropriate MCP transport layer based on configuration.
+ * This function acts as the bridge between the core server logic and the communication channel.
+ *
+ * MCP Spec Relevance:
+ * - Transport Selection: Reads `config.mcpTransportType` ('stdio' or 'http') to determine
+ *   which transport mechanism defined in the MCP specification to use.
+ * - Transport Connection: Calls dedicated functions (`connectStdioTransport` or `startHttpTransport`)
+ *   which handle the specifics of establishing communication according to the chosen
+ *   transport's rules (e.g., stdin/stdout handling for 'stdio', HTTP server setup and
+ *   endpoint handling for 'http').
+ * - Server Instance Lifecycle:
+ *   - For 'stdio', creates a single `McpServer` instance for the lifetime of the process.
+ *   - For 'http', passes the `createMcpServerInstance` factory function to `startHttpTransport`,
+ *     allowing the HTTP transport to create a new, isolated server instance for each client session,
+ *     aligning with the stateful session management described in the Streamable HTTP spec.
+ *
+ * @returns {Promise<McpServer | void>} Resolves with the McpServer instance for 'stdio', or void for 'http'.
+ * @throws {Error} If the configured transport type is unsupported or if transport setup fails.
+ */
+async function startTransport() {
+    // Determine the transport type from the validated configuration.
+    const transportType = config.mcpTransportType;
+    const context = { operation: 'startTransport', transport: transportType };
+    logger.info(`Starting transport: ${transportType}`, context);
+    // --- HTTP Transport Setup ---
+    if (transportType === 'http') {
+        logger.debug('Delegating to startHttpTransport...', context);
+        // For HTTP, the transport layer manages its own lifecycle and potentially multiple sessions.
+        // We pass the factory function to allow the HTTP transport to create server instances as needed (per session).
+        await startHttpTransport(createMcpServerInstance, context);
+        // The HTTP server runs indefinitely, listening for connections, so this function returns void.
+        return;
+    }
+    // --- Stdio Transport Setup ---
+    if (transportType === 'stdio') {
+        logger.debug('Creating single McpServer instance for stdio transport...', context);
+        // For stdio, there's typically one persistent connection managed by a parent process.
+        // Create a single McpServer instance for the entire process lifetime.
+        const server = await createMcpServerInstance();
+        logger.debug('Delegating to connectStdioTransport...', context);
+        // Connect the server instance to the stdio transport handler.
+        await connectStdioTransport(server, context);
+        // Return the server instance; the caller (main entry point) might hold onto it.
+        return server;
+    }
+    // --- Unsupported Transport ---
+    // This case should theoretically not be reached due to config validation, but acts as a safeguard.
+    logger.fatal(`Unsupported transport type configured: ${transportType}`, context);
+    throw new Error(`Unsupported transport type: ${transportType}. Must be 'stdio' or 'http'.`);
+}
+/**
+ * Main application entry point. Initializes and starts the MCP server.
+ *
+ * MCP Spec Relevance:
+ * - Orchestrates the server startup sequence, culminating in a server ready to accept
+ *   connections and process MCP messages according to the chosen transport's rules.
+ * - Implements top-level error handling for critical startup failures, ensuring the
+ *   process exits appropriately if it cannot initialize correctly.
+ *
+ * @returns {Promise<void | McpServer>} Resolves upon successful startup (void for http, McpServer for stdio). Rejects on critical failure.
+ */
+export async function initializeAndStartServer() {
+    const context = { operation: 'initializeAndStartServer' };
+    logger.info('MCP Server initialization sequence started.', context);
+    try {
+        // Initiate the transport setup based on configuration.
+        const result = await startTransport();
+        logger.info('MCP Server initialization sequence completed successfully.', context);
+        return result;
+    }
+    catch (err) {
+        // Catch any errors that occurred during server instance creation or transport setup.
+        logger.fatal('Critical error during MCP server initialization.', {
+            ...context,
+            error: err instanceof Error ? err.message : String(err),
+            stack: err instanceof Error ? err.stack : undefined,
+        });
+        // Use the centralized error handler for consistent critical error reporting.
+        ErrorHandler.handleError(err, { ...context, critical: true });
+        // Exit the process with a non-zero code to indicate failure.
+        logger.info('Exiting process due to critical initialization error.', context);
+        process.exit(1);
+    }
+}

package/{build → dist}/mcp-server/tools/gitAdd/logic.js

@@ -1,13 +1,16 @@
-import { z } from 'zod';
-import { promisify } from 'util';
 import { exec } from 'child_process';
-import { logger } from '../../../utils/logger.js';
-import { McpError, BaseErrorCode } from '../../../types-global/errors.js';
-import { sanitization } from '../../../utils/sanitization.js';
+import { promisify } from 'util';
+import { z } from 'zod';
+// Import utils from barrel (logger from ../utils/internal/logger.js)
+import { logger } from '../../../utils/index.js';
+// Import utils from barrel (RequestContext from ../utils/internal/requestContext.js)
+import { BaseErrorCode, McpError } from '../../../types-global/errors.js'; // Keep direct import for types-global
+// Import utils from barrel (sanitization from ../utils/security/sanitization.js)
+import { sanitization } from '../../../utils/index.js';
 const execAsync = promisify(exec);
 // Define the input schema for the git_add tool using Zod
 export const GitAddInputSchema = z.object({
-    path: z.string().min(1).optional().default('.').describe("Path to the Git repository. Defaults to the session's working directory if set via `git_set_working_dir`, otherwise defaults to the server's current working directory (`.`)."),
+    path: z.string().min(1).optional().default('.').describe("Path to the Git repository. Defaults to the directory set via `git_set_working_dir` for the session; set 'git_set_working_dir' if not set."),
     files: z.union([
         z.string().min(1),
         z.array(z.string().min(1))

package/{build → dist}/mcp-server/tools/gitAdd/registration.js

@@ -1,9 +1,12 @@
-import { logger } from '../../../utils/logger.js';
-import { ErrorHandler } from '../../../utils/errorHandler.js';
-import { requestContextService } from '../../../utils/requestContext.js';
+// Import utils from barrel (logger from ../utils/internal/logger.js)
+import { logger } from '../../../utils/index.js';
+// Import utils from barrel (ErrorHandler from ../utils/internal/errorHandler.js)
+import { ErrorHandler } from '../../../utils/index.js';
+// Import utils from barrel (requestContextService from ../utils/internal/requestContext.js)
+import { requestContextService } from '../../../utils/index.js';
 // Import the result type along with the function and input schema
-import { addGitFiles, GitAddInputSchema } from './logic.js';
 import { BaseErrorCode } from '../../../types-global/errors.js'; // Import BaseErrorCode
+import { addGitFiles, GitAddInputSchema } from './logic.js';
 let _getWorkingDirectory;
 let _getSessionId;
 /**

package/{build → dist}/mcp-server/tools/gitBranch/logic.js

@@ -1,17 +1,20 @@
-import { z } from 'zod';
-import { promisify } from 'util';
 import { exec } from 'child_process';
-import { logger } from '../../../utils/logger.js';
-import { McpError, BaseErrorCode } from '../../../types-global/errors.js';
-import { sanitization } from '../../../utils/sanitization.js';
+import { promisify } from 'util';
+import { z } from 'zod';
+// Import utils from barrel (logger from ../utils/internal/logger.js)
+import { logger } from '../../../utils/index.js';
+// Import utils from barrel (RequestContext from ../utils/internal/requestContext.js)
+import { BaseErrorCode, McpError } from '../../../types-global/errors.js'; // Keep direct import for types-global
+// Import utils from barrel (sanitization from ../utils/security/sanitization.js)
+import { sanitization } from '../../../utils/index.js';
 const execAsync = promisify(exec);
 // Define the BASE input schema for the git_branch tool using Zod
 export const GitBranchBaseSchema = z.object({
-    path: z.string().min(1).optional().default('.').describe("Path to the local Git repository. If omitted, defaults to the path set by `git_set_working_dir` for the current session, or the server's CWD if no session path is set."),
+    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', 'create', 'delete', 'rename', 'show-current']).describe("The branch operation to perform: 'list', 'create', 'delete', 'rename', 'show-current'."),
-    branchName: z.string().min(1).optional().describe("The name of the branch. Required for 'create', 'delete', 'rename' modes."),
-    newBranchName: z.string().min(1).optional().describe("The new name for the branch. Required for 'rename' mode."),
-    startPoint: z.string().min(1).optional().describe("Optional commit hash, tag, or existing branch name to start the new branch from. Used only in 'create' mode. Defaults to HEAD."),
+    branchName: z.string().min(1).optional().describe("The name of the branch (e.g., 'feat/new-login', 'main'). Required for 'create', 'delete', 'rename' modes."),
+    newBranchName: z.string().min(1).optional().describe("The new name for the branch (e.g., 'fix/typo-in-readme'). Required for 'rename' mode."),
+    startPoint: z.string().min(1).optional().describe("Optional commit hash, tag, or existing branch name (e.g., 'main', 'v1.0.0', 'commit-hash') to start the new branch from. Used only in 'create' mode. Defaults to HEAD."),
     force: z.boolean().default(false).describe("Force the operation. Use -D for delete, -M for rename, -f for create (if branch exists). Use with caution, as forcing operations can lead to data loss."),
     all: z.boolean().default(false).describe("List both local and remote-tracking branches. Used only in 'list' mode."),
     remote: z.boolean().default(false).describe("Act on remote-tracking branches. Used with 'list' (-r) or 'delete' (-r)."),
@@ -80,12 +83,20 @@ export async function gitBranchLogic(input, context) {
                     .map(line => {
                     const isCurrent = line.startsWith('* ');
                     const trimmedLine = line.replace(/^\*?\s+/, ''); // Remove leading '*' and spaces
+                    // Determine isRemote based on the raw trimmed line BEFORE splitting
+                    const isRemote = trimmedLine.startsWith('remotes/');
                     const parts = trimmedLine.split(/\s+/);
-                    const name = parts[0];
-                    const isRemote = name.startsWith('remotes/');
+                    const name = parts[0]; // This might be 'remotes/origin/main' or just 'main'
                     const commitHash = parts[1] || undefined; // Verbose gives hash
                     const commitSubject = parts.slice(2).join(' ') || undefined; // Verbose gives subject
-                    return { name, isCurrent, isRemote, commitHash, commitSubject };
+                    // Return the correct name (without 'remotes/' prefix if it was remote) and the isRemote flag
+                    return {
+                        name: isRemote ? name.split('/').slice(2).join('/') : name, // e.g., 'origin/main' or 'main'
+                        isCurrent,
+                        isRemote, // Use the flag determined before splitting
+                        commitHash,
+                        commitSubject
+                    };
                 });
                 const currentBranch = branches.find(b => b.isCurrent)?.name;
                 result = { success: true, mode: 'list', branches, currentBranch };

package/{build → dist}/mcp-server/tools/gitBranch/registration.js

@@ -1,8 +1,11 @@
-import { logger } from '../../../utils/logger.js';
-import { ErrorHandler } from '../../../utils/errorHandler.js';
-import { requestContextService } from '../../../utils/requestContext.js';
-import { gitBranchLogic, GitBranchBaseSchema } from './logic.js';
-import { BaseErrorCode } from '../../../types-global/errors.js';
+// Import utils from barrel (logger from ../utils/internal/logger.js)
+import { logger } from '../../../utils/index.js';
+// Import utils from barrel (ErrorHandler from ../utils/internal/errorHandler.js)
+import { ErrorHandler } from '../../../utils/index.js';
+// Import utils from barrel (requestContextService from ../utils/internal/requestContext.js)
+import { BaseErrorCode } from '../../../types-global/errors.js'; // Keep direct import for types-global
+import { requestContextService } from '../../../utils/index.js';
+import { GitBranchBaseSchema, gitBranchLogic } from './logic.js';
 let _getWorkingDirectory;
 let _getSessionId;
 /**

package/{build → dist}/mcp-server/tools/gitCheckout/logic.js

@@ -1,15 +1,18 @@
-import { z } from 'zod';
-import { promisify } from 'util';
 import { exec } from 'child_process';
-import { logger } from '../../../utils/logger.js';
-import { McpError, BaseErrorCode } from '../../../types-global/errors.js';
-import { sanitization } from '../../../utils/sanitization.js';
+import { promisify } from 'util';
+import { z } from 'zod';
+// Import utils from barrel (logger from ../utils/internal/logger.js)
+import { logger } from '../../../utils/index.js';
+// Import utils from barrel (RequestContext from ../utils/internal/requestContext.js)
+import { BaseErrorCode, McpError } from '../../../types-global/errors.js'; // Keep direct import for types-global
+// Import utils from barrel (sanitization from ../utils/security/sanitization.js)
+import { sanitization } from '../../../utils/index.js';
 const execAsync = promisify(exec);
 // Define the input schema for the git_checkout tool using Zod
 export const GitCheckoutInputSchema = z.object({
-    path: z.string().min(1).optional().default('.').describe("Path to the Git repository. Defaults to the session's working directory if set."),
-    branchOrPath: z.string().min(1).describe("The branch name, commit hash, tag, or file path(s) to checkout."),
-    newBranch: z.string().optional().describe("Create a new branch named <new_branch> and start it at <branchOrPath>."),
+    path: z.string().min(1).optional().default('.').describe("Path to the Git repository. Defaults to the directory set via `git_set_working_dir` for the session; set 'git_set_working_dir' if not set."),
+    branchOrPath: z.string().min(1).describe("The branch name (e.g., 'main'), commit hash, tag, or file path(s) (e.g., './src/file.ts') to checkout."),
+    newBranch: z.string().optional().describe("Create a new branch named <new_branch> (e.g., 'feat/new-feature') and start it at <branchOrPath>."),
     force: z.boolean().optional().default(false).describe("Force checkout even if there are uncommitted changes (use with caution, discards local changes)."),
     // Add other relevant git checkout options as needed (e.g., --track, -b for new branch shorthand)
 });
@@ -72,52 +75,53 @@ export async function checkoutGit(input, context) {
         let currentBranch = undefined;
         let newBranchCreated = !!input.newBranch;
         let filesRestored = undefined;
+        let isDetachedHead = false;
+        let isFileCheckout = false;
+        // --- Initial analysis of checkout output ---
         // Extract previous branch if available
         const prevBranchMatch = stderr.match(/Switched to.*? from ['"]?(.*?)['"]?/);
         if (prevBranchMatch) {
             previousBranch = prevBranchMatch[1];
         }
-        // Extract current branch/state
-        if (stderr.includes('Switched to branch')) {
-            const currentBranchMatch = stderr.match(/Switched to branch ['"]?(.*?)['"]?/);
-            if (currentBranchMatch)
-                currentBranch = currentBranchMatch[1];
-            message = `Switched to branch '${currentBranch || input.branchOrPath}'.`;
-        }
-        else if (stderr.includes('Switched to a new branch')) {
+        // Determine primary outcome from stderr/stdout
+        if (stderr.includes('Switched to a new branch')) {
             const currentBranchMatch = stderr.match(/Switched to a new branch ['"]?(.*?)['"]?/);
-            if (currentBranchMatch)
-                currentBranch = currentBranchMatch[1];
-            message = `Switched to new branch '${currentBranch || input.newBranch}'.`;
-            newBranchCreated = true; // Confirm creation
+            currentBranch = currentBranchMatch ? currentBranchMatch[1] : input.newBranch; // Use matched or input
+            message = `Switched to new branch '${currentBranch}'.`;
+            newBranchCreated = true;
+        }
+        else if (stderr.includes('Switched to branch')) {
+            const currentBranchMatch = stderr.match(/Switched to branch ['"]?(.*?)['"]?/);
+            currentBranch = currentBranchMatch ? currentBranchMatch[1] : input.branchOrPath; // Use matched or input
+            message = `Switched to branch '${currentBranch}'.`;
         }
         else if (stderr.includes('Already on')) {
             const currentBranchMatch = stderr.match(/Already on ['"]?(.*?)['"]?/);
-            if (currentBranchMatch)
-                currentBranch = currentBranchMatch[1];
-            message = `Already on '${currentBranch || input.branchOrPath}'.`;
-        }
-        else if (stderr.includes('Updated N path') || stdout.includes('Updated N path')) { // Checking out files
-            message = `Restored path(s): ${input.branchOrPath}`;
-            // Potentially list the files if input.branchOrPath was specific enough
-            // Assume input.branchOrPath contains file paths separated by newlines
-            filesRestored = input.branchOrPath.split('\n').filter(p => p.trim().length > 0); // Split by newline and filter out empty entries
-            // Try to get current branch after file checkout
-            try {
-                const statusResult = await execAsync(`git -C "${targetPath}" branch --show-current`);
-                currentBranch = statusResult.stdout.trim();
+            currentBranch = currentBranchMatch ? currentBranchMatch[1] : input.branchOrPath; // Use matched or input
+            message = `Already on '${currentBranch}'.`;
+        }
+        else if (stderr.includes('Updated N path') || stdout.includes('Updated N path') || stderr.includes('Your branch is up to date with')) { // Checking out files or confirming current state
+            // Check if the input looks like file paths rather than a branch/commit
+            // This is heuristic - might need refinement if branch names look like paths
+            if (input.branchOrPath.includes('/') || input.branchOrPath.includes('.')) {
+                isFileCheckout = true;
+                message = `Restored or checked path(s): ${input.branchOrPath}`;
+                filesRestored = input.branchOrPath.split('\n').map(p => p.trim()).filter(p => p.length > 0);
             }
-            catch (statusError) {
-                logger.warning('Could not determine current branch after file checkout', { ...context, operation, statusError });
+            else {
+                // Assume it was just confirming the current branch state
+                message = stderr.trim() || stdout.trim() || `Checked out ${input.branchOrPath}.`;
             }
         }
         else if (stderr.includes('Previous HEAD position was') && stderr.includes('HEAD is now at')) { // Detached HEAD
             message = `Checked out commit ${input.branchOrPath} (Detached HEAD state).`;
-            currentBranch = 'Detached HEAD'; // Indicate detached state
+            currentBranch = 'Detached HEAD';
+            isDetachedHead = true;
         }
-        else if (stderr.includes('Note: switching to')) { // Another detached HEAD message variant
+        else if (stderr.includes('Note: switching to') || stderr.includes('Note: checking out')) { // Other detached HEAD variants
             message = `Checked out ${input.branchOrPath} (Detached HEAD state).`;
             currentBranch = 'Detached HEAD';
+            isDetachedHead = true;
         }
         else if (message.includes('fatal:')) {
             success = false;
@@ -125,19 +129,63 @@ export async function checkoutGit(input, context) {
             logger.error(`Git checkout command indicated failure: ${message}`, { ...context, operation, stdout, stderr });
         }
         else if (!message && !stdout && !stderr) {
-            message = 'Checkout command executed, but no output received.';
-            logger.warning(message, { ...context, operation });
-            // Attempt to get current branch as confirmation
+            message = 'Checkout command executed silently.'; // Assume success, will verify branch below
+            logger.info(message, { ...context, operation });
+        }
+        else {
+            // Some other message, treat as informational for now
+            message = stderr.trim() || stdout.trim();
+            logger.info(`Git checkout produced message: ${message}`, { ...context, operation });
+        }
+        // --- Get definitive current branch IF checkout was successful AND not file checkout/detached HEAD ---
+        if (success && !isFileCheckout && !isDetachedHead) {
             try {
+                logger.debug('Attempting to get current branch via git branch --show-current', { ...context, operation });
                 const statusResult = await execAsync(`git -C "${targetPath}" branch --show-current`);
-                currentBranch = statusResult.stdout.trim();
-                message += ` Current branch is '${currentBranch}'.`;
+                const definitiveCurrentBranch = statusResult.stdout.trim();
+                if (definitiveCurrentBranch) {
+                    currentBranch = definitiveCurrentBranch;
+                    logger.info(`Confirmed current branch: ${currentBranch}`, { ...context, operation });
+                    // Refine message if it wasn't specific before
+                    if (message.startsWith('Checkout command executed silently') || message.startsWith('Checked out ')) {
+                        message = `Checked out '${currentBranch}'.`;
+                    }
+                    else if (message.startsWith('Already on') && !message.includes(`'${currentBranch}'`)) {
+                        message = `Already on '${currentBranch}'.`; // Update if initial parse was wrong
+                    }
+                    else if (message.startsWith('Switched to branch') && !message.includes(`'${currentBranch}'`)) {
+                        message = `Switched to branch '${currentBranch}'.`; // Update if initial parse was wrong
+                    }
+                }
+                else {
+                    // Command succeeded but returned empty - might be detached HEAD after all?
+                    logger.warning('git branch --show-current returned empty, possibly detached HEAD?', { ...context, operation });
+                    // Keep potentially parsed 'Detached HEAD' or fallback to input if needed
+                    currentBranch = currentBranch || 'Unknown (possibly detached)';
+                    if (!message.includes('Detached HEAD'))
+                        message += ' (Could not confirm branch name).';
+                }
             }
             catch (statusError) {
-                logger.warning('Could not determine current branch after silent checkout', { ...context, operation, statusError });
+                logger.warning('Could not determine current branch after checkout', { ...context, operation, error: statusError.message });
+                // Keep potentially parsed 'Detached HEAD' or fallback to input if needed
+                currentBranch = currentBranch || 'Unknown (error checking)';
+                if (!message.includes('Detached HEAD'))
+                    message += ' (Error checking branch name).';
+            }
+        }
+        else if (success && isFileCheckout) {
+            // If it was a file checkout, still try to get the branch name for context
+            try {
+                const statusResult = await execAsync(`git -C "${targetPath}" branch --show-current`);
+                currentBranch = statusResult.stdout.trim() || 'Unknown (possibly detached)';
+            }
+            catch {
+                currentBranch = 'Unknown (error checking)';
             }
+            logger.info(`Current branch after file checkout: ${currentBranch}`, { ...context, operation });
         }
-        logger.info(`${operation} completed`, { ...context, operation, path: targetPath, success, message });
+        logger.info(`${operation} completed`, { ...context, operation, path: targetPath, success, message, currentBranch });
         return { success, message, previousBranch, currentBranch, newBranchCreated, filesRestored };
     }
     catch (error) {

package/{build → dist}/mcp-server/tools/gitCheckout/registration.js

@@ -1,8 +1,11 @@
-import { ErrorHandler } from '../../../utils/errorHandler.js';
-import { logger } from '../../../utils/logger.js';
-import { requestContextService } from '../../../utils/requestContext.js';
-import { GitCheckoutInputSchema, checkoutGit } from './logic.js';
-import { BaseErrorCode } from '../../../types-global/errors.js';
+// Import utils from barrel (ErrorHandler from ../utils/internal/errorHandler.js)
+import { ErrorHandler } from '../../../utils/index.js';
+// Import utils from barrel (logger from ../utils/internal/logger.js)
+import { logger } from '../../../utils/index.js';
+// Import utils from barrel (requestContextService, RequestContext from ../utils/internal/requestContext.js)
+import { BaseErrorCode } from '../../../types-global/errors.js'; // Keep direct import for types-global
+import { requestContextService } from '../../../utils/index.js';
+import { checkoutGit, GitCheckoutInputSchema } from './logic.js';
 let _getWorkingDirectory;
 let _getSessionId;
 /**