ShadowGit MCP Server

Instructions

Implementation Reference

• src/handlers/git-handler.ts:10-80 (handler)

  The GitHandler class provides the core implementation of the git_command tool. It validates input arguments, resolves repository paths, executes git commands via GitExecutor, and formats responses including workflow reminders for certain commands.
  export class GitHandler { constructor( private repositoryManager: RepositoryManager, private gitExecutor: GitExecutor ) {} /** * Validate git command arguments */ private isGitCommandArgs(args: unknown): args is GitCommandArgs { return ( typeof args === 'object' && args !== null && 'repo' in args && 'command' in args && typeof (args as GitCommandArgs).repo === 'string' && typeof (args as GitCommandArgs).command === 'string' ); } /** * Handle git_command tool execution */ async handle(args: unknown): Promise<MCPToolResponse> { if (!this.isGitCommandArgs(args)) { return createErrorResponse( "Error: Both 'repo' and 'command' parameters are required.", `Example usage: git_command({repo: "my-project", command: "log --oneline -10"}) git_command({repo: "my-project", command: "diff HEAD~1"}) Use list_repos() to see available repositories.` ); } const repoPath = this.repositoryManager.resolveRepoPath(args.repo); if (!repoPath) { const repos = this.repositoryManager.getRepositories(); return createRepoNotFoundResponse(args.repo, repos); } const output = await this.gitExecutor.execute(args.command, repoPath); // Add workflow reminder for common commands that suggest changes are being planned // Show workflow hints unless disabled const showHints = process.env.SHADOWGIT_HINTS !== '0'; const reminderCommands = ['diff', 'status', 'log', 'blame']; const needsReminder = showHints && reminderCommands.some(cmd => args.command.toLowerCase().includes(cmd)); if (needsReminder) { return createTextResponse( `${output} ${'='.repeat(50)} 📝 **Planning to Make Changes?** ${'='.repeat(50)} **Required Workflow:** 1️⃣ \`start_session({repo: "${args.repo}", description: "your task"})\` 2️⃣ Make your changes 3️⃣ \`checkpoint({repo: "${args.repo}", title: "commit message"})\` 4️⃣ \`end_session({sessionId: "...", commitHash: "..."})\` 💡 **NEXT STEP:** Call \`start_session()\` before editing any files!` ); } return createTextResponse(output); } }
• src/shadowgit-mcp-server.ts:80-96 (registration)

  Registration of the git_command tool in the MCP server's listTools handler, including name, description, and input schema definition.
  name: 'git_command', description: 'Execute a read-only git command on a ShadowGit repository. Only safe, read-only commands are allowed.', inputSchema: { type: 'object', properties: { repo: { type: 'string', description: 'Repository name (use list_repos to see available repositories)', }, command: { type: 'string', description: 'Git command to execute (e.g., "log -10", "diff HEAD~1", "status")', }, }, required: ['repo', 'command'], }, },
• src/shadowgit-mcp-server.ts:174-175 (registration)

  Dispatch to GitHandler in the MCP server's callTool request handler for git_command execution.
  return await this.gitHandler.handle(args);
• src/types.ts:10-13 (schema)

  TypeScript interface defining the input arguments for the git_command tool.
  export interface GitCommandArgs { repo: string; command: string; }
• src/core/git-executor.ts:23-154 (helper)

  GitExecutor class provides secure git command execution used by the git_command handler, with safety checks, whitelisting, and sandboxing.
  async execute( command: string | string[], repoPath: string, isInternal = false, additionalEnv?: NodeJS.ProcessEnv ): Promise<string> { // Parse command into arguments let args: string[]; if (Array.isArray(command)) { // Array-based command (safer for internal use) args = command; } else { // String command - check length only for external calls if (!isInternal && command.length > MAX_COMMAND_LENGTH) { return `Error: Command too long (max ${MAX_COMMAND_LENGTH} characters).`; } // Remove control characters const sanitizedCommand = command.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, ''); // Simple argument parsing that handles quotes and all whitespace args = []; let current = ''; let inQuotes = false; let quoteChar = ''; for (let i = 0; i < sanitizedCommand.length; i++) { const char = sanitizedCommand[i]; const nextChar = sanitizedCommand[i + 1]; if (!inQuotes && (char === '"' || char === "'")) { inQuotes = true; quoteChar = char; } else if (inQuotes && char === '\\' && nextChar === quoteChar) { // Handle escaped quote current += quoteChar; i++; // Skip the quote } else if (inQuotes && char === quoteChar) { inQuotes = false; quoteChar = ''; } else if (!inQuotes && /\s/.test(char)) { // Split on any whitespace (space, tab, etc.) if (current) { args.push(current); current = ''; } } else { current += char; } } if (current) { args.push(current); } } if (args.length === 0) { return 'Error: No command provided.'; } const gitCommand = args[0]; // Safety check 1: ALWAYS block dangerous arguments for (const arg of args) { if (isDangerousArg(arg)) { return 'Error: Command contains potentially dangerous arguments.'; } } // Safety check 2: Only check command whitelist for external calls if (!isInternal && !SAFE_COMMANDS.has(gitCommand)) { return `Error: Command '${gitCommand}' is not allowed. Only read-only commands are permitted. Allowed commands: ${Array.from(SAFE_COMMANDS).join(', ')}`; } // Safety check 3: Ensure we're operating on a .shadowgit.git repository const gitDir = path.join(repoPath, SHADOWGIT_DIR); if (!fs.existsSync(gitDir)) { return `Error: Not a ShadowGit repository. The .shadowgit.git directory was not found at ${gitDir}`; } log('debug', `Executing git ${gitCommand} in ${repoPath}`); try { const output = execFileSync('git', [ `--git-dir=${gitDir}`, `--work-tree=${repoPath}`, ...args ], { cwd: repoPath, encoding: 'utf-8', timeout: TIMEOUT_MS, maxBuffer: MAX_BUFFER_SIZE, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', // Disable interactive prompts GIT_SSH_COMMAND: 'ssh -o BatchMode=yes', // Disable SSH prompts GIT_PAGER: 'cat', // Disable pager PAGER: 'cat', // Fallback pager disable ...additionalEnv } }); return output || '(empty output)'; } catch (error: unknown) { if (error && typeof error === 'object') { const execError = error as any; // Check for timeout if (execError.code === 'ETIMEDOUT' || execError.signal === 'SIGTERM') { return `Error: Command timed out after ${TIMEOUT_MS}ms.`; } // Check for detailed error info (has stderr/stdout or status code) if ('stderr' in execError || 'stdout' in execError || 'status' in execError) { const stderr = execError.stderr?.toString() || ''; const stdout = execError.stdout?.toString() || ''; const message = execError.message || 'Unknown error'; return `Error executing git command: ${message} ${stderr ? `\nError output:\n${stderr}` : ''} ${stdout ? `\nPartial output:\n${stdout}` : ''}`; } } return `Error: ${error}`; } } }