@aaronsb/jira-cloud-mcp 0.6.0 → 0.6.1

package/build/client/field-discovery.js

@@ -14,10 +14,18 @@ const SCREEN_WEIGHT = 10;
 const RECENCY_WEIGHT = 5;
 const RECENCY_HALF_LIFE_DAYS = 30;
 // ── Field Discovery ────────────────────────────────────────────────────
+/** Well-known locked fields identified by schema custom type */
+const WELL_KNOWN_FIELDS = {
+    'com.pyxis.greenhopper.jira:gh-sprint': 'sprint',
+    'com.pyxis.greenhopper.jira:jsw-story-points': 'storyPoints',
+    'com.atlassian.jpo:jpo-custom-field-baseline-start': 'startDate',
+    'com.atlassian.jpo:jpo-custom-field-baseline-end': 'targetDate',
+};
 export class FieldDiscovery {
     catalog = [];
     nameToId = new Map();
     idToField = new Map();
+    wellKnown = new Map(); // logical name → field ID
     stats = null;
     ready = false;
     error = null;
@@ -37,6 +45,14 @@ export class FieldDiscovery {
     getStats() {
         return this.stats;
     }
+    /** Get a well-known field ID by logical name (e.g., 'sprint', 'storyPoints') */
+    getWellKnownFieldId(logicalName) {
+        return this.wellKnown.get(logicalName) ?? null;
+    }
+    /** All discovered well-known field mappings */
+    getWellKnownFields() {
+        return Object.fromEntries(this.wellKnown);
+    }
     /** Resolve a human-readable field name to its Jira field ID */
     resolveNameToId(name) {
         return this.nameToId.get(name.toLowerCase()) ?? null;
@@ -115,6 +131,14 @@ export class FieldDiscovery {
             console.error('[field-discovery] Starting custom field discovery...');
             const rawFields = await this.fetchAllCustomFields(client);
             console.error(`[field-discovery] Fetched ${rawFields.length} custom fields`);
+            // Detect well-known locked fields by schema type (before filtering)
+            for (const field of rawFields) {
+                const logicalName = WELL_KNOWN_FIELDS[field.schemaCustom];
+                if (logicalName) {
+                    this.wellKnown.set(logicalName, field.id);
+                    console.error(`[field-discovery] Well-known: ${logicalName} → ${field.id} (${field.name})`);
+                }
+            }
             const { qualified, stats } = this.filterAndClassify(rawFields);
             console.error(`[field-discovery] ${qualified.length} fields passed filters`);
             const scored = this.scoreFields(qualified);

package/build/client/jira-client.js

@@ -28,8 +28,13 @@ export class JiraClient {
         this.customFields = {
             startDate: config.customFields?.startDate ?? 'customfield_10015',
             storyPoints: config.customFields?.storyPoints ?? 'customfield_10016',
+            sprint: config.customFields?.sprint ?? null, // Discovered at runtime via field-discovery
         };
     }
+    /** Update sprint field ID after runtime discovery */
+    setSprintFieldId(fieldId) {
+        this.customFields.sprint = fieldId;
+    }
     /** Standard Jira fields that require ADF format in v3 API */
     static ADF_FIELDS = new Set(['environment']);
     /** Convert any ADF-type fields in customFields from markdown to ADF */
@@ -89,9 +94,24 @@ export class JiraClient {
             this.customFields.startDate,
             this.customFields.storyPoints,
             'timeestimate',
+            ...(this.customFields.sprint ? [this.customFields.sprint] : []),
             'issuelinks',
         ];
     }
+    /** Extract the most relevant sprint name from the sprint field array */
+    extractSprintName(sprints) {
+        if (!Array.isArray(sprints) || sprints.length === 0)
+            return null;
+        // Prefer active sprint, then future, then most recent closed
+        const active = sprints.find((s) => s.state === 'active');
+        if (active)
+            return active.name ?? null;
+        const future = sprints.find((s) => s.state === 'future');
+        if (future)
+            return future.name ?? null;
+        // Fall back to last sprint in array (most recent)
+        return sprints[sprints.length - 1]?.name ?? null;
+    }
     /** Maps a raw Jira API issue to our JiraIssueDetails shape */
     mapIssueFields(issue) {
         const fields = issue.fields ?? issue.fields;
@@ -127,6 +147,7 @@ export class JiraClient {
             startDate: fields?.[this.customFields.startDate] || null,
             storyPoints: fields?.[this.customFields.storyPoints] ?? null,
             timeEstimate: fields?.timeestimate ?? null,
+            sprint: this.customFields.sprint ? this.extractSprintName(fields?.[this.customFields.sprint]) : null,
             issueLinks: (fields?.issuelinks || []).map((link) => ({
                 type: link.type?.name || '',
                 outward: link.outwardIssue?.key || null,
@@ -517,6 +538,7 @@ export class JiraClient {
                 'status', 'resolution', 'labels', 'created', 'updated',
                 'resolutiondate', 'statuscategorychangedate', 'duedate', 'timeestimate',
                 this.customFields.startDate, this.customFields.storyPoints,
+                ...(this.customFields.sprint ? [this.customFields.sprint] : []),
             ];
             const params = {
                 jql: cleanJql,

package/build/handlers/analysis-handler.js

@@ -6,7 +6,7 @@ import { analysisNextSteps } from '../utils/next-steps.js';
 import { normalizeArgs } from '../utils/normalize-args.js';
 const ALL_METRICS = ['points', 'time', 'schedule', 'cycle', 'distribution'];
 // flow and hierarchy are opt-in only
-const VALID_GROUP_BY = ['project', 'assignee', 'priority', 'issuetype', 'parent'];
+const VALID_GROUP_BY = ['project', 'assignee', 'priority', 'issuetype', 'parent', 'sprint'];
 const MAX_ISSUES_HARD = 500; // absolute ceiling for detail metrics — beyond this, context explodes
 const MAX_ISSUES_DEFAULT = 100;
 const CUBE_SAMPLE_PCT = 0.2; // 20% of total issues
@@ -272,6 +272,10 @@ export function renderDistribution(issues, groupLimit = DEFAULT_GROUP_LIMIT) {
     lines.push(`**By priority:** ${mapToString(byPriority, ' | ', groupLimit)}`);
     const byType = countBy(issues, i => i.issueType || 'Unknown');
     lines.push(`**By type:** ${mapToString(byType, ' | ', groupLimit)}`);
+    const bySprint = countBy(issues, i => i.sprint || '(no sprint)');
+    if (bySprint.size > 1 || !bySprint.has('(no sprint)')) {
+        lines.push(`**By sprint:** ${mapToString(bySprint, ' | ', groupLimit)}`);
+    }
     return lines.join('\n');
 }
 export async function renderFlow(jiraClient, issues) {
@@ -437,6 +441,8 @@ export function groupByJqlClause(dimension, values) {
             return values.map(v => `issuetype = "${v}"`);
         case 'parent':
             return values.map(v => v === '(no parent)' ? 'issue not in childIssuesOf("")' : `parent = ${v}`);
+        case 'sprint':
+            return values.map(v => v === '(no sprint)' ? 'sprint is EMPTY' : `sprint = "${v}"`);
     }
 }
 async function buildCountRow(jiraClient, label, baseJql, implicitMeasureNames, implicitMeasureDefs) {
@@ -597,6 +603,7 @@ export function extractDimensions(issues, groupLimit = DEFAULT_GROUP_LIMIT) {
         { name: 'priority', extractor: i => i.priority || 'None' },
         { name: 'issuetype', extractor: i => i.issueType || 'Unknown' },
         { name: 'parent', extractor: i => i.parent || '(no parent)' },
+        { name: 'sprint', extractor: i => i.sprint || '(no sprint)' },
     ];
     return dims.map(({ name, extractor }) => {
         const counts = new Map();
@@ -770,6 +777,7 @@ function graphIssueToDetails(issue) {
         dueDate: issue.dueDate,
         startDate: issue.startDate,
         storyPoints: issue.storyPoints,
+        sprint: null,
         timeEstimate: null,
         issueLinks: [],
     };

package/build/index.js

@@ -83,7 +83,13 @@ class JiraServer {
         });
         this.setupHandlers();
         // Start async field discovery (non-blocking)
-        fieldDiscovery.startAsync(this.jiraClient.v3Client);
+        fieldDiscovery.startAsync(this.jiraClient.v3Client).then(() => {
+            const sprintId = fieldDiscovery.getWellKnownFieldId('sprint');
+            if (sprintId) {
+                this.jiraClient.setSprintFieldId(sprintId);
+                console.error(`[jira-cloud] Sprint field: ${sprintId}`);
+            }
+        }).catch(() => { });
         // CloudId discovery happens in run() before server connects — must complete
         // before ListTools so analyze_jira_plan is registered if available.
         this.server.onerror = (error) => console.error('[MCP Error]', error);

package/build/schemas/tool-schemas.js

@@ -352,8 +352,8 @@ export const toolSchemas = {
                 },
                 groupBy: {
                     type: 'string',
-                    enum: ['project', 'assignee', 'priority', 'issuetype', 'parent'],
-                    description: 'Split counts by this dimension — produces a breakdown table. Use with metrics: ["summary"] for exact counts. This is the correct approach for "how many issues per assignee/priority/type" questions. "project" produces a per-project comparison. "parent" groups by parent issue — useful for seeing rollups per epic/initiative.',
+                    enum: ['project', 'assignee', 'priority', 'issuetype', 'parent', 'sprint'],
+                    description: 'Split counts by this dimension — produces a breakdown table. Use with metrics: ["summary"] for exact counts. This is the correct approach for "how many issues per assignee/priority/type" questions. "project" produces a per-project comparison. "parent" groups by parent issue. "sprint" groups by sprint name.',
                 },
                 compute: {
                     type: 'array',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaronsb/jira-cloud-mcp",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "mcpName": "io.github.aaronsb/jira-cloud",
   "description": "Model Context Protocol (MCP) server for Jira Cloud - enables AI assistants to interact with Jira",
   "type": "module",