@cyanheads/git-mcp-server 1.2.4 → 2.0.2

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

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import { promisify } from 'util';
+import { exec } from 'child_process';
+import fs from 'fs/promises';
+import { logger } from '../../../utils/logger.js';
+import { McpError, BaseErrorCode } from '../../../types-global/errors.js';
+import { sanitization } from '../../../utils/sanitization.js';
+const execAsync = promisify(exec);
+// Define the input schema for the git_clone tool using Zod
+export const GitCloneInputSchema = z.object({
+    repositoryUrl: z.string().url("Invalid repository URL format.").describe("The URL of the repository to clone (e.g., https://github.com/cyanheads/git-mcp-server, git@github.com:cyanheads/git-mcp-server.git)."),
+    targetPath: z.string().min(1).describe("The absolute path to the directory where the repository should be cloned."),
+    branch: z.string().optional().describe("Specify a specific branch to checkout after cloning."),
+    depth: z.number().int().positive().optional().describe("Create a shallow clone with a history truncated to the specified number of commits."),
+    // recursive: z.boolean().default(false).describe("After the clone is created, initialize all submodules within, using their default settings."), // Consider adding later
+    quiet: z.boolean().default(false).describe("Operate quietly. Progress is not reported to the standard error stream."),
+});
+/**
+ * Executes the 'git clone' command to clone a repository.
+ *
+ * @param {GitCloneInput} input - The validated input object.
+ * @param {RequestContext} context - The request context for logging and error handling.
+ * @returns {Promise<GitCloneResult>} A promise that resolves with the structured clone result.
+ * @throws {McpError} Throws an McpError if path/URL validation fails or the git command fails unexpectedly.
+ */
+export async function gitCloneLogic(input, context) {
+    const operation = 'gitCloneLogic';
+    logger.debug(`Executing ${operation}`, { ...context, input });
+    let sanitizedTargetPath;
+    let sanitizedRepoUrl;
+    try {
+        // Sanitize the target path (must be absolute)
+        sanitizedTargetPath = sanitization.sanitizePath(input.targetPath);
+        logger.debug('Sanitized target path', { ...context, operation, sanitizedTargetPath });
+        // Basic sanitization/validation for URL (Zod already checks format)
+        // Further sanitization might be needed depending on how it's used in the shell command
+        // For now, rely on Zod's URL validation and careful command construction.
+        sanitizedRepoUrl = input.repositoryUrl; // Assume Zod validation is sufficient for now
+        logger.debug('Validated repository URL', { ...context, operation, sanitizedRepoUrl });
+        // Check if target directory already exists and is not empty
+        try {
+            const stats = await fs.stat(sanitizedTargetPath);
+            if (stats.isDirectory()) {
+                const files = await fs.readdir(sanitizedTargetPath);
+                if (files.length > 0) {
+                    throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Target directory already exists and is not empty: ${sanitizedTargetPath}`, { context, operation });
+                }
+            }
+            else {
+                throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Target path exists but is not a directory: ${sanitizedTargetPath}`, { context, operation });
+            }
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error; // Re-throw our specific validation errors
+            if (error.code !== 'ENOENT') {
+                // If error is not "does not exist", it's unexpected
+                logger.error(`Error checking target directory ${sanitizedTargetPath}`, { ...context, operation, error: error.message });
+                throw new McpError(BaseErrorCode.INTERNAL_ERROR, `Failed to check target directory: ${error.message}`, { context, operation });
+            }
+            // ENOENT is expected - directory doesn't exist, which is fine for clone
+            logger.debug(`Target directory ${sanitizedTargetPath} does not exist, proceeding with clone.`, { ...context, operation });
+        }
+    }
+    catch (error) {
+        logger.error('Path/URL validation or sanitization failed', { ...context, operation, error });
+        if (error instanceof McpError)
+            throw error;
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid input: ${error instanceof Error ? error.message : String(error)}`, { context, operation, originalError: error });
+    }
+    try {
+        // Construct the git clone command
+        // Use placeholders and pass args safely if possible, but exec requires string command. Be careful with quoting.
+        let command = `git clone`;
+        if (input.quiet) {
+            command += ' --quiet';
+        }
+        if (input.branch) {
+            command += ` --branch "${input.branch.replace(/"/g, '\\"')}"`;
+        }
+        if (input.depth) {
+            command += ` --depth ${input.depth}`;
+        }
+        // Add repo URL and target path (ensure they are quoted)
+        command += ` "${sanitizedRepoUrl}" "${sanitizedTargetPath}"`;
+        logger.debug(`Executing command: ${command}`, { ...context, operation });
+        // Increase timeout for clone operations as they can take time
+        const { stdout, stderr } = await execAsync(command, { timeout: 300000 }); // 5 minutes timeout
+        if (stderr && !input.quiet) {
+            // Stderr often contains progress info, log as info if quiet is false
+            logger.info(`Git clone command produced stderr (progress/info)`, { ...context, operation, stderr });
+        }
+        if (stdout && !input.quiet) {
+            logger.info(`Git clone command produced stdout`, { ...context, operation, stdout });
+        }
+        // Verify the target directory exists after clone
+        let repoDirExists = false;
+        try {
+            await fs.access(sanitizedTargetPath);
+            repoDirExists = true;
+        }
+        catch (e) {
+            logger.error(`Could not verify existence of target directory ${sanitizedTargetPath} after git clone`, { ...context, operation });
+            // This indicates a potential failure despite exec not throwing
+            throw new McpError(BaseErrorCode.INTERNAL_ERROR, `Clone command finished but target directory ${sanitizedTargetPath} not found.`, { context, operation });
+        }
+        const successMessage = `Repository cloned successfully into ${sanitizedTargetPath}`;
+        logger.info(`${operation} executed successfully`, { ...context, operation, path: sanitizedTargetPath });
+        return {
+            success: true,
+            message: successMessage,
+            path: sanitizedTargetPath,
+            repoDirExists: repoDirExists
+        };
+    }
+    catch (error) {
+        const errorMessage = error.stderr || error.message || '';
+        logger.error(`Failed to execute git clone command`, { ...context, operation, path: sanitizedTargetPath, error: errorMessage, stderr: error.stderr, stdout: error.stdout });
+        // Handle specific error cases
+        if (errorMessage.toLowerCase().includes('repository not found') || errorMessage.toLowerCase().includes('could not read from remote repository')) {
+            throw new McpError(BaseErrorCode.NOT_FOUND, `Repository not found or access denied: ${sanitizedRepoUrl}. Error: ${errorMessage}`, { context, operation, originalError: error });
+        }
+        if (errorMessage.toLowerCase().includes('already exists and is not an empty directory')) {
+            // This should have been caught by our pre-check, but handle defensively
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Target directory already exists and is not empty: ${sanitizedTargetPath}. Error: ${errorMessage}`, { context, operation, originalError: error });
+        }
+        if (errorMessage.toLowerCase().includes('permission denied')) {
+            throw new McpError(BaseErrorCode.FORBIDDEN, `Permission denied during clone operation for path: ${sanitizedTargetPath}. Error: ${errorMessage}`, { context, operation, originalError: error });
+        }
+        if (errorMessage.toLowerCase().includes('timeout')) {
+            throw new McpError(BaseErrorCode.TIMEOUT, `Git clone operation timed out for repository: ${sanitizedRepoUrl}. Error: ${errorMessage}`, { context, operation, originalError: error });
+        }
+        // Generic internal error for other failures
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, `Failed to clone repository ${sanitizedRepoUrl} to ${sanitizedTargetPath}. Error: ${errorMessage}`, { context, operation, originalError: error });
+    }
+}

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

@@ -0,0 +1,44 @@
+import { ErrorHandler } from '../../../utils/errorHandler.js';
+import { logger } from '../../../utils/logger.js';
+import { requestContextService } from '../../../utils/requestContext.js';
+import { GitCloneInputSchema, gitCloneLogic } from './logic.js';
+import { BaseErrorCode } from '../../../types-global/errors.js';
+const TOOL_NAME = 'git_clone';
+const TOOL_DESCRIPTION = 'Clones a Git repository from a given URL into a specified absolute directory path. Supports cloning specific branches and setting clone depth.';
+/**
+ * Registers the git_clone tool with the MCP server.
+ *
+ * @param {McpServer} server - The McpServer instance to register the tool with.
+ * @returns {Promise<void>}
+ * @throws {Error} If registration fails.
+ */
+export const registerGitCloneTool = async (server) => {
+    const operation = 'registerGitCloneTool';
+    const context = requestContextService.createRequestContext({ operation });
+    await ErrorHandler.tryCatch(async () => {
+        server.tool(TOOL_NAME, TOOL_DESCRIPTION, GitCloneInputSchema.shape, // Provide the Zod schema shape
+        async (validatedArgs, callContext) => {
+            const toolOperation = 'tool:git_clone';
+            const requestContext = requestContextService.createRequestContext({ operation: toolOperation, parentContext: callContext });
+            logger.info(`Executing tool: ${TOOL_NAME}`, requestContext);
+            return await ErrorHandler.tryCatch(async () => {
+                // Call the core logic function
+                const cloneResult = await gitCloneLogic(validatedArgs, requestContext);
+                // Format the result as a JSON string within TextContent
+                const resultContent = {
+                    type: 'text',
+                    text: JSON.stringify(cloneResult, null, 2), // Pretty-print JSON
+                    contentType: 'application/json',
+                };
+                logger.info(`Tool ${TOOL_NAME} executed successfully, returning JSON`, requestContext);
+                return { content: [resultContent] };
+            }, {
+                operation: toolOperation,
+                context: requestContext,
+                input: validatedArgs, // Log sanitized input
+                errorCode: BaseErrorCode.INTERNAL_ERROR, // Default if unexpected error occurs
+            });
+        });
+        logger.info(`Tool registered: ${TOOL_NAME}`, context);
+    }, { operation, context, critical: true }); // Mark registration as critical
+};

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

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

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

@@ -0,0 +1,129 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { z } from 'zod';
+import { BaseErrorCode, McpError } from '../../../types-global/errors.js';
+import { logger } from '../../../utils/logger.js';
+import { sanitization } from '../../../utils/sanitization.js';
+const execAsync = promisify(exec);
+// Define the input schema for the git_commit tool using Zod
+export const GitCommitInputSchema = 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 (`.`)."),
+    message: z.string().min(1).describe('Commit message. Follow Conventional Commits format: `type(scope): subject`. Example: `feat(api): add user signup endpoint`'),
+    author: z.object({
+        name: z.string().describe('Author name for the commit'),
+        email: z.string().email().describe('Author email for the commit'),
+    }).optional().describe('Overrides the commit author information (name and email). Use only when necessary (e.g., applying external patches).'),
+    allowEmpty: z.boolean().default(false).describe('Allow creating empty commits'),
+    amend: z.boolean().default(false).describe('Amend the previous commit instead of creating a new one'),
+});
+/**
+ * Executes the 'git commit' command and returns structured JSON output.
+ *
+ * @param {GitCommitInput} input - The validated input object.
+ * @param {RequestContext} context - The request context for logging and error handling.
+ * @returns {Promise<GitCommitResult>} A promise that resolves with the structured commit result.
+ * @throws {McpError} Throws an McpError if path resolution or validation fails, or if the git command fails unexpectedly.
+ */
+export async function commitGitChanges(input, context // Add getter to context
+) {
+    const operation = 'commitGitChanges';
+    logger.debug(`Executing ${operation}`, { ...context, input });
+    let targetPath;
+    try {
+        // Resolve the target path
+        if (input.path && input.path !== '.') {
+            targetPath = input.path;
+            logger.debug(`Using provided path: ${targetPath}`, { ...context, operation });
+        }
+        else {
+            const workingDir = context.getWorkingDirectory();
+            if (!workingDir) {
+                throw new McpError(BaseErrorCode.VALIDATION_ERROR, "No path provided and no working directory set for the session.", { context, operation });
+            }
+            targetPath = workingDir;
+            logger.debug(`Using session working directory: ${targetPath}`, { ...context, operation, sessionId: context.sessionId });
+        }
+        // Sanitize the resolved path
+        const sanitizedPath = sanitization.sanitizePath(targetPath);
+        logger.debug('Sanitized path', { ...context, operation, sanitizedPath });
+        targetPath = sanitizedPath; // Use the sanitized path going forward
+    }
+    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 {
+        // Construct the git commit command using the resolved targetPath
+        let command = `git -C "${targetPath}" commit -m "${input.message.replace(/"/g, '\\"')}"`; // Escape double quotes
+        if (input.allowEmpty) {
+            command += ' --allow-empty';
+        }
+        if (input.amend) {
+            command += ' --amend --no-edit';
+        }
+        if (input.author) {
+            // Ensure author details are properly escaped if needed, though exec usually handles this
+            command = `git -C "${targetPath}" -c user.name="${input.author.name.replace(/"/g, '\\"')}" -c user.email="${input.author.email.replace(/"/g, '\\"')}" commit -m "${input.message.replace(/"/g, '\\"')}"`;
+            if (input.allowEmpty)
+                command += ' --allow-empty';
+            if (input.amend)
+                command += ' --amend --no-edit';
+        }
+        logger.debug(`Executing command: ${command}`, { ...context, operation });
+        const { stdout, stderr } = await execAsync(command);
+        // Check stderr first for common non-error messages
+        if (stderr) {
+            if (stderr.includes('nothing to commit, working tree clean') || stderr.includes('no changes added to commit')) {
+                const msg = stderr.includes('nothing to commit') ? 'Nothing to commit, working tree clean.' : 'No changes added to commit.';
+                logger.info(msg, { ...context, operation, path: targetPath });
+                // Use statusMessage
+                return { success: true, statusMessage: msg, nothingToCommit: true };
+            }
+            // Log other stderr as warning but continue, as commit might still succeed
+            logger.warning(`Git commit command produced stderr`, { ...context, operation, stderr });
+        }
+        // Extract commit hash (more robustly)
+        let commitHash = undefined;
+        const hashMatch = stdout.match(/([a-f0-9]{7,40})/); // Look for typical short or long hash
+        if (hashMatch) {
+            commitHash = hashMatch[1];
+        }
+        else {
+            // Fallback parsing if needed, or rely on success message
+            logger.warning('Could not parse commit hash from stdout', { ...context, operation, stdout });
+        }
+        // Use statusMessage
+        const statusMsg = commitHash
+            ? `Commit successful: ${commitHash}`
+            : `Commit successful (stdout: ${stdout.trim()})`;
+        logger.info(`${operation} executed successfully`, { ...context, operation, path: targetPath, commitHash });
+        return {
+            success: true,
+            statusMessage: statusMsg,
+            commitHash: commitHash
+        };
+    }
+    catch (error) {
+        logger.error(`Failed to execute git commit command`, { ...context, operation, path: targetPath, error: error.message, stderr: error.stderr });
+        const errorMessage = error.stderr || error.message || '';
+        // Handle specific error cases first
+        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 });
+        }
+        if (errorMessage.includes('nothing to commit') || errorMessage.includes('no changes added to commit')) {
+            // This might happen if git exits with error despite these messages
+            const msg = errorMessage.includes('nothing to commit') ? 'Nothing to commit, working tree clean.' : 'No changes added to commit.';
+            logger.info(msg + ' (caught as error)', { ...context, operation, path: targetPath, errorMessage });
+            // Return success=false but indicate the reason using statusMessage
+            return { success: false, statusMessage: msg, nothingToCommit: true };
+        }
+        if (errorMessage.includes('conflicts')) {
+            throw new McpError(BaseErrorCode.CONFLICT, `Commit failed due to unresolved conflicts in ${targetPath}`, { context, operation, originalError: error });
+        }
+        // Generic internal error for other failures
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, `Failed to commit changes for path: ${targetPath}. Error: ${errorMessage}`, { context, operation, originalError: error });
+    }
+}

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

@@ -0,0 +1,100 @@
+import { ErrorHandler } from '../../../utils/errorHandler.js';
+import { logger } from '../../../utils/logger.js';
+import { requestContextService } from '../../../utils/requestContext.js';
+// Import the result type along with the function and input schema
+import { BaseErrorCode } from '../../../types-global/errors.js'; // Import BaseErrorCode
+import { commitGitChanges, GitCommitInputSchema } from './logic.js';
+let _getWorkingDirectory;
+let _getSessionId;
+/**
+ * Initializes the state accessors needed by the tool registration.
+ * This should be called once during server setup.
+ * @param getWdFn - Function to get the working directory for a session.
+ * @param getSidFn - Function to get the session ID from context.
+ */
+export function initializeGitCommitStateAccessors(getWdFn, getSidFn) {
+    _getWorkingDirectory = getWdFn;
+    _getSessionId = getSidFn;
+    logger.info('State accessors initialized for git_commit tool registration.');
+}
+const TOOL_NAME = 'git_commit';
+const TOOL_DESCRIPTION = `Commits staged changes to the Git repository index with a descriptive message. Supports author override, amending, and empty commits. Returns a JSON result.
+
+**Commit Message Guidance:**
+Write clear, concise commit messages using the Conventional Commits format: \`type(scope): subject\`.
+- \`type\`: feat, fix, docs, style, refactor, test, chore, etc.
+- \`(scope)\`: Optional context (e.g., \`auth\`, \`ui\`, filename).
+- \`subject\`: Imperative, present tense description (e.g., "add login button", not "added login button").
+
+**Example Commit Message:**
+\`\`\`
+feat(auth): implement password reset endpoint
+
+Adds the /api/auth/reset-password endpoint to allow users
+to reset their password via an email link. Includes input
+validation and rate limiting.
+
+Closes #123 (if applicable).
+\`\`\`
+
+**Best Practice:** Commit related changes together in logical units. If you've modified multiple files for a single feature or fix, stage and commit them together with a message that describes the overall change.
+
+**Path Handling:** If the 'path' parameter is omitted or set to '.', the tool uses the working directory set by 'git_set_working_dir'. Providing a full, absolute path overrides this default and ensures explicitness.`;
+/**
+ * Registers the git_commit tool with the MCP server.
+ * Uses the high-level server.tool() method for registration, schema validation, and routing.
+ *
+ * @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 registerGitCommitTool = async (server) => {
+    if (!_getWorkingDirectory || !_getSessionId) {
+        throw new Error('State accessors for git_commit must be initialized before registration.');
+    }
+    const operation = 'registerGitCommitTool';
+    const context = requestContextService.createRequestContext({ operation });
+    await ErrorHandler.tryCatch(async () => {
+        server.tool(TOOL_NAME, TOOL_DESCRIPTION, GitCommitInputSchema.shape, // Provide the Zod schema shape
+        async (validatedArgs, callContext) => {
+            const toolOperation = 'tool:git_commit';
+            const requestContext = requestContextService.createRequestContext({ operation: toolOperation, parentContext: callContext });
+            const sessionId = _getSessionId(requestContext);
+            const getWorkingDirectoryForSession = () => {
+                return _getWorkingDirectory(sessionId);
+            };
+            const logicContext = {
+                ...requestContext,
+                sessionId: sessionId,
+                getWorkingDirectory: getWorkingDirectoryForSession,
+            };
+            logger.info(`Executing tool: ${TOOL_NAME}`, logicContext);
+            return await ErrorHandler.tryCatch(async () => {
+                // Call the core logic function which now returns a GitCommitResult object
+                const commitResult = await commitGitChanges(validatedArgs, logicContext);
+                // Format the result as a JSON string within TextContent
+                const resultContent = {
+                    type: 'text',
+                    // Stringify the JSON object for the response content
+                    text: JSON.stringify(commitResult, null, 2), // Pretty-print JSON
+                    contentType: 'application/json',
+                };
+                // Log based on the success flag in the result
+                if (commitResult.success) {
+                    logger.info(`Tool ${TOOL_NAME} executed successfully, returning JSON`, logicContext);
+                }
+                else {
+                    logger.info(`Tool ${TOOL_NAME} completed with non-fatal condition (e.g., nothing to commit), returning JSON`, logicContext);
+                }
+                // Even if success is false (e.g., nothing to commit), it's not a tool execution 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/tools/gitDiff/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel file for the gitDiff tool.
+ */
+export { registerGitDiffTool, initializeGitDiffStateAccessors } from './registration.js';
+// Export types if needed elsewhere, e.g.:
+// export type { GitDiffInput, GitDiffResult } from './logic.js';

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

@@ -0,0 +1,114 @@
+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';
+const execAsync = promisify(exec);
+// Define the base input schema without refinement
+const GitDiffInputBaseSchema = z.object({
+    path: z.string().min(1).optional().default('.').describe("Path to the Git repository. Defaults to the session's working directory if set."),
+    commit1: z.string().optional().describe("First commit, branch, or ref for comparison. If omitted, compares against the working tree or index (depending on 'staged')."),
+    commit2: z.string().optional().describe("Second commit, branch, or ref for comparison. If omitted, compares commit1 against the working tree or index."),
+    staged: z.boolean().optional().default(false).describe("Show diff of changes staged for the next commit (compares index against HEAD). Overrides commit1/commit2 if true."),
+    file: z.string().optional().describe("Limit the diff output to a specific file path."),
+    // Add options like --name-only, --stat, context lines (-U<n>) if needed
+});
+// Export the shape for registration
+export const GitDiffInputShape = GitDiffInputBaseSchema.shape;
+// Define the final schema with refinement for validation during execution
+export const GitDiffInputSchema = GitDiffInputBaseSchema.refine(data => !(data.staged && (data.commit1 || data.commit2)), {
+    message: "Cannot use 'staged' option with specific commit references (commit1 or commit2).",
+    path: ["staged", "commit1", "commit2"], // Indicate related fields
+});
+/**
+ * Executes the 'git diff' command and returns the diff output.
+ *
+ * @param {GitDiffInput} input - The validated input object.
+ * @param {RequestContext} context - The request context for logging and error handling.
+ * @returns {Promise<GitDiffResult>} A promise that resolves with the structured diff result.
+ * @throws {McpError} Throws an McpError if path resolution, validation, or the git command fails unexpectedly.
+ */
+export async function diffGitChanges(input, context) {
+    const operation = 'diffGitChanges';
+    logger.debug(`Executing ${operation}`, { ...context, input });
+    let targetPath;
+    try {
+        // Resolve and sanitize the target path
+        if (input.path && input.path !== '.') {
+            targetPath = input.path;
+        }
+        else {
+            const workingDir = context.getWorkingDirectory();
+            if (!workingDir) {
+                throw new McpError(BaseErrorCode.VALIDATION_ERROR, "No path provided and no working directory set for the session.", { context, operation });
+            }
+            targetPath = workingDir;
+        }
+        targetPath = sanitization.sanitizePath(targetPath);
+        logger.debug('Sanitized path', { ...context, operation, sanitizedPath: targetPath });
+    }
+    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 });
+    }
+    // Basic sanitization for refs and file path
+    const safeCommit1 = input.commit1?.replace(/[`$&;*()|<>]/g, '');
+    const safeCommit2 = input.commit2?.replace(/[`$&;*()|<>]/g, '');
+    const safeFile = input.file?.replace(/[`$&;*()|<>]/g, '');
+    try {
+        // Construct the git diff command
+        let command = `git -C "${targetPath}" diff`;
+        if (input.staged) {
+            command += ' --staged'; // Or --cached
+        }
+        else {
+            // Add commit references if not doing staged diff
+            if (safeCommit1) {
+                command += ` ${safeCommit1}`;
+            }
+            if (safeCommit2) {
+                command += ` ${safeCommit2}`;
+            }
+        }
+        // Add file path limiter if provided
+        if (safeFile) {
+            command += ` -- "${safeFile}"`; // Use '--' to separate paths from revisions
+        }
+        logger.debug(`Executing command: ${command}`, { ...context, operation });
+        // Execute command. Diff output is primarily on stdout.
+        // Increase maxBuffer as diffs can be large.
+        const { stdout, stderr } = await execAsync(command, { maxBuffer: 1024 * 1024 * 20 }); // 20MB buffer
+        if (stderr) {
+            // Log stderr as warning, as it might contain non-fatal info
+            logger.warning(`Git diff stderr: ${stderr}`, { ...context, operation });
+        }
+        const diffOutput = stdout;
+        const message = diffOutput.trim() === '' ? 'No changes found.' : 'Diff generated successfully.';
+        logger.info(`${operation} completed successfully. ${message}`, { ...context, operation, path: targetPath });
+        return { success: true, diff: diffOutput, message };
+    }
+    catch (error) {
+        logger.error(`Failed to execute git diff command`, { ...context, operation, path: targetPath, error: error.message, stderr: error.stderr, stdout: error.stdout });
+        const errorMessage = error.stderr || error.stdout || error.message || '';
+        // Handle specific error cases
+        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 });
+        }
+        if (errorMessage.includes('fatal: bad object') || errorMessage.includes('unknown revision or path not in the working tree')) {
+            const invalidRef = input.commit1 || input.commit2 || input.file;
+            throw new McpError(BaseErrorCode.NOT_FOUND, `Invalid commit reference or file path specified: '${invalidRef}'. Error: ${errorMessage}`, { context, operation, originalError: error });
+        }
+        if (errorMessage.includes('ambiguous argument')) {
+            const ambiguousArg = input.commit1 || input.commit2 || input.file;
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Ambiguous argument provided: '${ambiguousArg}'. Error: ${errorMessage}`, { context, operation, originalError: error });
+        }
+        // If the command exits with an error but stdout has content, it might still be useful (e.g., diff with conflicts)
+        // However, standard 'git diff' usually exits 0 even with differences. Errors typically mean invalid input/repo state.
+        // We'll treat most exec errors as failures.
+        // Generic internal error for other failures
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, `Failed to get git diff for path: ${targetPath}. Error: ${errorMessage}`, { context, operation, originalError: error });
+    }
+}

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

@@ -0,0 +1,74 @@
+import { ErrorHandler } from '../../../utils/errorHandler.js';
+import { logger } from '../../../utils/logger.js';
+import { requestContextService } from '../../../utils/requestContext.js';
+// Import the shape and the final schema/types
+import { GitDiffInputShape, diffGitChanges } from './logic.js';
+import { BaseErrorCode } from '../../../types-global/errors.js';
+let _getWorkingDirectory;
+let _getSessionId;
+/**
+ * Initializes the state accessors needed by the tool registration.
+ * This should be called once during server setup.
+ * @param getWdFn - Function to get the working directory for a session.
+ * @param getSidFn - Function to get the session ID from context.
+ */
+export function initializeGitDiffStateAccessors(getWdFn, getSidFn) {
+    _getWorkingDirectory = getWdFn;
+    _getSessionId = getSidFn;
+    logger.info('State accessors initialized for git_diff tool registration.');
+}
+const TOOL_NAME = 'git_diff';
+const TOOL_DESCRIPTION = "Shows changes between commits, commit and working tree, etc. Can show staged changes or diff specific files. Returns the diff output as plain text.";
+/**
+ * Registers the git_diff tool with the MCP server.
+ *
+ * @param {McpServer} server - The MCP server instance.
+ * @throws {Error} If state accessors are not initialized.
+ */
+export async function registerGitDiffTool(server) {
+    if (!_getWorkingDirectory || !_getSessionId) {
+        throw new Error('State accessors for git_diff must be initialized before registration.');
+    }
+    const operation = 'registerGitDiffTool';
+    const context = requestContextService.createRequestContext({ operation });
+    await ErrorHandler.tryCatch(async () => {
+        // Use the exported shape for registration
+        server.tool(TOOL_NAME, TOOL_DESCRIPTION, GitDiffInputShape, // Provide the Zod base schema shape
+        async (validatedArgs, callContext) => {
+            const toolOperation = 'tool:git_diff';
+            const requestContext = requestContextService.createRequestContext({ operation: toolOperation, parentContext: callContext });
+            const sessionId = _getSessionId(requestContext);
+            const getWorkingDirectoryForSession = () => {
+                return _getWorkingDirectory(sessionId);
+            };
+            const logicContext = {
+                ...requestContext,
+                sessionId: sessionId,
+                getWorkingDirectory: getWorkingDirectoryForSession,
+            };
+            logger.info(`Executing tool: ${TOOL_NAME}`, logicContext);
+            return await ErrorHandler.tryCatch(async () => {
+                // Call the core logic function
+                const diffResult = await diffGitChanges(validatedArgs, logicContext);
+                // Format the result (the diff string) as plain text within TextContent
+                const resultContent = {
+                    type: 'text',
+                    // Return the raw diff output directly
+                    text: diffResult.diff,
+                    // Indicate the content type is plain text diff
+                    contentType: 'text/plain; charset=utf-8', // Or 'text/x-diff'
+                };
+                logger.info(`Tool ${TOOL_NAME} executed successfully: ${diffResult.message}`, logicContext);
+                // Success is determined by the logic function
+                return { content: [resultContent] };
+            }, {
+                operation: toolOperation,
+                context: logicContext,
+                input: validatedArgs,
+                errorCode: BaseErrorCode.INTERNAL_ERROR, // Default if unexpected error in logic
+            });
+        });
+        logger.info(`Tool registered: ${TOOL_NAME}`, context);
+    }, { operation, context, critical: true });
+}
+;

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

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel file for the gitFetch tool.
+ */
+export { registerGitFetchTool, initializeGitFetchStateAccessors } from './registration.js';
+// Export types if needed elsewhere, e.g.:
+// export type { GitFetchInput, GitFetchResult } from './logic.js';