ShadowGit MCP Server

Instructions

Implementation Reference

• src/handlers/checkpoint-handler.ts:33-203 (handler)

  Main handler logic for the 'checkpoint' tool. Validates input, checks for changes, stages all files with 'git add -A', creates a git commit with custom message and author, returns detailed success response with commit hash and change summary.
  async handle(args: unknown): Promise<MCPToolResponse> { if (!this.isValidArgs(args)) { return createErrorResponse( "Error: Both 'repo' and 'title' parameters are required.", `Example usage: checkpoint({ repo: "my-project", title: "Fix authentication bug", author: "Claude" }) Use list_repos() to see available repositories.` ); } // Validate title length if (args.title.length > 50) { return createErrorResponse( `Error: Title must be 50 characters or less (current: ${args.title.length} chars).` ); } // Validate message length if provided if (args.message && args.message.length > 1000) { return createErrorResponse( `Error: Message must be 1000 characters or less (current: ${args.message.length} chars).` ); } const repoPath = this.repositoryManager.resolveRepoPath(args.repo); if (!repoPath) { const repos = this.repositoryManager.getRepositories(); if (repos.length === 0) { return createErrorResponse( 'Error: No repositories found. Please add repositories to ShadowGit first.' ); } return createErrorResponse( `Error: Repository '${args.repo}' not found.`, `Available repositories: ${repos.map(r => ` - ${r.name}: ${r.path}`).join('\n')}` ); } // Check for changes const statusOutput = await this.gitExecutor.execute(['status', '--porcelain'], repoPath, true); if (!statusOutput || statusOutput.trim() === '' || statusOutput === '(empty output)') { return createErrorResponse( `❌ **No Changes Detected** ${'='.repeat(50)} 📁 Repository has no changes to commit. ⚠️ **Important:** Do NOT call end_session() - no commit was created. 💡 **NEXT STEP:** Make some changes first, then call checkpoint() again.` ); } // Build commit message const commitTitle = args.title; const commitBody = args.message || ''; const author = args.author || 'AI Assistant'; // Add all changes const addOutput = await this.gitExecutor.execute(['add', '-A'], repoPath, true); if (addOutput.startsWith('Error:')) { return createErrorResponse( `❌ **Failed to Stage Changes** ${'='.repeat(50)} 🚨 **Error:** ${addOutput} ⚠️ **Important:** Do NOT call end_session() - commit was not created. 💡 **NEXT STEP:** Check the error and try again.` ); } // Build full commit message let fullMessage = commitTitle; if (commitBody) { fullMessage += `\n\n${commitBody}`; } fullMessage += `\n\nAuthor: ${author} (via ShadowGit MCP)`; // Create commit with author information const commitEnv = { GIT_AUTHOR_NAME: author, GIT_AUTHOR_EMAIL: `${author.toLowerCase().replace(/\s+/g, '-')}@shadowgit.local`, GIT_COMMITTER_NAME: 'ShadowGit MCP', GIT_COMMITTER_EMAIL: 'shadowgit-mcp@shadowgit.local' }; // Use array-based command to avoid parsing issues const commitOutput = await this.gitExecutor.execute( ['commit', '-m', fullMessage], repoPath, true, commitEnv ); if (commitOutput.startsWith('Error:')) { return createErrorResponse( `❌ **Failed to Create Commit** ${'='.repeat(50)} 🚨 **Error:** ${commitOutput} ⚠️ **Important:** Do NOT call end_session() - commit was not created. 💡 **NEXT STEP:** Check the error message and try checkpoint() again.` ); } // Extract commit hash from output let commitHash: string | undefined; const hashMatch = commitOutput.match(/\[[\w\-]+ ([a-f0-9]+)\]/); if (hashMatch) { commitHash = hashMatch[1]; } // Get summary of changes const showOutput = await this.gitExecutor.execute(['show', '--stat', '--format=short', 'HEAD'], repoPath, true); return { content: [ { type: 'text', text: `✅ **Checkpoint Created Successfully!** ${'='.repeat(50)} 📦 **Commit Details:** ${commitOutput} 📊 **Changes Summary:** ${showOutput} 🔑 **Commit Hash:** \`${commitHash || 'unknown'}\` ${'='.repeat(50)} 📋 **Workflow Progress:** - [x] Session started - [x] Changes made - [x] Checkpoint created ✨ - [ ] Session ended 🚨 **REQUIRED NEXT STEP:** You MUST now call \`end_session()\` to resume auto-commits: \`\`\`javascript end_session({ sessionId: "your-session-id", commitHash: "${commitHash || 'unknown'}" }) \`\`\` ⚠️ **Important:** Only call end_session() because the commit was SUCCESSFUL.` } ], success: true }; }
• src/shadowgit-mcp-server.ts:115-140 (registration)

  Tool registration in ListToolsRequestSchema handler, defining name, description, and input schema for the 'checkpoint' tool.
  { name: 'checkpoint', description: 'Create a git commit with your changes. Call this AFTER completing your work but BEFORE end_session. Creates a clean commit for the user to review.', inputSchema: { type: 'object', properties: { repo: { type: 'string', description: 'Repository name', }, title: { type: 'string', description: 'Commit title (max 50 chars) - REQUIRED. Be specific about what was changed.', }, message: { type: 'string', description: 'Detailed commit message (optional, max 1000 chars)', }, author: { type: 'string', description: 'Author name (e.g., "Claude", "GPT-4"). Defaults to "AI Assistant"', }, }, required: ['repo', 'title'], }, },
• src/shadowgit-mcp-server.ts:179-181 (registration)

  Switch case in CallToolRequestSchema handler that routes 'checkpoint' calls to CheckpointHandler.handle().
  case 'checkpoint': return await this.checkpointHandler.handle(args);
• src/types.ts:15-20 (schema)

  TypeScript interface defining the expected arguments for the checkpoint tool, used for validation in the handler.
  export interface ManualCheckpointArgs { repo: string; title: string; message?: string; author?: string; }
• src/handlers/checkpoint-handler.ts:19-28 (helper)

  Helper method for validating checkpoint arguments against ManualCheckpointArgs type.
  private isValidArgs(args: unknown): args is ManualCheckpointArgs { return ( typeof args === 'object' && args !== null && 'repo' in args && 'title' in args && typeof (args as ManualCheckpointArgs).repo === 'string' && typeof (args as ManualCheckpointArgs).title === 'string' ); }