git_status_explained

Instructions

Implementation Reference

• src/index.js:35-77 (handler)

  The main execution handler for the git_status_explained tool. It runs `git status --porcelain -b`, parses the branch and file status lines, maps status codes to explanations, formats an output string, and returns it as MCP content.

  async () => {
    const result = await runCommand("git status --porcelain -b");
    if (!result.success) {
      return { content: [{ type: "text", text: `Error: ${result.error}\n\nAre you in a git repository? Try: git init` }] };
    }
  
    const lines = result.stdout.split("\n").filter(Boolean);
    if (lines.length === 0) {
      return { content: [{ type: "text", text: "Not a git repository or empty output" }] };
    }
  
    const branchLine = lines[0];
    const fileLines = lines.slice(1);
  
    const meanings = {
      "??": "Untracked - New file, not yet tracked by git. Use 'git add <file>' to track it.",
      " M": "Modified - Changed but not staged. Use 'git add <file>' to stage it.",
      "M ": "Staged - Ready to be committed. Use 'git commit -m \"message\"' to commit.",
      "MM": "Modified & Staged - File was staged, then modified again.",
      "A ": "Added - New file, staged and ready to commit.",
      "D ": "Deleted - File was deleted. Stage with 'git add <file>'.",
      " D": "Deleted (unstaged) - File deleted but not staged.",
      "R ": "Renamed - File was renamed.",
      "C ": "Copied - File was copied.",
      "UU": "Conflict - Merge conflict! Edit the file to resolve.",
    };
  
    let output = `Branch: ${branchLine.replace("## ", "")}\n\n`;
  
    if (fileLines.length === 0) {
      output += "Working tree clean - no changes to commit.";
    } else {
      output += "Changes:\n";
      for (const line of fileLines) {
        const status = line.substring(0, 2);
        const file = line.substring(3);
        const meaning = meanings[status] || `Unknown status: ${status}`;
        output += `  ${file}\n    Status: ${meaning}\n\n`;
      }
    }
  
    return { content: [{ type: "text", text: output }] };
  }

• src/index.js:34-34 (schema)

  Empty input schema object, indicating the tool takes no parameters.

  {},

• src/index.js:31-78 (registration)

  Registration of the git_status_explained tool using McpServer.tool() with name, description, schema, and handler.

  server.tool(
    "git_status_explained",
    "Check git status with beginner-friendly explanations",
    {},
    async () => {
      const result = await runCommand("git status --porcelain -b");
      if (!result.success) {
        return { content: [{ type: "text", text: `Error: ${result.error}\n\nAre you in a git repository? Try: git init` }] };
      }
  
      const lines = result.stdout.split("\n").filter(Boolean);
      if (lines.length === 0) {
        return { content: [{ type: "text", text: "Not a git repository or empty output" }] };
      }
  
      const branchLine = lines[0];
      const fileLines = lines.slice(1);
  
      const meanings = {
        "??": "Untracked - New file, not yet tracked by git. Use 'git add <file>' to track it.",
        " M": "Modified - Changed but not staged. Use 'git add <file>' to stage it.",
        "M ": "Staged - Ready to be committed. Use 'git commit -m \"message\"' to commit.",
        "MM": "Modified & Staged - File was staged, then modified again.",
        "A ": "Added - New file, staged and ready to commit.",
        "D ": "Deleted - File was deleted. Stage with 'git add <file>'.",
        " D": "Deleted (unstaged) - File deleted but not staged.",
        "R ": "Renamed - File was renamed.",
        "C ": "Copied - File was copied.",
        "UU": "Conflict - Merge conflict! Edit the file to resolve.",
      };
  
      let output = `Branch: ${branchLine.replace("## ", "")}\n\n`;
  
      if (fileLines.length === 0) {
        output += "Working tree clean - no changes to commit.";
      } else {
        output += "Changes:\n";
        for (const line of fileLines) {
          const status = line.substring(0, 2);
          const file = line.substring(3);
          const meaning = meanings[status] || `Unknown status: ${status}`;
          output += `  ${file}\n    Status: ${meaning}\n\n`;
        }
      }
  
      return { content: [{ type: "text", text: output }] };
    }
  );

• src/index.js:18-25 (helper)

  Helper function runCommand used by the handler to execute shell commands safely with timeout and error handling.

  async function runCommand(cmd, options = {}) {
    try {
      const { stdout, stderr } = await execAsync(cmd, { timeout: 30000, ...options });
      return { success: true, stdout: stdout.trim(), stderr: stderr.trim() };
    } catch (error) {
      return { success: false, error: error.message, stdout: error.stdout?.trim(), stderr: error.stderr?.trim() };
    }
  }