@cyanheads/git-mcp-server 1.2.4 → 2.0.2

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

@@ -0,0 +1,215 @@
+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_status tool using Zod
+export const GitStatusInputSchema = z.object({
+    path: z.string().min(1).optional().default('.').describe("Path to the Git repository (defaults to '.' which uses the session's working directory if set)"),
+});
+/**
+ * Parses the output of 'git status --porcelain=v1 -b'.
+ * See: https://git-scm.com/docs/git-status#_porcelain_format_version_1
+ *
+ * @param {string} porcelainOutput - The raw output from the git command.
+ * @returns {GitStatusResult} - Structured status information.
+ */
+function parseGitStatusPorcelainV1(porcelainOutput) {
+    const lines = porcelainOutput.trim().split('\n');
+    const result = {
+        currentBranch: null,
+        staged: [],
+        modified: [],
+        untracked: [],
+        conflicted: [],
+        isClean: true, // Assume clean initially
+    };
+    if (lines.length === 0 || (lines.length === 1 && lines[0] === '')) {
+        // If output is empty, it might mean no branch yet or truly clean
+        // We'll refine branch detection below if possible
+        return result;
+    }
+    // First line often contains branch info (e.g., ## master...origin/master)
+    if (lines[0].startsWith('## ')) {
+        const branchLine = lines.shift(); // Remove and process the branch line
+        // Try matching standard branch format first (e.g., ## master...origin/master [ahead 1])
+        // Make regex more specific: look for '...' or '[' after branch name, or end of line for simple branch name
+        const standardBranchMatch = branchLine.match(/^## ([^ ]+?)(?:\.\.\.| \[.*\]|$)/);
+        // Try matching the 'No commits yet' format (e.g., ## No commits yet on master)
+        const noCommitsMatch = branchLine.match(/^## No commits yet on (.+)/);
+        // Try matching detached HEAD format (e.g., ## HEAD (no branch))
+        const detachedMatch = branchLine.match(/^## HEAD \(no branch\)/);
+        if (standardBranchMatch) {
+            result.currentBranch = standardBranchMatch[1];
+            // TODO: Optionally parse ahead/behind counts if needed from the full match
+        }
+        else if (noCommitsMatch) {
+            // More descriptive state: Branch exists but has no commits
+            result.currentBranch = `${noCommitsMatch[1]} (no commits yet)`;
+        }
+        else if (detachedMatch) { // Handle detached HEAD
+            result.currentBranch = 'HEAD (detached)';
+        }
+        else {
+            // Fallback if branch line format is unexpected
+            logger.warning('Could not parse branch information from line:', { branchLine });
+            result.currentBranch = '(unknown)';
+        }
+    }
+    for (const line of lines) {
+        if (!line)
+            continue; // Skip empty lines if any
+        result.isClean = false; // Any line indicates non-clean state
+        const xy = line.substring(0, 2);
+        const file = line.substring(3); // Path starts after 'XY '
+        const stagedStatus = xy[0];
+        const unstagedStatus = xy[1];
+        // Handle untracked files
+        if (xy === '??') {
+            result.untracked.push(file);
+            continue;
+        }
+        // Handle conflicted files (complex statuses)
+        if (stagedStatus === 'U' || unstagedStatus === 'U' || (stagedStatus === 'A' && unstagedStatus === 'A') || (stagedStatus === 'D' && unstagedStatus === 'D')) {
+            result.conflicted.push(file);
+            // Decide how to represent conflicts (could be more granular)
+            if (!result.staged.some(f => f.file === file))
+                result.staged.push({ status: 'Conflicted', file });
+            if (!result.modified.some(f => f.file === file))
+                result.modified.push({ status: 'Conflicted', file });
+            continue;
+        }
+        // Handle staged changes (index status)
+        if (stagedStatus !== ' ' && stagedStatus !== '?') {
+            let statusDesc = 'Unknown Staged';
+            switch (stagedStatus) {
+                case 'M':
+                    statusDesc = 'Modified';
+                    break;
+                case 'A':
+                    statusDesc = 'Added';
+                    break;
+                case 'D':
+                    statusDesc = 'Deleted';
+                    break;
+                case 'R':
+                    statusDesc = 'Renamed';
+                    break; // Often includes ' -> new_name' in file path
+                case 'C':
+                    statusDesc = 'Copied';
+                    break; // Often includes ' -> new_name' in file path
+                case 'T':
+                    statusDesc = 'Type Changed';
+                    break;
+            }
+            result.staged.push({ status: statusDesc, file });
+        }
+        // Handle unstaged changes (worktree status)
+        if (unstagedStatus !== ' ' && unstagedStatus !== '?') {
+            let statusDesc = 'Unknown Unstaged';
+            switch (unstagedStatus) {
+                case 'M':
+                    statusDesc = 'Modified';
+                    break;
+                case 'D':
+                    statusDesc = 'Deleted';
+                    break;
+                case 'T':
+                    statusDesc = 'Type Changed';
+                    break;
+                // Note: 'A' (Added) in unstaged usually means untracked ('??') handled above
+            }
+            // Avoid duplicating if already marked as conflicted
+            if (!result.modified.some(f => f.file === file && f.status === 'Conflicted')) {
+                result.modified.push({ status: statusDesc, file });
+            }
+        }
+    }
+    // Final check for cleanliness
+    result.isClean = result.staged.length === 0 && result.modified.length === 0 && result.untracked.length === 0 && result.conflicted.length === 0;
+    return result;
+}
+/**
+ * Executes the 'git status --porcelain=v1 -b' command and returns structured JSON output.
+ *
+ * @param {GitStatusInput} input - The validated input object containing the repository path.
+ * @param {RequestContext} context - The request context for logging and error handling.
+ * @returns {Promise<GitStatusResult>} A promise that resolves with the structured git status.
+ * @throws {McpError} Throws an McpError if path resolution or validation fails, or if the git command fails.
+ */
+export async function getGitStatus(input, context // Add getter to context
+) {
+    const operation = 'getGitStatus';
+    logger.debug(`Executing ${operation}`, { ...context, input });
+    let targetPath;
+    try {
+        // Resolve the target path
+        if (input.path && input.path !== '.') {
+            // Use the provided path directly
+            targetPath = input.path;
+            logger.debug(`Using provided path: ${targetPath}`, { ...context, operation });
+        }
+        else {
+            // Path is '.' or undefined, try to get the session's working directory
+            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 {
+        // Using --porcelain=v1 for stable, scriptable output and -b for branch info
+        // Ensure the path passed to -C is correctly quoted for the shell
+        const command = `git -C "${targetPath}" status --porcelain=v1 -b`;
+        logger.debug(`Executing command: ${command}`, { ...context, operation });
+        const { stdout, stderr } = await execAsync(command);
+        if (stderr) {
+            // Log stderr as warning but proceed to parse stdout
+            logger.warning(`Git status command produced stderr (may be informational)`, { ...context, operation, stderr });
+        }
+        logger.info(`${operation} command executed, parsing output...`, { ...context, operation, path: targetPath });
+        // Parse the porcelain output
+        const structuredResult = parseGitStatusPorcelainV1(stdout);
+        // If parsing resulted in clean state but no branch, re-check branch explicitly
+        // This handles the case of an empty repo after init but before first commit
+        if (structuredResult.isClean && !structuredResult.currentBranch) {
+            try {
+                const branchCommand = `git -C "${targetPath}" rev-parse --abbrev-ref HEAD`;
+                const { stdout: branchStdout } = await execAsync(branchCommand);
+                const currentBranch = branchStdout.trim();
+                if (currentBranch && currentBranch !== 'HEAD') {
+                    structuredResult.currentBranch = currentBranch;
+                }
+            }
+            catch (branchError) {
+                // Ignore error if rev-parse fails (e.g., still no commits)
+                logger.debug('Could not determine branch via rev-parse, likely no commits yet.', { ...context, operation, branchError });
+            }
+        }
+        logger.info(`${operation} parsed successfully`, { ...context, operation, path: targetPath });
+        return structuredResult; // Return the structured JSON object
+    }
+    catch (error) {
+        logger.error(`Failed to execute or parse git status command`, { ...context, operation, path: targetPath, error: error.message, stderr: error.stderr });
+        const errorMessage = error.stderr || error.message || '';
+        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 });
+        }
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, `Failed to get git status for path: ${targetPath}. Error: ${errorMessage}`, { context, operation, originalError: error });
+    }
+}

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

@@ -0,0 +1,77 @@
+import { logger } from '../../../utils/logger.js';
+import { ErrorHandler } from '../../../utils/errorHandler.js';
+import { requestContextService } from '../../../utils/requestContext.js';
+// Import the result type along with the function and input schema
+import { getGitStatus, GitStatusInputSchema } from './logic.js';
+import { BaseErrorCode } from '../../../types-global/errors.js'; // Import BaseErrorCode
+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 initializeGitStatusStateAccessors(getWdFn, getSidFn) {
+    _getWorkingDirectory = getWdFn;
+    _getSessionId = getSidFn;
+    logger.info('State accessors initialized for git_status tool registration.');
+}
+const TOOL_NAME = 'git_status';
+const TOOL_DESCRIPTION = 'Retrieves the status of a Git repository. Shows the working tree status including tracked/untracked files, modifications, staged changes, and current branch information. Returns the status as a JSON object.';
+/**
+ * Registers the git_status 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 registerGitStatusTool = async (server) => {
+    if (!_getWorkingDirectory || !_getSessionId) {
+        throw new Error('State accessors for git_status must be initialized before registration.');
+    }
+    const operation = 'registerGitStatusTool';
+    const context = requestContextService.createRequestContext({ operation });
+    await ErrorHandler.tryCatch(async () => {
+        server.tool(TOOL_NAME, TOOL_DESCRIPTION, GitStatusInputSchema.shape, // Provide the Zod schema shape
+        async (validatedArgs, callContext) => {
+            const toolOperation = 'tool:git_status';
+            // Create context, potentially inheriting from callContext
+            const requestContext = requestContextService.createRequestContext({ operation: toolOperation, parentContext: callContext });
+            // Get session ID
+            const sessionId = _getSessionId(requestContext);
+            // Define the session-specific getter function
+            const getWorkingDirectoryForSession = () => {
+                return _getWorkingDirectory(sessionId);
+            };
+            // Enhance context for the logic function
+            const logicContext = {
+                ...requestContext,
+                sessionId: sessionId,
+                getWorkingDirectory: getWorkingDirectoryForSession,
+            };
+            logger.info(`Executing tool: ${TOOL_NAME}`, logicContext);
+            // Use ErrorHandler.tryCatch to wrap the logic execution
+            return await ErrorHandler.tryCatch(async () => {
+                // Call the core logic function with validated args and enhanced context
+                const statusResult = await getGitStatus(validatedArgs, logicContext);
+                // Format the successful result as a JSON string within TextContent
+                const resultContent = {
+                    type: 'text',
+                    // Stringify the JSON object for the response content
+                    text: JSON.stringify(statusResult, null, 2), // Pretty-print JSON
+                    contentType: 'application/json', // Specify content type
+                };
+                logger.info(`Tool ${TOOL_NAME} executed successfully, returning JSON`, logicContext);
+                return { content: [resultContent] }; // isError defaults to false
+            }, {
+                operation: toolOperation,
+                context: logicContext,
+                input: validatedArgs, // Log sanitized input
+                errorCode: BaseErrorCode.INTERNAL_ERROR, // Default error code if logic fails unexpectedly
+            });
+        });
+        logger.info(`Tool registered: ${TOOL_NAME}`, context);
+    }, { operation, context, critical: true }); // Treat registration failure as critical
+};

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

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

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

@@ -0,0 +1,142 @@
+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 base input schema for the git_tag tool using Zod
+// We export this separately to access its .shape for registration
+export const GitTagBaseSchema = 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', 'create', 'delete']).describe("The tag operation to perform: 'list' (show all tags), 'create' (add a new tag), 'delete' (remove a local tag)."),
+    tagName: z.string().min(1).optional().describe("The name for the tag. Required for 'create' and 'delete' modes. e.g., 'v2.3.0'."),
+    message: z.string().optional().describe("The annotation message for the tag. Required and used only when 'mode' is 'create' and 'annotate' is true."),
+    commitRef: z.string().optional().describe("The commit hash, branch name, or other reference to tag. Used only in 'create' mode. Defaults to the current HEAD if omitted."),
+    annotate: z.boolean().default(false).describe("If true, creates an annotated tag (-a flag) instead of a lightweight tag. Requires 'message' to be provided. Used only in 'create' mode."),
+    // force: z.boolean().default(false).describe("Force tag creation/update (-f flag). Use with caution as it can overwrite existing tags."), // Consider adding later
+});
+// Apply refinements for conditional validation and export the final schema
+export const GitTagInputSchema = GitTagBaseSchema.refine(data => !(data.mode === 'create' && data.annotate && !data.message), {
+    message: "An annotation 'message' is required when creating an annotated tag (annotate=true).",
+    path: ["message"], // Point Zod error to the message field
+}).refine(data => !(data.mode === 'create' && !data.tagName), {
+    message: "A 'tagName' is required for 'create' mode.",
+    path: ["tagName"], // Point Zod error to the tagName field
+}).refine(data => !(data.mode === 'delete' && !data.tagName), {
+    message: "A 'tagName' is required for 'delete' mode.",
+    path: ["tagName"], // Point Zod error to the tagName field
+});
+/**
+ * Executes git tag commands based on the specified mode.
+ *
+ * @param {GitTagInput} input - The validated input object.
+ * @param {RequestContext} context - The request context for logging and error handling.
+ * @returns {Promise<GitTagResult>} A promise that resolves with the structured result.
+ * @throws {McpError} Throws an McpError for path resolution/validation failures or unexpected errors.
+ */
+export async function gitTagLogic(input, context) {
+    const operation = `gitTagLogic:${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 tag 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 tag name format (simple validation)
+    if (input.tagName && !/^[a-zA-Z0-9_./-]+$/.test(input.tagName)) {
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid tag name format: ${input.tagName}`, { context, operation });
+    }
+    // Validate commit ref format (simple validation - allows hashes, HEAD, branches, etc.)
+    if (input.commitRef && !/^[a-zA-Z0-9_./~^-]+$/.test(input.commitRef)) {
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid commit reference format: ${input.commitRef}`, { context, operation });
+    }
+    try {
+        let command;
+        let result;
+        switch (input.mode) {
+            case 'list':
+                command = `git -C "${targetPath}" tag --list`;
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                const { stdout: listStdout } = await execAsync(command);
+                const tags = listStdout.trim().split('\n').filter(tag => tag); // Filter out empty lines
+                result = { success: true, mode: 'list', tags };
+                break;
+            case 'create':
+                // TagName is validated by Zod refine
+                const tagNameCreate = input.tagName;
+                command = `git -C "${targetPath}" tag`;
+                if (input.annotate) {
+                    // Message is validated by Zod refine
+                    command += ` -a -m "${input.message.replace(/"/g, '\\"')}"`;
+                }
+                command += ` "${tagNameCreate}"`;
+                if (input.commitRef) {
+                    command += ` "${input.commitRef}"`;
+                }
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                await execAsync(command);
+                result = { success: true, mode: 'create', message: `Tag '${tagNameCreate}' created successfully.`, tagName: tagNameCreate };
+                break;
+            case 'delete':
+                // TagName is validated by Zod refine
+                const tagNameDelete = input.tagName;
+                command = `git -C "${targetPath}" tag -d "${tagNameDelete}"`;
+                logger.debug(`Executing command: ${command}`, { ...context, operation });
+                await execAsync(command);
+                result = { success: true, mode: 'delete', message: `Tag '${tagNameDelete}' deleted successfully.`, tagName: tagNameDelete };
+                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 tag 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 === 'create' && errorMessage.toLowerCase().includes('already exists')) {
+            return { success: false, mode: 'create', message: `Failed to create tag: Tag '${input.tagName}' already exists.`, error: errorMessage };
+        }
+        if (input.mode === 'delete' && errorMessage.toLowerCase().includes('not found')) {
+            return { success: false, mode: 'delete', message: `Failed to delete tag: Tag '${input.tagName}' not found.`, error: errorMessage };
+        }
+        if (input.mode === 'create' && input.commitRef && errorMessage.toLowerCase().includes('unknown revision or path not in the working tree')) {
+            return { success: false, mode: 'create', message: `Failed to create tag: Commit reference '${input.commitRef}' not found.`, error: errorMessage };
+        }
+        // Return structured failure for other git errors
+        return {
+            success: false,
+            mode: input.mode,
+            message: `Git tag ${input.mode} failed for path: ${targetPath}.`,
+            error: errorMessage
+        };
+    }
+}

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

@@ -0,0 +1,84 @@
+import { ErrorHandler } from '../../../utils/errorHandler.js';
+import { logger } from '../../../utils/logger.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 { BaseErrorCode } from '../../../types-global/errors.js';
+import { GitTagBaseSchema, gitTagLogic } from './logic.js';
+let _getWorkingDirectory;
+let _getSessionId;
+/**
+ * Initializes the state accessors needed by the git_tag 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 initializeGitTagStateAccessors(getWdFn, getSidFn) {
+    _getWorkingDirectory = getWdFn;
+    _getSessionId = getSidFn;
+    logger.info('State accessors initialized for git_tag tool registration.');
+}
+const TOOL_NAME = 'git_tag';
+const TOOL_DESCRIPTION = 'Manages Git tags. Supports listing existing tags, creating new lightweight or annotated tags against specific commits, and deleting local tags. Returns results as a JSON object.';
+/**
+ * Registers the git_tag 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 registerGitTagTool = async (server) => {
+    if (!_getWorkingDirectory || !_getSessionId) {
+        throw new Error('State accessors for git_tag must be initialized before registration.');
+    }
+    const operation = 'registerGitTagTool';
+    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, GitTagBaseSchema.shape, // Use the shape from the BASE schema
+        // Let TypeScript infer handler argument types.
+        // The SDK validates against the full GitTagInputSchema 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 GitTagResult object
+                const tagResult = await gitTagLogic(toolInput, logicContext);
+                // Format the result as a JSON string within TextContent
+                const resultContent = {
+                    type: 'text',
+                    text: JSON.stringify(tagResult, null, 2), // Pretty-print JSON
+                    contentType: 'application/json',
+                };
+                // Log based on the success flag in the result
+                if (tagResult.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: ${tagResult.message}`, { ...logicContext, errorDetails: tagResult.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/types-global/errors.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+/**
+ * Defines a set of standardized error codes for common issues within MCP servers or tools.
+ * These codes help clients understand the nature of an error programmatically.
+ */
+export var BaseErrorCode;
+(function (BaseErrorCode) {
+    /** Access denied due to invalid credentials or lack of authentication. */
+    BaseErrorCode["UNAUTHORIZED"] = "UNAUTHORIZED";
+    /** Access denied despite valid authentication, due to insufficient permissions. */
+    BaseErrorCode["FORBIDDEN"] = "FORBIDDEN";
+    /** The requested resource or entity could not be found. */
+    BaseErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    /** The request could not be completed due to a conflict with the current state of the resource. */
+    BaseErrorCode["CONFLICT"] = "CONFLICT";
+    /** The request failed due to invalid input parameters or data. */
+    BaseErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    /** The request was rejected because the client has exceeded rate limits. */
+    BaseErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
+    /** The request timed out before a response could be generated. */
+    BaseErrorCode["TIMEOUT"] = "TIMEOUT";
+    /** The service is temporarily unavailable, possibly due to maintenance or overload. */
+    BaseErrorCode["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
+    /** An unexpected error occurred on the server side. */
+    BaseErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+    /** An error occurred, but the specific cause is unknown or cannot be categorized. */
+    BaseErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+    /** An error occurred during the loading or validation of configuration data. */
+    BaseErrorCode["CONFIGURATION_ERROR"] = "CONFIGURATION_ERROR";
+    /** An error occurred related to network connectivity (e.g., DNS resolution, connection refused). */
+    BaseErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+})(BaseErrorCode || (BaseErrorCode = {}));
+/**
+ * Custom error class for MCP-specific errors.
+ * Encapsulates a `BaseErrorCode`, a descriptive message, and optional details.
+ * Provides a method to format the error into a standard MCP tool response.
+ */
+export class McpError extends Error {
+    code;
+    details;
+    /**
+     * Creates an instance of McpError.
+     * @param {BaseErrorCode} code - The standardized error code.
+     * @param {string} message - A human-readable description of the error.
+     * @param {Record<string, unknown>} [details] - Optional additional details about the error.
+     */
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        // Set the error name for identification
+        this.name = 'McpError';
+        // Ensure the prototype chain is correct
+        Object.setPrototypeOf(this, McpError.prototype);
+    }
+}
+/**
+ * Zod schema for validating error objects, potentially used for parsing
+ * error responses or validating error structures internally.
+ */
+export const ErrorSchema = z.object({
+    /** The error code, corresponding to BaseErrorCode enum values. */
+    code: z.nativeEnum(BaseErrorCode).describe("Standardized error code"),
+    /** A human-readable description of the error. */
+    message: z.string().describe("Detailed error message"),
+    /** Optional additional details or context about the error. */
+    details: z.record(z.unknown()).optional().describe("Optional structured error details")
+}).describe("Schema for validating structured error objects.");

package/dist/types-global/mcp.js

@@ -0,0 +1,59 @@
+// Type definitions for the MCP (Message Control Protocol) protocol
+// and standard JSON-RPC 2.0 structures
+// Standard JSON-RPC 2.0 Error Codes
+export var JsonRpcErrorCode;
+(function (JsonRpcErrorCode) {
+    JsonRpcErrorCode[JsonRpcErrorCode["PARSE_ERROR"] = -32700] = "PARSE_ERROR";
+    JsonRpcErrorCode[JsonRpcErrorCode["INVALID_REQUEST"] = -32600] = "INVALID_REQUEST";
+    JsonRpcErrorCode[JsonRpcErrorCode["METHOD_NOT_FOUND"] = -32601] = "METHOD_NOT_FOUND";
+    JsonRpcErrorCode[JsonRpcErrorCode["INVALID_PARAMS"] = -32602] = "INVALID_PARAMS";
+    JsonRpcErrorCode[JsonRpcErrorCode["INTERNAL_ERROR"] = -32603] = "INTERNAL_ERROR";
+    // -32000 to -32099 are reserved for implementation-defined server-errors.
+    JsonRpcErrorCode[JsonRpcErrorCode["SERVER_ERROR_START"] = -32000] = "SERVER_ERROR_START";
+    JsonRpcErrorCode[JsonRpcErrorCode["SERVER_ERROR_END"] = -32099] = "SERVER_ERROR_END";
+})(JsonRpcErrorCode || (JsonRpcErrorCode = {}));
+// ==================================
+// Helper Functions (Updated for JSON-RPC context)
+// ==================================
+/**
+ * Creates a JSON-RPC 2.0 Success Response containing an McpToolResult.
+ */
+export const createJsonRpcToolSuccessResponse = (id, text) => ({
+    jsonrpc: "2.0",
+    result: {
+        content: [{ type: "text", text }]
+    },
+    id
+});
+/**
+ * Creates a JSON-RPC 2.0 Error Response.
+ */
+export const createJsonRpcErrorResponse = (id, code, message, data) => ({
+    jsonrpc: "2.0",
+    error: {
+        code,
+        message,
+        ...(data !== undefined && { data }) // Include data only if provided
+    },
+    id
+});
+/**
+ * Creates a JSON-RPC 2.0 Success Response containing an McpResourceResult.
+ */
+export const createJsonRpcResourceSuccessResponse = (id, uri, text, mimeType) => ({
+    jsonrpc: "2.0",
+    result: {
+        contents: [{ uri, text, mimeType }]
+    },
+    id
+});
+// Note: PromptResponse helper might need adjustment depending on how prompts fit into JSON-RPC
+export const createPromptResponse = (text, role = "assistant") => ({
+    messages: [{
+            role,
+            content: {
+                type: "text",
+                text
+            }
+        }]
+});

package/dist/types-global/tool.js

@@ -0,0 +1 @@
+export {};