@cyanheads/git-mcp-server 2.0.11 → 2.0.14

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

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

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

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

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

@@ -0,0 +1,3 @@
+export { registerGitWrapupInstructionsTool } from './registration.js';
+// This tool does not require session-specific state accessors like getWorkingDirectory,
+// so no initialize...StateAccessors function is needed or exported here.

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

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+// Define the input schema
+export const GitWrapupInstructionsInputSchema = z.object({
+    acknowledgement: z.enum(['Y', 'y', 'Yes', 'yes'], {
+        required_error: 'Acknowledgement is required.',
+        description: 'Acknowledgement that you have permission (implicit allowed, explicit preferred) from the user to initiate this tool. Must be "Y" or "Yes" (case-insensitive).',
+    }),
+    updateAgentMetaFiles: z.enum(['Y', 'y', 'Yes', 'yes']).optional().describe("If set to 'Y' or 'Yes', include an extra instruction to review and update agent-specific meta files like .clinerules or claude.md if present. Only use this if the user explicitly requested it."),
+});
+// The predefined instructions string.
+const WRAPUP_INSTRUCTIONS = `Initiate our standard git wrapup workflow. (1) First, review all changes to our repo using the git_diff tool to understand the precise nature and rationale behind each change (what changed and why did it change?). (2) For substantial code updates, review and update the README to ensure it is up to date with our current codebase (make a note to the user of any discrepancies you noticed, gathered from everything you've seen of our codebase). (3) Then, update the CHANGELOG with concise, descriptive entries detailing all modifications, clearly indicating their purpose (e.g., bug fix, feature implementation, refactoring). (4) Finally, proceed to commit all changes; group these changes into logical, atomic commits, each accompanied by a clear and descriptive message adhering to Conventional Commits standards (e.g. "docs(readme): updated readme to include xyz."). Note the 'git_commit' tool allows you to also stage the files while commiting. Ensure commit messages accurately convey the scope and impact of the changes, incorporating specific metrics or identifiers where applicable. Be sure to set 'git_set_working_dir' if not already set.`;
+/**
+ * Core logic for the git_wrapup_instructions tool.
+ * This tool simply returns a predefined set of instructions, potentially augmented.
+ *
+ * @param {GitWrapupInstructionsInput} input - The validated input, may contain 'updateAgentMetaFiles'.
+ * @param {RequestContext} _context - The request context (included for consistency, not used in this simple logic).
+ * @returns {Promise<GitWrapupInstructionsResult>} A promise that resolves with the wrap-up instructions.
+ */
+export async function getWrapupInstructions(input, _context // Included for structural consistency, not used by this simple tool
+) {
+    let finalInstructions = WRAPUP_INSTRUCTIONS;
+    if (input.updateAgentMetaFiles && ['Y', 'y', 'Yes', 'yes'].includes(input.updateAgentMetaFiles)) {
+        finalInstructions += ` Extra request: review and update if needed the .clinerules and claude.md files if present.`;
+    }
+    return {
+        instructions: finalInstructions,
+    };
+}

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

@@ -0,0 +1,42 @@
+import { BaseErrorCode } from '../../../types-global/errors.js';
+import { ErrorHandler, logger, requestContextService } from '../../../utils/index.js';
+import { getWrapupInstructions, GitWrapupInstructionsInputSchema, } from './logic.js';
+const TOOL_NAME = 'git_wrapup_instructions';
+const TOOL_DESCRIPTION = 'Provides a standard Git wrap-up workflow. This involves reviewing changes with `git_diff`, updating documentation (README, CHANGELOG), and making logical, descriptive commits using the `git_commit` tool.';
+/**
+ * Registers the git_wrapup_instructions 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 registerGitWrapupInstructionsTool = async (server) => {
+    const operation = 'registerGitWrapupInstructionsTool';
+    const context = requestContextService.createRequestContext({ operation });
+    await ErrorHandler.tryCatch(async () => {
+        server.tool(TOOL_NAME, TOOL_DESCRIPTION, GitWrapupInstructionsInputSchema.shape, // Empty schema shape
+        async (validatedArgs, callContext) => {
+            const toolOperation = 'tool:git_wrapup_instructions';
+            // Pass callContext as parentContext for consistent context chaining
+            const requestContext = requestContextService.createRequestContext({ operation: toolOperation, parentContext: callContext });
+            logger.info(`Executing tool: ${TOOL_NAME}`, requestContext);
+            return await ErrorHandler.tryCatch(async () => {
+                const result = await getWrapupInstructions(validatedArgs, requestContext // Pass the created requestContext
+                );
+                const resultContent = {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                    contentType: 'application/json',
+                };
+                logger.info(`Tool ${TOOL_NAME} executed successfully, returning JSON`, requestContext);
+                return { content: [resultContent] };
+            }, {
+                operation: toolOperation,
+                context: requestContext,
+                input: validatedArgs,
+                errorCode: BaseErrorCode.INTERNAL_ERROR,
+            });
+        });
+        logger.info(`Tool registered: ${TOOL_NAME}`, context);
+    }, { operation, context, critical: true });
+};