@abdelrahmanhsn/jira-mcp 1.3.0 → 1.6.0

package/README.md

@@ -1,6 +1,8 @@
 # @abdelrahmanhsn/jira-mcp
 
-A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects your AI IDE to Jira. Query your tickets, active sprint, and issue details directly from GitHub Copilot, Cursor, Claude Desktop, or any MCP-compatible client.
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects your AI IDE to Jira. Query tickets, manage sprints, and let AI autonomously implement, test, and ship Jira tickets — all without leaving your editor.
+
+Works with GitHub Copilot, Cursor, Claude Desktop, and any MCP-compatible client.
 
 ## Tools
 
@@ -14,12 +16,32 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that co
 | `get_sprint_summary` | Get all sprint tickets grouped by status (Todo / In Progress / Done) |
 | `search_tickets` | Search tickets with plain English or raw JQL |
 | `get_context_for_pr` | Extract Jira ticket from a branch name and return a ready-to-use PR description block |
+| `start_ticket` | **🤖 Autonomous mode** — assigns ticket, moves to In Progress, creates git branch, then drives AI to implement, test, commit, push, open PR, and comment on Jira — non-stop |
 
 ## Prerequisites
 
 - Node.js 18 or later
 - A Jira Cloud account
 - A Jira API token ([generate one here](https://id.atlassian.com/manage-profile/security/api-tokens))
+- **GitHub CLI** — required for `start_ticket` to create PRs automatically
+
+### Install GitHub CLI
+
+```bash
+# macOS
+brew install gh
+gh auth login
+
+# Windows
+winget install --id GitHub.cli
+gh auth login
+
+# Linux
+# See https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+gh auth login
+```
+
+> If `gh` is not installed or not authenticated, `start_ticket` will return clear instructions instead of silently failing.
 
 ## Setup
 
@@ -115,17 +137,47 @@ Open `~/Library/Application Support/Claude/claude_desktop_config.json` and add:
 
 ## Usage Examples
 
-Once configured, you can ask your AI assistant:
+### Everyday queries
 
 - *"Show me my current Jira tickets"*
 - *"What's in my active sprint?"*
 - *"Get me the details for PROJ-1234"*
-- *"Summarize the description of PROJ-5678"*
 - *"Add a comment to PROJ-123 saying the fix is deployed to staging"*
 - *"Give me my standup for today"*
 - *"Summarize the active sprint — how many tickets are done vs in progress?"*
 - *"Search for open bugs related to login"*
+
+### PR workflow
+
 - *"Get PR context for branch STUD-17891-add-email-icon"*
+  → Extracts the ticket key from the branch, fetches description + comments, returns a formatted PR description block ready to paste or expand.
+
+### Autonomous mode — `start_ticket`
+
+The most powerful tool. One prompt and AI does everything:
+
+```
+"Start working on STUD-17931"
+```
+
+**What happens automatically, with no stops:**
+1. ✅ Self-assigns the Jira ticket to you
+2. ✅ Moves it to **In Progress**
+3. ✅ Creates and switches to a git branch (e.g. `stud-17931-content-preview-bug`)
+4. ✅ AI reads description, acceptance criteria, and comments
+5. ✅ Implements the feature/fix
+6. ✅ Runs the test suite — fixes failures automatically
+7. ✅ Commits and pushes the branch
+8. ✅ Opens a PR via `gh pr create`
+9. ✅ Posts the PR link as a comment on the Jira ticket
+
+You can optionally pass the repo path:
+
+```
+"Start working on STUD-17931 in /Users/you/code/my-project"
+```
+
+If omitted, the tool auto-detects the git repo from the current working directory.
 
 ## Security
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@abdelrahmanhsn/jira-mcp",
   "type": "module",
-  "version": "1.3.0",
+  "version": "1.6.0",
   "description": "MCP server for Jira — query your tickets, active sprints, and issue details from any AI IDE (GitHub Copilot, Cursor, Claude Desktop)",
   "main": "server.js",
   "bin": {

package/server.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import axios from "axios";
+import { execSync } from "child_process";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -269,6 +270,253 @@ server.tool(
   }
 );
 
+// Tool: start_ticket
+server.tool(
+  "start_ticket",
+  "Fully start a Jira ticket in AUTONOMOUS mode: self-assigns, moves to In Progress, creates the git branch, then returns agent instructions that drive non-stop autonomous implementation, testing, commit, push, PR creation, and Jira comment — no confirmation needed",
+  {
+    issueKey: z.string().describe("The Jira issue key, e.g. STUD-17891"),
+    workingDir: z.string().optional().describe("Absolute path to the git repo. If omitted, the tool auto-detects from the current working directory."),
+  },
+  async ({ issueKey, workingDir }) => {
+    const actions = [];
+
+    // ── Auto-detect workingDir if not provided ────────────────────────────────
+    if (!workingDir) {
+      try {
+        workingDir = execSync("git rev-parse --show-toplevel", { stdio: "pipe" }).toString().trim();
+        actions.push(`✅ Auto-detected repo: ${workingDir}`);
+      } catch {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              error: "Could not auto-detect the git repository.",
+              fix: "Re-run start_ticket and pass the workingDir parameter explicitly, e.g. /Users/you/code/my-project",
+              hint: "The AI should look at the currently open workspace/files in the editor to determine the correct path and retry.",
+            }, null, 2),
+          }],
+        };
+      }
+    }
+
+    // ── 0. Preflight: verify gh CLI is installed and authenticated ───────────
+    try {
+      execSync("gh --version", { stdio: "pipe" });
+    } catch {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            error: "GitHub CLI (gh) is not installed.",
+            fix: "Install it first, then re-run start_ticket.",
+            install_steps: {
+              macOS: "brew install gh",
+              windows: "winget install --id GitHub.cli",
+              linux: "https://github.com/cli/cli/blob/trunk/docs/install_linux.md",
+            },
+            after_install: "Run `gh auth login` to authenticate, then retry.",
+          }, null, 2),
+        }],
+      };
+    }
+
+    try {
+      execSync("gh auth status", { stdio: "pipe" });
+    } catch {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            error: "GitHub CLI is installed but not authenticated.",
+            fix: "Run `gh auth login` in your terminal, complete the browser flow, then retry start_ticket.",
+          }, null, 2),
+        }],
+      };
+    }
+
+    actions.push("✅ GitHub CLI (gh) is installed and authenticated");
+
+    // ── 1. Fetch ticket + comments + current user in parallel ────────────────
+    const [issueRes, commentsRes, myselfRes, transitionsRes] = await Promise.all([
+      jiraClient.get(`/issue/${issueKey}`, {
+        params: {
+          fields: "summary,description,issuetype,priority,status,assignee,reporter,labels,components,customfield_10016,customfield_10014,customfield_10021,subtasks,parent",
+        },
+      }),
+      jiraClient.get(`/issue/${issueKey}/comment`, {
+        params: { maxResults: 20, orderBy: "-created" },
+      }),
+      jiraClient.get("/myself"),
+      jiraClient.get(`/issue/${issueKey}/transitions`),
+    ]);
+
+    const f = issueRes.data.fields;
+    const me = myselfRes.data;
+
+    // Extract plain text from Atlassian Document Format
+    function extractText(node) {
+      if (!node) return "";
+      if (node.type === "text") return node.text || "";
+      if (node.type === "hardBreak") return "\n";
+      if (node.content) return node.content.map(extractText).join(node.type === "paragraph" ? "\n" : " ");
+      return "";
+    }
+
+    const description = extractText(f.description).trim() || "No description provided.";
+    const acceptanceCriteria = extractText(
+      f["customfield_10016"] || f["customfield_10014"] || f["customfield_10021"] || null
+    ).trim();
+
+    const comments = (commentsRes.data.comments || [])
+      .map(c => ({ author: c.author?.displayName, body: extractText(c.body).trim(), created: c.created?.split("T")[0] }))
+      .filter(c => c.body);
+
+    const subtasks = (f.subtasks || []).map(s => ({
+      key: s.key,
+      summary: s.fields?.summary,
+      status: s.fields?.status?.name,
+    }));
+
+    // ── 2. Self-assign the ticket ─────────────────────────────────────────────
+    try {
+      await jiraClient.put(`/issue/${issueKey}/assignee`, { accountId: me.accountId });
+      actions.push(`✅ Assigned to ${me.displayName}`);
+    } catch (e) {
+      actions.push(`⚠️  Could not assign: ${e.response?.data?.errorMessages?.[0] ?? e.message}`);
+    }
+
+    // ── 3. Transition to "In Progress" ────────────────────────────────────────
+    const transitions = transitionsRes.data.transitions || [];
+    const inProgress = transitions.find(t =>
+      /in.?progress|start|doing|in.?dev/i.test(t.name)
+    );
+    if (inProgress) {
+      try {
+        await jiraClient.post(`/issue/${issueKey}/transitions`, { transition: { id: inProgress.id } });
+        actions.push(`✅ Moved to "${inProgress.name}"`);
+      } catch (e) {
+        actions.push(`⚠️  Could not transition: ${e.response?.data?.errorMessages?.[0] ?? e.message}`);
+      }
+    } else {
+      const available = transitions.map(t => t.name).join(", ");
+      actions.push(`⚠️  No "In Progress" transition found. Available: ${available}`);
+    }
+
+    // ── 4. Create git branch ──────────────────────────────────────────────────
+    const slugifiedSummary = (f.summary || "")
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, "")
+      .trim()
+      .replace(/\s+/g, "-")
+      .slice(0, 50)
+      .replace(/-+$/, "");
+    const branchName = `${issueKey.toLowerCase()}-${slugifiedSummary}`;
+
+    try {
+      execSync(`git -C "${workingDir}" checkout -b "${branchName}"`, { stdio: "pipe" });
+      actions.push(`✅ Created and switched to branch: ${branchName}`);
+    } catch (e) {
+      const stderr = e.stderr?.toString() ?? "";
+      if (stderr.includes("already exists")) {
+        try {
+          execSync(`git -C "${workingDir}" checkout "${branchName}"`, { stdio: "pipe" });
+          actions.push(`✅ Branch already exists — switched to: ${branchName}`);
+        } catch {
+          actions.push(`⚠️  Branch exists but could not switch: ${stderr}`);
+        }
+      } else {
+        actions.push(`⚠️  Git error: ${stderr || e.message}`);
+      }
+    }
+
+    const ticketUrl = `https://${JIRA_DOMAIN}/browse/${issueKey}`;
+
+    const agentInstructions = [
+      `You are now in AUTONOMOUS CODING MODE for ${issueKey}.`,
+      ``,
+      `RULES — follow these exactly, do NOT stop or ask for confirmation at any point:`,
+      `1. You are already on branch \`${branchName}\` in \`${workingDir}\` — start coding immediately.`,
+      `2. Read the description and acceptance criteria below — implement everything required.`,
+      `3. After implementing, run the test suite automatically. Fix any failures before moving on.`,
+      `4. If you encounter an ambiguity, make the most reasonable assumption and document it in a code comment — do NOT pause to ask.`,
+      `5. After all tests pass, run: \`git -C "${workingDir}" add -A && git -C "${workingDir}" commit -m "${issueKey}: ${f.summary}" && git -C "${workingDir}" push -u origin ${branchName}\``,
+      `6. Create the PR by running: \`gh pr create --repo $(git -C "${workingDir}" remote get-url origin) --title "${issueKey}: ${f.summary}" --body "Resolves ${ticketUrl}" --head ${branchName}\``,
+      `7. Capture the PR URL from the gh output and call the add_comment tool to post it on ${issueKey}.`,
+      `8. Only stop when the PR is open and the Jira ticket has been commented. That is the definition of done.`,
+    ].join("\n");
+
+    const brief = [
+      `# 🤖 AUTONOMOUS MODE — ${issueKey}: ${f.summary}`,
+      ``,
+      agentInstructions,
+      ``,
+      `**Type:** ${f.issuetype?.name} | **Priority:** ${f.priority?.name}`,
+      `**Assignee:** ${me.displayName} | **Reporter:** ${f.reporter?.displayName}`,
+      f.labels?.length ? `**Labels:** ${f.labels.join(", ")}` : "",
+      f.components?.length ? `**Components:** ${f.components.map(c => c.name).join(", ")}` : "",
+      `**Ticket:** ${ticketUrl}`,
+      ``,
+      `## ⚡ Actions Taken`,
+      ...actions.map(a => `- ${a}`),
+      ``,
+      `## 📋 Description`,
+      description,
+      acceptanceCriteria ? `\n## ✅ Acceptance Criteria\n${acceptanceCriteria}` : "",
+      subtasks.length > 0
+        ? `\n## 🔀 Subtasks\n${subtasks.map(s => `- [${s.status === "Done" ? "x" : " "}] ${s.key}: ${s.summary} (${s.status})`).join("\n")}`
+        : "",
+      comments.length > 0
+        ? `\n## 💬 Recent Comments\n${comments.slice(0, 5).map(c => `**${c.author}** (${c.created}):\n${c.body}`).join("\n\n---\n\n")}`
+        : "",
+      ``,
+      `## 🚀 Implementation Checklist`,
+      `- [ ] Implement the feature/fix on branch \`${branchName}\``,
+      `- [ ] Write unit tests`,
+      `- [ ] Write integration tests if applicable`,
+      `- [ ] Run full test suite`,
+      `- [ ] Create PR with title: \`${issueKey}: ${f.summary}\``,
+      `- [ ] Link PR to ticket: ${ticketUrl}`,
+      ``,
+      `## 📝 PR Description Template`,
+      `### What`,
+      description.split("\n")[0],
+      ``,
+      `### Why`,
+      `Resolves ${issueKey} — ${ticketUrl}`,
+      ``,
+      `### How`,
+      `<!-- Describe your implementation approach -->`,
+      ``,
+      `### Testing`,
+      `- [ ] Unit tests added/updated`,
+      `- [ ] Integration tests added/updated`,
+      `- [ ] Manually tested`,
+    ].filter(l => l !== null && l !== undefined).join("\n");
+
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          issue_key: issueKey,
+          summary: f.summary,
+          type: f.issuetype?.name,
+          priority: f.priority?.name,
+          branch_name: branchName,
+          ticket_url: ticketUrl,
+          actions_taken: actions,
+          agent_instructions: agentInstructions,
+          description,
+          acceptance_criteria: acceptanceCriteria || null,
+          subtasks,
+          comments,
+          brief,
+        }, null, 2),
+      }],
+    };
+  }
+);
+
 // ── Start ────────────────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);