@cyanheads/git-mcp-server 1.2.4 → 2.0.2

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

@@ -0,0 +1,99 @@
+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 input schema for the git_show tool using Zod
+// No refinements needed here, so we don't need a separate BaseSchema
+export const GitShowInputSchema = 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."),
+    ref: z.string().min(1).describe("The object reference (commit hash, tag name, branch name, HEAD, etc.) to show."),
+    filePath: z.string().optional().describe("Optional specific file path within the ref to show (e.g., show a file's content at a specific commit). If provided, use the format '<ref>:<filePath>'."),
+    // format: z.string().optional().describe("Optional format string for the output"), // Consider adding later
+});
+/**
+ * Executes the 'git show' command for a given reference and optional file path.
+ *
+ * @param {GitShowInput} input - The validated input object.
+ * @param {RequestContext} context - The request context for logging and error handling.
+ * @returns {Promise<GitShowResult>} A promise that resolves with the structured result.
+ * @throws {McpError} Throws an McpError for path resolution/validation failures or unexpected errors.
+ */
+export async function gitShowLogic(input, context) {
+    const operation = 'gitShowLogic';
+    logger.debug(`Executing ${operation}`, { ...context, input });
+    let targetPath;
+    try {
+        // Resolve and sanitize the target path
+        const workingDir = context.getWorkingDirectory();
+        targetPath = (input.path && input.path !== '.')
+            ? input.path
+            : workingDir ?? '.';
+        if (targetPath === '.' && !workingDir) {
+            logger.warning("Executing git show 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);
+        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 });
+    }
+    // Validate ref format (simple validation)
+    if (!/^[a-zA-Z0-9_./~^:-]+$/.test(input.ref)) { // Allow ':' for filePath combination
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid reference format: ${input.ref}`, { context, operation });
+    }
+    // Validate filePath format if provided (basic path chars)
+    if (input.filePath && !/^[a-zA-Z0-9_./-]+$/.test(input.filePath)) {
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid file path format: ${input.filePath}`, { context, operation });
+    }
+    try {
+        // Construct the refspec, combining ref and filePath if needed
+        const refSpec = input.filePath ? `${input.ref}:"${input.filePath}"` : `"${input.ref}"`;
+        // Construct the command
+        const command = `git -C "${targetPath}" show ${refSpec}`;
+        logger.debug(`Executing command: ${command}`, { ...context, operation });
+        // Execute command. Note: git show might write to stderr for non-error info (like commit details before diff)
+        // We primarily care about stdout for the content. Errors usually have non-zero exit code.
+        const { stdout, stderr } = await execAsync(command);
+        if (stderr) {
+            // Log stderr as debug info, as it might contain commit details etc.
+            logger.debug(`Git show command produced stderr (may be informational)`, { ...context, operation, stderr });
+        }
+        logger.info(`${operation} executed successfully`, { ...context, operation, path: targetPath, refSpec });
+        return { success: true, content: stdout }; // Return raw stdout content
+    }
+    catch (error) {
+        const errorMessage = error.stderr || error.message || '';
+        logger.error(`Failed to execute git show command`, { ...context, operation, path: targetPath, error: errorMessage, stderr: error.stderr, stdout: error.stdout });
+        // Specific error handling
+        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 (/unknown revision or path not in the working tree/i.test(errorMessage)) {
+            const target = input.filePath ? `${input.ref}:${input.filePath}` : input.ref;
+            return { success: false, message: `Failed to show: Reference or pathspec '${target}' not found.`, error: errorMessage };
+        }
+        if (/ambiguous argument/i.test(errorMessage)) {
+            return { success: false, message: `Failed to show: Reference '${input.ref}' is ambiguous. Provide a more specific reference.`, error: errorMessage };
+        }
+        // Return structured failure for other git errors
+        return {
+            success: false,
+            message: `Git show failed for path: ${targetPath}, ref: ${input.ref}.`,
+            error: errorMessage
+        };
+    }
+}

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

@@ -0,0 +1,83 @@
+import { logger } from '../../../utils/logger.js';
+import { ErrorHandler } from '../../../utils/errorHandler.js';
+import { requestContextService } from '../../../utils/requestContext.js';
+// Import the schema and types
+import { gitShowLogic, GitShowInputSchema } from './logic.js';
+import { BaseErrorCode } from '../../../types-global/errors.js';
+let _getWorkingDirectory;
+let _getSessionId;
+/**
+ * Initializes the state accessors needed by the git_show 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 initializeGitShowStateAccessors(getWdFn, getSidFn) {
+    _getWorkingDirectory = getWdFn;
+    _getSessionId = getSidFn;
+    logger.info('State accessors initialized for git_show tool registration.');
+}
+const TOOL_NAME = 'git_show';
+const TOOL_DESCRIPTION = 'Shows information about Git objects (commits, tags, blobs, trees) based on a reference. Can optionally show the content of a specific file at that reference. Returns the raw output.';
+/**
+ * Registers the git_show 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 registerGitShowTool = async (server) => {
+    if (!_getWorkingDirectory || !_getSessionId) {
+        throw new Error('State accessors for git_show must be initialized before registration.');
+    }
+    const operation = 'registerGitShowTool';
+    const context = requestContextService.createRequestContext({ operation });
+    await ErrorHandler.tryCatch(async () => {
+        // Register the tool using the schema's shape (no refinements here)
+        server.tool(TOOL_NAME, TOOL_DESCRIPTION, GitShowInputSchema.shape, // Use the shape directly
+        // Let TypeScript infer handler argument types.
+        async (validatedArgs, callContext) => {
+            // Cast validatedArgs to the specific input type for use within the handler
+            const toolInput = validatedArgs;
+            const toolOperation = `tool:${TOOL_NAME}`;
+            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 returns a GitShowResult object
+                const showResult = await gitShowLogic(toolInput, logicContext);
+                // Format the result within TextContent
+                const resultContent = {
+                    type: 'text',
+                    // Return raw content on success, or error message on failure
+                    text: showResult.success ? showResult.content : `Error: ${showResult.message}${showResult.error ? `\nDetails: ${showResult.error}` : ''}`,
+                    // Use plain text content type, unless we decide to return JSON later
+                    contentType: 'text/plain',
+                };
+                // Log based on the success flag in the result
+                if (showResult.success) {
+                    logger.info(`Tool ${TOOL_NAME} executed successfully`, logicContext);
+                }
+                else {
+                    // Log specific failure message from the result
+                    logger.warning(`Tool ${TOOL_NAME} failed: ${showResult.message}`, { ...logicContext, errorDetails: showResult.error });
+                }
+                // Return the result, whether success or structured failure
+                return { content: [resultContent] };
+            }, {
+                operation: toolOperation,
+                context: logicContext,
+                input: validatedArgs, // Log the raw validated args
+                errorCode: BaseErrorCode.INTERNAL_ERROR, // Default if unexpected error occurs in logic/wrapper
+            });
+        });
+        logger.info(`Tool registered: ${TOOL_NAME}`, context);
+    }, { operation, context, critical: true }); // Mark registration as critical
+};

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

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

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

@@ -0,0 +1,161 @@
+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 for the git_stash tool using Zod
+export const GitStashBaseSchema = 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."),
+    mode: z.enum(['list', 'apply', 'pop', 'drop', 'save']).describe("The stash operation to perform: 'list', 'apply', 'pop', 'drop', 'save'."),
+    stashRef: z.string().optional().describe("Stash reference (e.g., 'stash@{1}'). Required for 'apply', 'pop', 'drop' modes."),
+    message: z.string().optional().describe("Optional descriptive message used only for 'save' mode."),
+    // includeUntracked: z.boolean().default(false).describe("Include untracked files in 'save' mode (-u)"), // Consider adding later
+    // keepIndex: z.boolean().default(false).describe("Keep staged changes in 'save' mode (--keep-index)"), // Consider adding later
+});
+// Apply refinements and export the FINAL schema for validation within the handler
+export const GitStashInputSchema = GitStashBaseSchema.refine(data => !(['apply', 'pop', 'drop'].includes(data.mode) && !data.stashRef), {
+    message: "A 'stashRef' (e.g., 'stash@{0}') is required for 'apply', 'pop', and 'drop' modes.",
+    path: ["stashRef"], // Point error to the stashRef field
+});
+/**
+ * Executes git stash commands based on the specified mode.
+ *
+ * @param {GitStashInput} input - The validated input object (validated against GitStashInputSchema).
+ * @param {RequestContext} context - The request context for logging and error handling.
+ * @returns {Promise<GitStashResult>} A promise that resolves with the structured result.
+ * @throws {McpError} Throws an McpError for path resolution/validation failures or unexpected errors.
+ */
+export async function gitStashLogic(input, context) {
+    const operation = `gitStashLogic:${input.mode}`;
+    logger.debug(`Executing ${operation}`, { ...context, input });
+    let targetPath;
+    try {
+        // Resolve and sanitize the target path
+        const workingDir = context.getWorkingDirectory();
+        targetPath = (input.path && input.path !== '.')
+            ? input.path
+            : workingDir ?? '.';
+        if (targetPath === '.' && !workingDir) {
+            logger.warning("Executing git stash 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);
+        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 });
+    }
+    // Validate stashRef format if provided (simple validation)
+    if (input.stashRef && !/^stash@\{[0-9]+\}$/.test(input.stashRef)) {
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid stash reference format: ${input.stashRef}. Expected format: stash@{n}`, { context, operation });
+    }
+    try {
+        let command;
+        let result;
+        switch (input.mode) {
+            case 'list':
+                command = `git -C "${targetPath}" stash list`;
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                const { stdout: listStdout } = await execAsync(command);
+                const stashes = listStdout.trim().split('\n')
+                    .filter(line => line)
+                    .map(line => {
+                    // Improved regex to handle different stash list formats
+                    const match = line.match(/^(stash@\{(\d+)\}):\s*(?:(?:WIP on|On)\s*([^:]+):\s*)?(.*)$/);
+                    return match
+                        ? { ref: match[1], branch: match[3] || 'unknown', description: match[4] }
+                        : { ref: 'unknown', branch: 'unknown', description: line }; // Fallback parsing
+                });
+                result = { success: true, mode: 'list', stashes };
+                break;
+            case 'apply':
+            case 'pop':
+                // stashRef is validated by Zod refine
+                const stashRefApplyPop = input.stashRef;
+                command = `git -C "${targetPath}" stash ${input.mode} ${stashRefApplyPop}`;
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                try {
+                    const { stdout, stderr } = await execAsync(command);
+                    // Check stdout/stderr for conflict messages, although exit code 0 usually means success
+                    const conflicts = /conflict/i.test(stdout) || /conflict/i.test(stderr);
+                    const message = conflicts
+                        ? `Stash ${input.mode} resulted in conflicts that need manual resolution.`
+                        : `Stash ${stashRefApplyPop} ${input.mode === 'apply' ? 'applied' : 'popped'} successfully.`;
+                    logger.info(message, { ...context, operation, path: targetPath, conflicts });
+                    result = { success: true, mode: input.mode, message, conflicts };
+                }
+                catch (applyError) {
+                    const applyErrorMessage = applyError.stderr || applyError.message || '';
+                    if (/conflict/i.test(applyErrorMessage)) {
+                        logger.warning(`Stash ${input.mode} failed due to conflicts.`, { ...context, operation, path: targetPath, error: applyErrorMessage });
+                        // Return failure but indicate conflicts
+                        return { success: false, mode: input.mode, message: `Failed to ${input.mode} stash ${stashRefApplyPop} due to conflicts. Resolve conflicts manually.`, error: applyErrorMessage, conflicts: true };
+                    }
+                    // Rethrow other errors
+                    throw applyError;
+                }
+                break;
+            case 'drop':
+                // stashRef is validated by Zod refine
+                const stashRefDrop = input.stashRef;
+                command = `git -C "${targetPath}" stash drop ${stashRefDrop}`;
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                await execAsync(command);
+                result = { success: true, mode: 'drop', message: `Dropped ${stashRefDrop} successfully.`, stashRef: stashRefDrop };
+                break;
+            case 'save':
+                command = `git -C "${targetPath}" stash save`;
+                if (input.message) {
+                    // Ensure message is properly quoted for the shell
+                    command += ` "${input.message.replace(/"/g, '\\"')}"`;
+                }
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                const { stdout: saveStdout } = await execAsync(command);
+                const stashCreated = !/no local changes to save/i.test(saveStdout);
+                const saveMessage = stashCreated
+                    ? `Changes stashed successfully.` + (input.message ? ` Message: "${input.message}"` : '')
+                    : "No local changes to save.";
+                result = { success: true, mode: 'save', message: saveMessage, stashCreated };
+                break;
+            default:
+                // Should not happen due to Zod validation
+                throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid mode: ${input.mode}`, { context, operation });
+        }
+        logger.info(`${operation} executed successfully`, { ...context, operation, path: targetPath });
+        return result;
+    }
+    catch (error) {
+        const errorMessage = error.stderr || error.message || '';
+        logger.error(`Failed to execute git stash command`, { ...context, operation, path: targetPath, error: errorMessage, stderr: error.stderr, stdout: error.stdout });
+        // Specific error handling
+        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 ((input.mode === 'apply' || input.mode === 'pop' || input.mode === 'drop') && /no such stash/i.test(errorMessage)) {
+            return { success: false, mode: input.mode, message: `Failed to ${input.mode} stash: Stash '${input.stashRef}' not found.`, error: errorMessage };
+        }
+        if ((input.mode === 'apply' || input.mode === 'pop') && /conflict/i.test(errorMessage)) {
+            // This case might be caught above, but double-check here
+            return { success: false, mode: input.mode, message: `Failed to ${input.mode} stash '${input.stashRef}' due to conflicts. Resolve conflicts manually.`, error: errorMessage, conflicts: true };
+        }
+        // Return structured failure for other git errors
+        return {
+            success: false,
+            mode: input.mode,
+            message: `Git stash ${input.mode} failed for path: ${targetPath}.`,
+            error: errorMessage
+        };
+    }
+}

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

@@ -0,0 +1,84 @@
+import { logger } from '../../../utils/logger.js';
+import { ErrorHandler } from '../../../utils/errorHandler.js';
+import { requestContextService } from '../../../utils/requestContext.js';
+// Import the final schema and types for handler logic
+// Import the BASE schema separately for registration shape
+import { gitStashLogic, GitStashBaseSchema } from './logic.js';
+import { BaseErrorCode } from '../../../types-global/errors.js';
+let _getWorkingDirectory;
+let _getSessionId;
+/**
+ * Initializes the state accessors needed by the git_stash 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 initializeGitStashStateAccessors(getWdFn, getSidFn) {
+    _getWorkingDirectory = getWdFn;
+    _getSessionId = getSidFn;
+    logger.info('State accessors initialized for git_stash tool registration.');
+}
+const TOOL_NAME = 'git_stash';
+const TOOL_DESCRIPTION = 'Manages stashed changes in the working directory. Supports listing stashes, applying/popping specific stashes (with conflict detection), dropping stashes, and saving current changes to a new stash with an optional message. Returns results as a JSON object.';
+/**
+ * Registers the git_stash 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 registerGitStashTool = async (server) => {
+    if (!_getWorkingDirectory || !_getSessionId) {
+        throw new Error('State accessors for git_stash must be initialized before registration.');
+    }
+    const operation = 'registerGitStashTool';
+    const context = requestContextService.createRequestContext({ operation });
+    await ErrorHandler.tryCatch(async () => {
+        // Register the tool using the *base* schema's shape for definition
+        server.tool(// Use BASE schema shape here
+        TOOL_NAME, TOOL_DESCRIPTION, GitStashBaseSchema.shape, // Use the shape from the BASE schema
+        // Let TypeScript infer handler argument types.
+        // The SDK validates against the full GitStashInputSchema before calling this.
+        async (validatedArgs, callContext) => {
+            // Cast validatedArgs to the specific input type for use within the handler
+            const toolInput = validatedArgs;
+            const toolOperation = `tool:${TOOL_NAME}:${toolInput.mode}`; // Include mode in operation
+            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} (mode: ${toolInput.mode})`, logicContext);
+            return await ErrorHandler.tryCatch(async () => {
+                // Call the core logic function which returns a GitStashResult object
+                const stashResult = await gitStashLogic(toolInput, logicContext);
+                // Format the result as a JSON string within TextContent
+                const resultContent = {
+                    type: 'text',
+                    text: JSON.stringify(stashResult, null, 2), // Pretty-print JSON
+                    contentType: 'application/json',
+                };
+                // Log based on the success flag in the result
+                if (stashResult.success) {
+                    logger.info(`Tool ${TOOL_NAME} (mode: ${toolInput.mode}) executed successfully, returning JSON`, logicContext);
+                }
+                else {
+                    // Log specific failure message from the result
+                    logger.warning(`Tool ${TOOL_NAME} (mode: ${toolInput.mode}) failed: ${stashResult.message}`, { ...logicContext, errorDetails: stashResult.error, conflicts: stashResult.conflicts });
+                }
+                // Return the result, whether success or structured failure
+                return { content: [resultContent] };
+            }, {
+                operation: toolOperation,
+                context: logicContext,
+                input: validatedArgs, // Log the raw validated args
+                errorCode: BaseErrorCode.INTERNAL_ERROR, // Default if unexpected error occurs in logic/wrapper
+            });
+        });
+        logger.info(`Tool registered: ${TOOL_NAME}`, context);
+    }, { operation, context, critical: true }); // Mark registration as critical
+};

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

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