@aaronsb/jira-cloud-mcp 0.6.1 → 0.7.0

package/build/client/field-discovery.js

@@ -71,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);
@@ -113,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).

package/build/client/jira-client.js

@@ -31,9 +31,9 @@ export class JiraClient {
             sprint: config.customFields?.sprint ?? null, // Discovered at runtime via field-discovery
         };
     }
-    /** Update sprint field ID after runtime discovery */
-    setSprintFieldId(fieldId) {
-        this.customFields.sprint = fieldId;
+    /** 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']);

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

@@ -84,10 +84,13 @@ class JiraServer {
         this.setupHandlers();
         // Start async field discovery (non-blocking)
         fieldDiscovery.startAsync(this.jiraClient.v3Client).then(() => {
-            const sprintId = fieldDiscovery.getWellKnownFieldId('sprint');
-            if (sprintId) {
-                this.jiraClient.setSprintFieldId(sprintId);
-                console.error(`[jira-cloud] Sprint field: ${sprintId}`);
+            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
@@ -220,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',

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.1",
+  "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",