@abdelrahmanhsn/jira-mcp 1.3.0 → 1.5.0

package/README.md

@@ -14,6 +14,7 @@ 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` | **⚡ Full coding brief** — description, acceptance criteria, comments, branch name, implementation checklist, and PR template in one shot |
 
 ## Prerequisites
 
@@ -126,6 +127,7 @@ Once configured, you can ask your AI assistant:
 - *"Summarize the active sprint — how many tickets are done vs in progress?"*
 - *"Search for open bugs related to login"*
 - *"Get PR context for branch STUD-17891-add-email-icon"*
+- *"Start working on STUD-17891"* → get full brief, branch name, checklist and PR template instantly
 
 ## Security
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@abdelrahmanhsn/jira-mcp",
   "type": "module",
-  "version": "1.3.0",
+  "version": "1.5.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,180 @@ server.tool(
   }
 );
 
+// Tool: start_ticket
+server.tool(
+  "start_ticket",
+  "Fully start a Jira ticket: self-assigns it, moves it to In Progress, creates the git branch in the given working directory, and returns the full coding brief with description, acceptance criteria, comments, and PR template — all in one shot",
+  {
+    issueKey: z.string().describe("The Jira issue key, e.g. STUD-17891"),
+    workingDir: z.string().describe("Absolute path to the git repo where the branch should be created, e.g. /Users/you/code/my-project"),
+  },
+  async ({ issueKey, workingDir }) => {
+    const actions = [];
+
+    // ── 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 brief = [
+      `# 🎯 ${issueKey}: ${f.summary}`,
+      ``,
+      `**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,
+          description,
+          acceptance_criteria: acceptanceCriteria || null,
+          subtasks,
+          comments,
+          brief,
+        }, null, 2),
+      }],
+    };
+  }
+);
+
 // ── Start ────────────────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);