Jira MCP Server

Instructions

Implementation Reference

• src/jira-client.ts:1135-1227 (handler)

  Core handler function that implements the update_progress tool logic: fetches current Progress Update field, parses existing sections, applies selective updates (refresh date, weeklyUpdate, delivered, whatsNext), generates new ADF document, and updates the Jira issue.
  export async function updateProgressField( issueKey: string, options: { refreshDate?: boolean; weeklyUpdate?: string; delivered?: string; whatsNext?: string; } ): Promise<{ success: boolean; updatedSections: string[]; parsedExisting?: { weeklyUpdate: string; delivered: string; whatsNext: string } }> { const PROGRESS_FIELD_ID = 'customfield_15112'; // Fetch current field value const currentValue = await getIssueCustomField(issueKey, PROGRESS_FIELD_ID); // Parse existing content const existing = parseProgressUpdateADF(currentValue); // Format current date const currentDate = new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric', }); // Determine which sections to update const updatedSections: string[] = []; let weeklyUpdate = existing.weeklyUpdate; let delivered = existing.delivered; let whatsNext = existing.whatsNext; // Handle refreshDate option - preserve existing content but update the date if (options.refreshDate) { // Extract just the content part from weeklyUpdate (remove old date or [date] placeholder if present) // The parsed weeklyUpdate may be: // - "December 10, 2025 - Some content" // - "[date] - Some content" // - Just "[date]" // - Just content with no date prefix let contentOnly = weeklyUpdate; // Remove date pattern like "December 10, 2025 - " or "December 10, 2025" const dateMatch = contentOnly.match(/^[A-Z][a-z]+ \d{1,2}, \d{4}\s*-?\s*/); if (dateMatch) { contentOnly = contentOnly.slice(dateMatch[0].length); } // Remove [date] placeholder pattern like "[date] - " or "[date]" const placeholderMatch = contentOnly.match(/^\[date\]\s*-?\s*/); if (placeholderMatch) { contentOnly = contentOnly.slice(placeholderMatch[0].length); } contentOnly = contentOnly.trim(); weeklyUpdate = contentOnly ? `${currentDate} - ${contentOnly}` : currentDate; updatedSections.push('weeklyUpdate (date refreshed)'); } // Handle explicit weeklyUpdate option if (options.weeklyUpdate !== undefined) { weeklyUpdate = options.weeklyUpdate ? `${currentDate} - ${options.weeklyUpdate}` : currentDate; updatedSections.push('weeklyUpdate'); } if (options.delivered !== undefined) { delivered = options.delivered; updatedSections.push('delivered'); } if (options.whatsNext !== undefined) { whatsNext = options.whatsNext; updatedSections.push('whatsNext'); } // Create the updated ADF document const updatedADF = createProgressUpdateADF(weeklyUpdate, delivered, whatsNext); // Update the field await jiraFetch<void>(`/issue/${issueKey}`, { method: 'PUT', body: JSON.stringify({ fields: { [PROGRESS_FIELD_ID]: updatedADF, }, }), }); return { success: true, updatedSections, parsedExisting: existing, }; }
• src/index.ts:520-582 (registration)

  MCP tool registration for 'update_progress', including title, description, inputSchema, outputSchema, and wrapper handler that validates inputs and delegates to updateProgressField.
  server.registerTool( 'update_progress', { title: 'Update Progress', description: `Update the Progress Update field (customfield_15112) on a Jira issue. This field uses a structured template with three sections: - Weekly Update: "ℹ️ Update for week of [date]:" - automatically includes current date - Delivered: "✅ What we've delivered so far:" - What's Next: "❓ What's next:" Options: - Use refreshDate=true to update just the date while preserving all existing content - Only sections you explicitly provide will be updated; others are preserved from existing content`, inputSchema: { issueKey: z.string().describe('The issue key (e.g., "TSSE-984")'), refreshDate: z.boolean().optional().describe('If true, updates the date to today while preserving all existing content. Use this to "refresh" the progress update without changing the content.'), weeklyUpdate: z.string().optional().describe('Text to add after the weekly header. Current date will be auto-inserted.'), delivered: z.string().optional().describe('Text describing what was delivered'), whatsNext: z.string().optional().describe('Text describing upcoming work'), }, outputSchema: { success: z.boolean(), updatedSections: z.array(z.string()).optional(), parsedExisting: z.object({ weeklyUpdate: z.string(), delivered: z.string(), whatsNext: z.string(), }).optional(), error: z.object({ message: z.string(), statusCode: z.number().optional(), details: z.unknown().optional(), }).optional(), }, }, async ({ issueKey, refreshDate, weeklyUpdate, delivered, whatsNext }) => { try { if (!issueKey || !issueKey.trim()) { throw new Error('issueKey is required'); } if (!refreshDate && weeklyUpdate === undefined && delivered === undefined && whatsNext === undefined) { throw new Error('At least one of refreshDate, weeklyUpdate, delivered, or whatsNext must be provided'); } const result = await updateProgressField(issueKey, { refreshDate, weeklyUpdate, delivered, whatsNext, }); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: result, }; } catch (error) { const output = { success: false, ...formatError(error) }; return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }], structuredContent: output, isError: true, }; } } );
• src/index.ts:532-552 (schema)

  Zod inputSchema and outputSchema definitions for the update_progress tool, defining parameters like issueKey, refreshDate, weeklyUpdate, delivered, whatsNext and response structure.
  inputSchema: { issueKey: z.string().describe('The issue key (e.g., "TSSE-984")'), refreshDate: z.boolean().optional().describe('If true, updates the date to today while preserving all existing content. Use this to "refresh" the progress update without changing the content.'), weeklyUpdate: z.string().optional().describe('Text to add after the weekly header. Current date will be auto-inserted.'), delivered: z.string().optional().describe('Text describing what was delivered'), whatsNext: z.string().optional().describe('Text describing upcoming work'), }, outputSchema: { success: z.boolean(), updatedSections: z.array(z.string()).optional(), parsedExisting: z.object({ weeklyUpdate: z.string(), delivered: z.string(), whatsNext: z.string(), }).optional(), error: z.object({ message: z.string(), statusCode: z.number().optional(), details: z.unknown().optional(), }).optional(), },
• src/jira-client.ts:880-985 (helper)

  Helper function to parse existing Progress Update ADF content into structured sections (weeklyUpdate, delivered, whatsNext), supporting both simple paragraphs and complex panel/bullet formats.
  function parseProgressUpdateADF(adf: unknown): { weeklyUpdate: string; delivered: string; whatsNext: string; } { const result = { weeklyUpdate: '[date]', delivered: '', whatsNext: '', }; if (!adf || typeof adf !== 'object') return result; const doc = adf as { content?: unknown[] }; if (!doc.content || !Array.isArray(doc.content)) return result; // Track which section we're currently parsing let currentSection: 'weekly' | 'delivered' | 'whatsNext' | null = null; for (const block of doc.content) { const b = block as { type?: string; content?: unknown[]; attrs?: unknown }; // Handle panel blocks (complex format) if (b.type === 'panel' && b.content) { let panelHeader = ''; const panelItems: string[] = []; for (const panelChild of b.content) { const pc = panelChild as { type?: string; content?: unknown[] }; // Extract heading text if (pc.type === 'heading') { panelHeader = extractTextFromADFNode(pc); } // Extract bullet list items if (pc.type === 'bulletList') { panelItems.push(...extractBulletListItems(pc)); } } // Determine which section based on header (handle both straight and curly apostrophes) const normalizedHeader = panelHeader.replace(/[']/g, "'"); if (normalizedHeader.includes('Update for week of')) { const dateMatch = panelHeader.match(/Update for week of ([^:]+):/); result.weeklyUpdate = dateMatch ? dateMatch[1].trim() : '[date]'; if (panelItems.length > 0) { result.weeklyUpdate += ' - ' + panelItems.join('. '); } } else if (normalizedHeader.includes('delivered so far')) { result.delivered = panelItems.join('. '); } else if (normalizedHeader.includes("What's next")) { result.whatsNext = panelItems.join('. '); } continue; } // Handle simple paragraph format if (b.type === 'paragraph' && b.content) { const paragraphText = extractTextFromADFNode(b); // Check for section headers const weeklyMatch = paragraphText.match(/Update for week of ([^:]+):(.*)/); if (weeklyMatch) { result.weeklyUpdate = weeklyMatch[1].trim(); if (weeklyMatch[2]?.trim()) { result.weeklyUpdate += ' - ' + weeklyMatch[2].trim(); } currentSection = 'weekly'; continue; } const deliveredMatch = paragraphText.match(/What we['']ve delivered so far:(.*)/); if (deliveredMatch) { result.delivered = deliveredMatch[1]?.trim() || ''; currentSection = 'delivered'; continue; } const whatsNextMatch = paragraphText.match(/What['']s next:(.*)/); if (whatsNextMatch) { result.whatsNext = whatsNextMatch[1]?.trim() || ''; currentSection = 'whatsNext'; continue; } // If we're in a section and this is additional content, append it if (currentSection && paragraphText.trim()) { switch (currentSection) { case 'weekly': result.weeklyUpdate += (result.weeklyUpdate.includes(' - ') ? '. ' : ' - ') + paragraphText.trim(); break; case 'delivered': result.delivered += (result.delivered ? '. ' : '') + paragraphText.trim(); break; case 'whatsNext': result.whatsNext += (result.whatsNext ? '. ' : '') + paragraphText.trim(); break; } } } } return result; }
• src/jira-client.ts:686-709 (helper)

  Helper function to create the ADF document for the Progress Update field with the three-section template using emojis and proper formatting.
  export function createProgressUpdateADF( weeklyUpdate: string, delivered: string, whatsNext: string ): object { return { type: 'doc', version: 1, content: [ createADFParagraph( `Update for week of ${weeklyUpdate}:`, { shortName: ':info:', id: 'atlassian-info', text: ':info:' } ), createADFParagraph( `What we've delivered so far: ${delivered}`, { shortName: ':check_mark:', id: 'atlassian-check_mark', text: ':check_mark:' } ), createADFParagraph( `What's next: ${whatsNext}`, { shortName: ':question:', id: 'atlassian-question_mark', text: ':question:' } ), ], }; }