@aaronsb/jira-cloud-mcp 0.6.0 → 0.7.0

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;
@@ -55,12 +71,9 @@ export class FieldDiscovery {
             return [];
         }
         try {
-            // Step 1: Get issue types for this project
-            const issueTypes = await client.issues.getCreateIssueMetaIssueTypes({
-                projectIdOrKey: projectKey,
-            });
-            const matchingType = (issueTypes.issueTypes || issueTypes.createMetaIssueType || [])
-                .find(t => t.name?.toLowerCase() === issueTypeName.toLowerCase());
+            // Step 1: Get issue types (uses shared cache)
+            const issueTypes = await this.getIssueTypes(client, projectKey);
+            const matchingType = issueTypes.find(t => t.name.toLowerCase() === issueTypeName.toLowerCase());
             if (!matchingType?.id) {
                 console.error(`[field-discovery] Issue type "${issueTypeName}" not found in project ${projectKey}`);
                 return this.catalog.filter(f => f.writable);
@@ -97,6 +110,92 @@ export class FieldDiscovery {
             return this.catalog.filter(f => f.writable);
         }
     }
+    // ── Required Fields Cache ────────────────────────────────────────────
+    requiredFieldsCache = new Map();
+    issueTypesCache = new Map();
+    /** Get issue types available for a project (lazy cached). */
+    async getIssueTypes(client, projectKey) {
+        const cacheKey = projectKey.toUpperCase();
+        const cached = this.issueTypesCache.get(cacheKey);
+        if (cached)
+            return cached;
+        try {
+            const result = await client.issues.getCreateIssueMetaIssueTypes({
+                projectIdOrKey: projectKey,
+            });
+            const types = (result.issueTypes || result.createMetaIssueType || [])
+                .filter((t) => t.id && t.name)
+                .map((t) => ({
+                id: t.id,
+                name: t.name,
+                subtask: t.subtask ?? false,
+            }));
+            this.issueTypesCache.set(cacheKey, types);
+            return types;
+        }
+        catch (err) {
+            console.error(`[field-discovery] Issue type fetch failed for ${projectKey}: ${err instanceof Error ? err.message : err}`);
+            return [];
+        }
+    }
+    /** Get required fields for a project + issue type combination (lazy cached). */
+    async getRequiredFields(client, projectKey, issueTypeName) {
+        const cacheKey = `${projectKey}:${issueTypeName}`.toLowerCase();
+        const cached = this.requiredFieldsCache.get(cacheKey);
+        if (cached)
+            return cached;
+        try {
+            const issueTypes = await this.getIssueTypes(client, projectKey);
+            const matchingType = issueTypes.find(t => t.name.toLowerCase() === issueTypeName.toLowerCase());
+            if (!matchingType)
+                return [];
+            const required = [];
+            let startAt = 0;
+            const maxResults = 50;
+            let hasMore = true;
+            while (hasMore) {
+                const fieldMeta = await client.issues.getCreateIssueMetaIssueTypeId({
+                    projectIdOrKey: projectKey,
+                    issueTypeId: matchingType.id,
+                    startAt,
+                    maxResults,
+                });
+                const fields = (fieldMeta.fields || fieldMeta.results || []);
+                for (const f of fields) {
+                    if (f.required && !f.hasDefaultValue) {
+                        const info = {
+                            fieldId: f.fieldId,
+                            name: f.name,
+                            schemaType: f.schema?.type ?? 'unknown',
+                        };
+                        if (f.allowedValues && Array.isArray(f.allowedValues)) {
+                            info.allowedValues = f.allowedValues
+                                .slice(0, 20)
+                                .map((v) => v.name ?? v.value ?? String(v));
+                        }
+                        required.push(info);
+                    }
+                }
+                if (fields.length < maxResults)
+                    hasMore = false;
+                startAt += fields.length;
+            }
+            this.requiredFieldsCache.set(cacheKey, required);
+            return required;
+        }
+        catch (err) {
+            console.error(`[field-discovery] Required fields fetch failed for ${projectKey}/${issueTypeName}: ${err instanceof Error ? err.message : err}`);
+            return [];
+        }
+    }
+    /** Clear required fields cache for a project (on 400 errors, cache may be stale). */
+    invalidateRequiredFields(projectKey) {
+        for (const key of this.requiredFieldsCache.keys()) {
+            if (key.startsWith(projectKey.toLowerCase() + ':')) {
+                this.requiredFieldsCache.delete(key);
+            }
+        }
+    }
     /**
      * Start discovery in the background. Does not block.
      * Returns a promise that resolves when done (for testing).
@@ -115,6 +214,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 a custom field ID after runtime discovery */
+    setCustomFieldId(logicalName, fieldId) {
+        this.customFields[logicalName] = 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/handlers/project-handlers.js

@@ -1,4 +1,5 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { fieldDiscovery } from '../client/field-discovery.js';
 import { MarkdownRenderer } from '../mcp/markdown-renderer.js';
 import { projectNextSteps } from '../utils/next-steps.js';
 import { normalizeArgs } from '../utils/normalize-args.js';
@@ -70,6 +71,16 @@ async function handleGetProject(jiraClient, args) {
         description: project.description || undefined,
         lead: project.lead || undefined,
     };
+    // Fetch issue types (always — essential context for creating issues)
+    try {
+        const issueTypes = await fieldDiscovery.getIssueTypes(jiraClient.v3Client, projectKey);
+        if (issueTypes.length > 0) {
+            projectData.issueTypes = issueTypes.map(t => ({ name: t.name, subtask: t.subtask }));
+        }
+    }
+    catch {
+        // Non-fatal — continue without issue types
+    }
     // If status counts are requested, get them
     if (includeStatusCounts) {
         try {
@@ -125,6 +136,7 @@ async function handleGetProject(jiraClient, args) {
         name: projectData.name,
         description: projectData.description,
         lead: projectData.lead,
+        issueTypes: projectData.issueTypes,
         statusCounts: projectData.statusCounts,
         boards: projectData.boards,
         recentIssues: projectData.recentIssues,

package/build/index.js

@@ -83,7 +83,16 @@ class JiraServer {
         });
         this.setupHandlers();
         // Start async field discovery (non-blocking)
-        fieldDiscovery.startAsync(this.jiraClient.v3Client);
+        fieldDiscovery.startAsync(this.jiraClient.v3Client).then(() => {
+            const wirable = ['sprint', 'storyPoints', 'startDate'];
+            for (const name of wirable) {
+                const fieldId = fieldDiscovery.getWellKnownFieldId(name);
+                if (fieldId) {
+                    this.jiraClient.setCustomFieldId(name, fieldId);
+                    console.error(`[jira-cloud] ${name} field: ${fieldId}`);
+                }
+            }
+        }).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);
@@ -214,6 +223,50 @@ class JiraServer {
                         isError: true,
                     };
                 }
+                if (status === 400) {
+                    const fieldErrors = error?.response?.data?.errors;
+                    const errorMessages = error?.response?.data?.errorMessages;
+                    const lines = ['**Jira rejected this request:**'];
+                    if (errorMessages?.length > 0) {
+                        lines.push(...errorMessages.map((m) => `- ${m}`));
+                    }
+                    if (fieldErrors && Object.keys(fieldErrors).length > 0) {
+                        lines.push('', '**Field errors:**');
+                        for (const [field, msg] of Object.entries(fieldErrors)) {
+                            lines.push(`- \`${field}\`: ${msg}`);
+                        }
+                    }
+                    // On create failures, invalidate cache and append required fields guidance
+                    const reqArgs = request.params.arguments;
+                    if (reqArgs?.operation === 'create' && reqArgs?.projectKey) {
+                        const pKey = reqArgs.projectKey;
+                        fieldDiscovery.invalidateRequiredFields(pKey);
+                        const iType = reqArgs.issueType;
+                        try {
+                            // Show valid issue types
+                            const issueTypes = await fieldDiscovery.getIssueTypes(this.jiraClient.v3Client, pKey);
+                            if (issueTypes.length > 0) {
+                                lines.push('', `**Valid issue types for ${pKey}:** ${issueTypes.map(t => t.name).join(', ')}`);
+                            }
+                            // Show required fields for the requested type
+                            if (iType) {
+                                const required = await fieldDiscovery.getRequiredFields(this.jiraClient.v3Client, pKey, iType);
+                                if (required.length > 0) {
+                                    lines.push(`**Required fields for ${pKey}/${iType}:** ${required.map(f => {
+                                        const vals = f.allowedValues ? ` (${f.schemaType}: ${f.allowedValues.slice(0, 5).join(', ')}${f.allowedValues.length > 5 ? '...' : ''})` : '';
+                                        return f.name + vals;
+                                    }).join(', ')}`);
+                                }
+                            }
+                        }
+                        catch { /* best-effort */ }
+                        lines.push('', '*Tip: Use `manage_jira_project get` to see valid issue types before creating.*');
+                    }
+                    return {
+                        content: [{ type: 'text', text: lines.join('\n') }],
+                        isError: true,
+                    };
+                }
                 if (status === 404) {
                     return {
                         content: [{

package/build/mcp/markdown-renderer.js

@@ -272,6 +272,17 @@ export function renderProject(project) {
         lines.push('');
         lines.push(truncate(stripHtml(project.description), 200));
     }
+    // Issue types
+    if (project.issueTypes && project.issueTypes.length > 0) {
+        const regular = project.issueTypes.filter(t => !t.subtask).map(t => t.name);
+        const subtasks = project.issueTypes.filter(t => t.subtask).map(t => t.name);
+        const parts = [...regular];
+        if (subtasks.length > 0) {
+            parts.push(...subtasks.map(n => `${n} (subtask)`));
+        }
+        lines.push('');
+        lines.push(`**Issue Types:** ${parts.join(', ')}`);
+    }
     // Status counts
     if (project.statusCounts && Object.keys(project.statusCounts).length > 0) {
         lines.push('');

package/build/schemas/tool-schemas.js

@@ -169,7 +169,7 @@ export const toolSchemas = {
                 },
                 issueType: {
                     type: 'string',
-                    description: 'Issue type (e.g., Story, Bug, Task). Required for create.',
+                    description: 'Issue type name — must match project configuration (e.g., Story, Bug, Task, Feature). Use manage_jira_project get to discover valid types. Required for create.',
                 },
                 priority: {
                     type: 'string',
@@ -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/build/utils/next-steps.js

@@ -108,7 +108,7 @@ export function projectNextSteps(operation, projectKey) {
             steps.push({ description: 'Get project details', tool: 'manage_jira_project', example: { operation: 'get', projectKey: '<key>' } }, { description: 'Search issues in a project', tool: 'manage_jira_filter', example: { operation: 'execute_jql', jql: `project = <key>` } });
             break;
         case 'get':
-            steps.push({ description: 'Search issues in this project', tool: 'manage_jira_filter', example: { operation: 'execute_jql', jql: `project = ${projectKey}` } }, { description: 'View project boards', tool: 'manage_jira_board', example: { operation: 'list' } }, { description: `Read jira://projects/${projectKey}/overview for additional context` });
+            steps.push({ description: 'Create an issue in this project (use issue types shown above)', tool: 'manage_jira_issue', example: { operation: 'create', projectKey, summary: '<title>', issueType: '<type from list above>' } }, { description: 'Search issues in this project', tool: 'manage_jira_filter', example: { operation: 'execute_jql', jql: `project = ${projectKey}` } }, { description: 'View project boards', tool: 'manage_jira_board', example: { operation: 'list' } });
             break;
     }
     return steps.length > 0 ? formatSteps(steps) : '';

package/package.json

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