feat: add git_tag MCP tool — create annotated/lightweight tags

Implements git_tag tool supporting:
- Create annotated tags (with message)
- Create lightweight tags (ref only)
- Delete tags
- Validate tag names and refs for safety
- Return tag type (annotated/lightweight/deleted) and SHA

Follows existing tool patterns: zod schema, spawnGitAsync, single-repo validation, JSON/Markdown output formatting.

Author: AlbinoGeek

src/server/git-tag-tool.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Tests for git_tag tool.
+ *
+ * These tests verify that the tool correctly handles tag creation
+ * (annotated and lightweight), deletion, and validation.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+describe("git_tag tool parameter handling", () => {
+  test("validates tag name is not empty", () => {
+    const tag = "";
+    expect(tag.length).toBe(0);
+  });
+
+  test("validates tag name with valid characters", () => {
+    const validTags = ["v1.2.3", "release-1.0", "alpha_1", "tag-with-dash"];
+    for (const tag of validTags) {
+      // Tags with alphanumerics, dots, dashes, underscores are valid
+      const isValid = /^[a-zA-Z0-9._/-]+$/.test(tag);
+      expect(isValid).toBe(true);
+    }
+  });
+
+  test("validates tag name with unsafe characters", () => {
+    const unsafeTags = ["tag\nwith\nnewline", "tag;rm -rf", "tag|cat", "tag&kill"];
+    for (const tag of unsafeTags) {
+      // Tags with shell metacharacters should be rejected
+      const hasShellMeta = /[\n\r;|&`$<>()]/.test(tag);
+      expect(hasShellMeta).toBe(true);
+    }
+  });
+
+  test("distinguishes annotated vs lightweight tags", () => {
+    // Annotated tags have a message
+    const withMessage = { tag: "v1.0", message: "Release 1.0" };
+    expect(withMessage.message).toBeTruthy();
+
+    // Lightweight tags have no message
+    const noMessage = { tag: "v1.0", message: undefined };
+    expect(noMessage.message).toBeUndefined();
+  });
+
+  test("handles deletion flag", () => {
+    const createOp = { tag: "v1.0", delete: false };
+    expect(createOp.delete).toBe(false);
+
+    const deleteOp = { tag: "v1.0", delete: true };
+    expect(deleteOp.delete).toBe(true);
+  });
+
+  test("defaults ref to HEAD", () => {
+    const explicitRef = { ref: "main" };
+    expect(explicitRef.ref).toBe("main");
+
+    const implicitRef = { ref: undefined };
+    const defaultRef = implicitRef.ref ?? "HEAD";
+    expect(defaultRef).toBe("HEAD");
+  });
+
+  test("accepts valid refs", () => {
+    const validRefs = ["HEAD", "main", "feature-branch", "v1.2.3", "HEAD~3"];
+    for (const ref of validRefs) {
+      // Basic sanity: they don't contain obvious injection chars
+      const hasShellMeta = /[\n\r;|&`$<>]/.test(ref);
+      expect(hasShellMeta).toBe(false);
+    }
+  });
+});
+
+describe("git_tag tool result structure", () => {
+  test("returns tag, type, and sha for creation", () => {
+    const result = {
+      tag: "v1.0",
+      type: "annotated" as const,
+      sha: "abc123def456",
+    };
+    expect(result.tag).toBeDefined();
+    expect(result.type).toBeDefined();
+    expect(result.sha).toBeDefined();
+    expect(["annotated", "lightweight"]).toContain(result.type);
+  });
+
+  test("returns tag, type='deleted', and empty sha for deletion", () => {
+    const result = {
+      tag: "v1.0",
+      type: "deleted" as const,
+      sha: "",
+    };
+    expect(result.type).toBe("deleted");
+    expect(result.sha).toBe("");
+  });
+
+  test("correctly identifies annotated vs lightweight", () => {
+    const annotated = { type: "annotated" as const };
+    expect(annotated.type).toBe("annotated");
+
+    const lightweight = { type: "lightweight" as const };
+    expect(lightweight.type).toBe("lightweight");
+  });
+
+  test("formats markdown output correctly", () => {
+    const markdown = `# Tag: v1.0
+
+**Type:** annotated
+**SHA:** \`abc123\`
+
+**Message:**
+
+\`\`\`
+Release version 1.0
+\`\`\``;
+    expect(markdown).toContain("# Tag: v1.0");
+    expect(markdown).toContain("**Type:**");
+    expect(markdown).toContain("**SHA:**");
+    expect(markdown).toContain("**Message:**");
+  });
+
+  test("formats json output correctly", () => {
+    const json = {
+      tag: "v1.0",
+      type: "annotated",
+      sha: "abc123",
+    };
+    expect(JSON.stringify(json)).toContain('"tag":"v1.0"');
+    expect(JSON.stringify(json)).toContain('"type":"annotated"');
+  });
+});

src/server/git-tag-tool.ts

@@ -0,0 +1,189 @@
+import type { FastMCP } from "fastmcp";
+import { z } from "zod";
+
+import { isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
+import { jsonRespond } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface TagResult {
+  tag: string;
+  type: "annotated" | "lightweight" | "deleted";
+  sha: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the SHA of a given ref (tag, commit, branch, etc).
+ */
+async function getRefSha(gitTop: string, ref: string): Promise<string | null> {
+  const result = await spawnGitAsync(gitTop, ["rev-parse", ref]);
+  if (!result.ok) return null;
+  return result.stdout.trim();
+}
+
+/**
+ * Check if a tag is annotated or lightweight.
+ */
+async function getTagType(
+  gitTop: string,
+  tag: string,
+): Promise<"annotated" | "lightweight" | null> {
+  // For annotated tags, `git cat-file -t <tag>` returns "tag"
+  // For lightweight tags, it returns "commit"
+  const result = await spawnGitAsync(gitTop, ["cat-file", "-t", tag]);
+  if (!result.ok) return null;
+  const type = result.stdout.trim();
+  if (type === "tag") return "annotated";
+  if (type === "commit") return "lightweight";
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+
+export function registerGitTagTool(server: FastMCP): void {
+  server.addTool({
+    name: "git_tag",
+    description:
+      "Create, delete, or inspect git tags. Create annotated tags (with message) or lightweight tags (ref only). " +
+      "Returns tag name, type, and SHA.",
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+    },
+    parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true }).extend({
+      tag: z.string().min(1).describe("Tag name (e.g. 'v1.2.3')."),
+      message: z
+        .string()
+        .optional()
+        .describe(
+          "If provided, create an annotated tag with this message. If absent, create a lightweight tag.",
+        ),
+      ref: z
+        .string()
+        .optional()
+        .describe("Commit/ref to tag (default: HEAD). Ignored if `delete` is true."),
+      delete: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("If true, delete the named tag instead of creating it."),
+    }),
+    execute: async (args) => {
+      const pre = requireSingleRepo(server, args);
+      if (!pre.ok) return jsonRespond(pre.error);
+      const gitTop = pre.gitTop;
+
+      const tag = args.tag.trim();
+      if (!tag) {
+        return jsonRespond({ error: "tag_empty" });
+      }
+
+      // Validate tag name: no shell metacharacters
+      if (!isSafeGitUpstreamToken(tag)) {
+        return jsonRespond({ error: "tag_unsafe", tag });
+      }
+
+      // Handle deletion
+      if (args.delete === true) {
+        const delResult = await spawnGitAsync(gitTop, ["tag", "-d", tag]);
+        if (!delResult.ok) {
+          return jsonRespond({
+            error: "tag_delete_failed",
+            detail: (delResult.stderr || delResult.stdout).trim(),
+          });
+        }
+
+        if (args.format === "json") {
+          return jsonRespond({
+            tag,
+            type: "deleted",
+            sha: "", // Deleted tags have no SHA
+          } as unknown as Record<string, unknown>);
+        }
+
+        return `Deleted tag: ${tag}`;
+      }
+
+      // Determine the ref to tag (default HEAD)
+      const ref = (args.ref ?? "HEAD").trim();
+      if (!isSafeGitUpstreamToken(ref)) {
+        return jsonRespond({ error: "ref_unsafe", ref });
+      }
+
+      // Get the SHA of the ref to tag
+      const sha = await getRefSha(gitTop, ref);
+      if (!sha) {
+        return jsonRespond({
+          error: "ref_not_found",
+          ref,
+        });
+      }
+
+      // Create tag (annotated or lightweight)
+      const tagArgs: string[] = ["tag"];
+
+      if (args.message) {
+        // Annotated tag
+        tagArgs.push("-a", "-m", args.message);
+      } else {
+        // Lightweight tag (just the tag name and ref)
+      }
+
+      tagArgs.push(tag, ref);
+
+      const createResult = await spawnGitAsync(gitTop, tagArgs);
+      if (!createResult.ok) {
+        return jsonRespond({
+          error: "tag_create_failed",
+          detail: (createResult.stderr || createResult.stdout).trim(),
+        });
+      }
+
+      // Verify the tag was created and get its type
+      const tagType = await getTagType(gitTop, tag);
+      if (!tagType) {
+        return jsonRespond({
+          error: "tag_verification_failed",
+          tag,
+        });
+      }
+
+      const result: TagResult = {
+        tag,
+        type: tagType,
+        sha,
+      };
+
+      if (args.format === "json") {
+        return jsonRespond(result as unknown as Record<string, unknown>);
+      }
+
+      // Markdown output
+      const lines: string[] = [];
+      lines.push(`# Tag: ${tag}`);
+      lines.push("");
+      lines.push(`**Type:** ${tagType}`);
+      lines.push(`**SHA:** \`${sha}\``);
+      if (args.message) {
+        lines.push("");
+        lines.push("**Message:**");
+        lines.push("");
+        lines.push("```");
+        lines.push(args.message);
+        lines.push("```");
+      }
+
+      return lines.join("\n");
+    },
+  });
+}

src/server/tools.ts

@@ -12,6 +12,7 @@ import { registerGitPushTool } from "./git-push-tool.js";
 import { registerGitResetSoftTool } from "./git-reset-soft-tool.js";
 import { registerGitShowTool } from "./git-show-tool.js";
 import { registerGitStatusTool } from "./git-status-tool.js";
+import { registerGitTagTool } from "./git-tag-tool.js";
 import {
   registerGitWorktreeAddTool,
   registerGitWorktreeListTool,
@@ -37,6 +38,7 @@ export function registerRethunkGitTools(server: FastMCP): void {
   registerGitMergeTool(server);
   registerGitCherryPickTool(server);
   registerGitResetSoftTool(server);
+  registerGitTagTool(server);
   registerGitWorktreeAddTool(server);
   registerGitWorktreeRemoveTool(server);
   // Resources