@aaronsb/jira-cloud-mcp 0.10.0 → 0.11.1

package/build/handlers/filter-handlers.js

@@ -291,6 +291,15 @@ async function handleExecuteJql(jiraClient, args) {
     // Set default pagination values
     const startAt = args.startAt !== undefined ? args.startAt : 0;
     const maxResults = args.maxResults !== undefined ? args.maxResults : 25;
+    // Validate field/function names and syntax before searching. The enhanced search endpoint
+    // silently returns zero results for an unknown field, so a typo'd field name would otherwise
+    // be indistinguishable from "that field is empty everywhere" (ADR-213 §A3, #44).
+    const jqlErrors = await jiraClient.parseJqlErrors(args.jql);
+    if (jqlErrors.length > 0) {
+        throw new McpError(ErrorCode.InvalidParams, `Invalid JQL — Jira rejected this query:\n${jqlErrors.map(e => `  - ${e}`).join('\n')}\n\n` +
+            `If you meant a custom field, check its exact name in the jira://custom-fields resource ` +
+            `(or jira://custom-fields/{projectKey}/{issueType} for fields on a specific issue type).`);
+    }
     try {
         console.error(`Executing JQL search with args:`, JSON.stringify(args, null, 2));
         // Parse search expansion options (not currently used but reserved for future)

package/build/handlers/issue-handlers.js

@@ -1,6 +1,7 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { fieldDiscovery } from '../client/field-discovery.js';
 import { categoryLabel } from '../client/field-type-map.js';
+import { routeForField } from '../extensions/index.js';
 import { MarkdownRenderer } from '../mcp/markdown-renderer.js';
 import { bulkOperationGuard } from '../utils/bulk-operation-guard.js';
 import { issueNextSteps } from '../utils/next-steps.js';
@@ -120,7 +121,7 @@ function validateManageJiraIssueArgs(args) {
         if (!Array.isArray(normalizedArgs.expand)) {
             throw new McpError(ErrorCode.InvalidParams, 'Invalid expand parameter. Expected an array of strings.');
         }
-        const validExpansions = ['comments', 'transitions', 'attachments', 'related_issues', 'history'];
+        const validExpansions = ['comments', 'transitions', 'attachments', 'related_issues', 'history', 'custom_fields'];
         for (const expansion of normalizedArgs.expand) {
             if (typeof expansion !== 'string' || !validExpansions.includes(expansion)) {
                 throw new McpError(ErrorCode.InvalidParams, `Invalid expansion: ${expansion}. Valid expansions are: ${validExpansions.join(', ')}`);
@@ -143,6 +144,106 @@ function getCatalogFieldMeta() {
         description: f.description,
     }));
 }
+/** Compact rendering of a field value for the "Applied" section. */
+function formatAppliedValue(v) {
+    if (v === null || v === undefined)
+        return '(none)';
+    if (Array.isArray(v))
+        return v.map(formatAppliedValue).join(', ') || '(none)';
+    if (typeof v === 'object') {
+        const o = v;
+        if (typeof o.name === 'string')
+            return o.name;
+        if (typeof o.value === 'string')
+            return o.value;
+        if (typeof o.displayName === 'string')
+            return o.displayName;
+        const s = JSON.stringify(v);
+        return s.length > 80 ? s.slice(0, 77) + '…' : s;
+    }
+    const s = String(v);
+    return s.length > 80 ? s.slice(0, 77) + '…' : s;
+}
+/**
+ * Render an "Applied" section confirming what a create/update wrote (ADR-213 §A4, #48).
+ * For custom fields it cross-checks the re-fetched issue and flags silent drops — a write
+ * Jira accepts but discards (field off the Edit screen, hidden by a config, etc.).
+ */
+function renderAppliedFields(args, issue) {
+    const lines = [];
+    if (args.summary !== undefined)
+        lines.push(`- **Summary**: ${formatAppliedValue(issue.summary ?? args.summary)}`);
+    if (args.description !== undefined)
+        lines.push(`- **Description**: ${issue.description ? `updated (${issue.description.length} chars)` : '(cleared)'}`);
+    if (args.priority !== undefined)
+        lines.push(`- **Priority**: ${formatAppliedValue(issue.priority)}`);
+    if (args.assignee !== undefined)
+        lines.push(`- **Assignee**: ${issue.assignee ?? '(unassigned)'}`);
+    if (args.labels !== undefined)
+        lines.push(`- **Labels**: ${(issue.labels && issue.labels.length) ? issue.labels.join(', ') : '(none)'}`);
+    if (args.dueDate !== undefined)
+        lines.push(`- **Due date**: ${issue.dueDate ?? '(cleared)'}`);
+    if (args.parent !== undefined)
+        lines.push(`- **Parent**: ${issue.parent ?? '(removed)'}`);
+    if (args.originalEstimate !== undefined)
+        lines.push(`- **Original estimate**: ${issue.originalEstimate ?? '(cleared)'}`);
+    if (args.remainingEstimate !== undefined)
+        lines.push(`- **Remaining estimate**: ${issue.timeEstimate ?? '(cleared)'}`);
+    if (args.customFields) {
+        const storedByName = new Map((issue.customFieldValues ?? []).map(v => [v.name, v.value]));
+        for (const [requestedName, requestedValue] of Object.entries(args.customFields)) {
+            const fieldId = requestedName.startsWith('customfield_') ? requestedName : fieldDiscovery.resolveNameToId(requestedName);
+            const catalogName = fieldId ? (fieldDiscovery.getFieldById(fieldId)?.name ?? requestedName) : requestedName;
+            const stored = storedByName.has(catalogName) ? storedByName.get(catalogName)
+                : storedByName.has(requestedName) ? storedByName.get(requestedName)
+                    : undefined;
+            const requestedNonEmpty = requestedValue !== undefined && requestedValue !== null && requestedValue !== ''
+                && !(Array.isArray(requestedValue) && requestedValue.length === 0);
+            if (stored !== undefined) {
+                lines.push(`- **${requestedName}**: ${formatAppliedValue(stored)}`);
+            }
+            else if (requestedNonEmpty && fieldId && fieldDiscovery.getFieldById(fieldId)) {
+                lines.push(`- **${requestedName}**: ⚠️ requested \`${formatAppliedValue(requestedValue)}\` but Jira stored no value — the field may be off the Edit screen for this issue type, hidden by a field configuration, or require a dedicated API. It may still be editable inline in the Jira UI.`);
+            }
+            else {
+                lines.push(`- **${requestedName}**: ${formatAppliedValue(requestedValue)} (sent — could not verify)`);
+            }
+        }
+    }
+    return lines.length > 0 ? `\n\n**Applied:**\n${lines.join('\n')}` : '';
+}
+/** The extension route claiming a customFields payload key — checks the key directly (covers a raw
+ *  field name or a Connect field key) and, for a `customfield_*` id, the resolved catalog name. */
+function routeForPayloadKey(key) {
+    const direct = routeForField(key);
+    if (direct)
+        return direct;
+    if (key.startsWith('customfield_')) {
+        const name = fieldDiscovery.getFieldById(key)?.name;
+        if (name)
+            return routeForField(name);
+    }
+    return undefined;
+}
+/** True if any customFields key maps to an extension route with a value-resolving write handler. */
+function customFieldsNeedRouting(customFields) {
+    return Object.keys(customFields).some(k => routeForPayloadKey(k)?.resolveWrite != null);
+}
+/**
+ * Apply extension routes' `resolveWrite` hooks to a resolved customFields map (ADR-213 §B) — e.g.
+ * turn a Tempo account name into the numeric id Jira expects. Throws if a value can't be resolved;
+ * callers re-throw as InvalidParams.
+ */
+async function applyRouteResolutions(jiraClient, customFields, projectKey, issueTypeName) {
+    const out = {};
+    for (const [key, value] of Object.entries(customFields)) {
+        const route = routeForPayloadKey(key);
+        out[key] = route?.resolveWrite
+            ? await route.resolveWrite({ client: jiraClient.v3Client, projectKey, issueTypeName }, key, value)
+            : value;
+    }
+    return out;
+}
 /** Resolve field names to IDs in customFields, returns resolved object */
 function resolveCustomFieldNames(customFields) {
     if (!fieldDiscovery.isReady())
@@ -191,6 +292,11 @@ function getUndescribedFieldNag() {
 function issueGuidance(operation, issueKey) {
     return issueNextSteps(operation, issueKey) + getUndescribedFieldNag();
 }
+/** Extract the project key prefix from a Jira issue key (e.g. `PROJ-123` → `PROJ`).
+ *  Uppercases the result so handlers don't drift from each other on casing. */
+function projectKeyFromIssueKey(issueKey) {
+    return issueKey.split('-')[0].toUpperCase();
+}
 // Handler functions for each operation
 async function handleGetIssue(jiraClient, args) {
     // Parse expansion options
@@ -204,14 +310,21 @@ async function handleGetIssue(jiraClient, args) {
     const includeComments = expansionOptions.comments || false;
     const includeAttachments = expansionOptions.attachments || false;
     const includeHistory = expansionOptions.history || false;
-    const issue = await jiraClient.getIssue(args.issueKey, includeComments, includeAttachments, getCatalogFieldMeta(), includeHistory);
+    const includeAllCustomFields = expansionOptions.custom_fields || false;
+    const issue = await jiraClient.getIssue(args.issueKey, includeComments, includeAttachments, getCatalogFieldMeta(), includeHistory, includeAllCustomFields);
     // Get transitions if requested
     let transitions = undefined;
     if (expansionOptions.transitions) {
         transitions = await jiraClient.getTransitions(args.issueKey);
     }
-    // Render to markdown
-    const markdown = MarkdownRenderer.renderIssue(issue, transitions);
+    // Render to markdown — ADR-214: minimal-by-default custom-field reveal.
+    // `expand: ["custom_fields"]` opts into the full dump; otherwise emit a one-line breadcrumb
+    // pointing at the opt-in and the scoped `jira://custom-fields/{proj}/{type}` resource.
+    const markdown = MarkdownRenderer.renderIssue(issue, transitions, {
+        customFields: includeAllCustomFields ? 'dump' : 'breadcrumb',
+        projectKey: projectKeyFromIssueKey(args.issueKey),
+        issueTypeName: issue.issueType,
+    });
     return {
         content: [
             {
@@ -231,8 +344,9 @@ async function handleMoveIssue(jiraClient, args) {
     await jiraClient.moveIssue(issueKey, args.targetProjectKey, args.targetIssueType);
     bulkOperationGuard.record('move', issueKey);
     // Get the moved issue (it now has a new key in the target project)
-    const movedIssue = await jiraClient.getIssue(issueKey, false, false);
-    const markdown = MarkdownRenderer.renderIssue(movedIssue);
+    const movedIssue = await jiraClient.getIssue(issueKey, false, false, getCatalogFieldMeta());
+    // ADR-214: post-write — `Applied:` is the read-out; drop the custom-fields block entirely.
+    const markdown = MarkdownRenderer.renderIssue(movedIssue, undefined, { customFields: 'none' });
     return {
         content: [
             {
@@ -251,7 +365,9 @@ async function handleDeleteIssue(jiraClient, args) {
     }
     // Get the issue details before deleting for a final snapshot
     const issue = await jiraClient.getIssue(issueKey, false, false);
-    const markdown = MarkdownRenderer.renderIssue(issue);
+    // ADR-214: post-write — the dump is noise on a soon-to-be-deleted issue, and the breadcrumb
+    // would point at expand/resource URIs that no longer apply once the delete lands.
+    const markdown = MarkdownRenderer.renderIssue(issue, undefined, { customFields: 'none' });
     await jiraClient.deleteIssue(issueKey);
     bulkOperationGuard.record('delete', issueKey);
     return {
@@ -264,7 +380,15 @@ async function handleDeleteIssue(jiraClient, args) {
     };
 }
 async function handleCreateIssue(jiraClient, args) {
-    const customFields = args.customFields ? resolveCustomFieldNames(args.customFields) : undefined;
+    let customFields = args.customFields ? resolveCustomFieldNames(args.customFields) : undefined;
+    if (customFields && customFieldsNeedRouting(customFields)) {
+        try {
+            customFields = await applyRouteResolutions(jiraClient, customFields, args.projectKey, args.issueType);
+        }
+        catch (e) {
+            throw new McpError(ErrorCode.InvalidParams, e instanceof Error ? e.message : String(e));
+        }
+    }
     const result = await jiraClient.createIssue({
         projectKey: args.projectKey,
         summary: args.summary,
@@ -278,19 +402,32 @@ async function handleCreateIssue(jiraClient, args) {
         customFields,
     });
     // Get the created issue and render to markdown
-    const createdIssue = await jiraClient.getIssue(result.key, false, false);
-    const markdown = MarkdownRenderer.renderIssue(createdIssue);
+    const createdIssue = await jiraClient.getIssue(result.key, false, false, getCatalogFieldMeta(), false, !!args.customFields);
+    // ADR-214: post-write — `Applied:` is the read-out; drop the custom-fields block entirely.
+    const markdown = MarkdownRenderer.renderIssue(createdIssue, undefined, { customFields: 'none' });
+    const applied = renderAppliedFields(args, createdIssue);
     return {
         content: [
             {
                 type: 'text',
-                text: `# Issue Created\n\n${markdown}${issueGuidance('create', result.key)}`,
+                text: `# Issue Created\n\n${markdown}${applied}${issueGuidance('create', result.key)}`,
             },
         ],
     };
 }
 async function handleUpdateIssue(jiraClient, args) {
-    const customFields = args.customFields ? resolveCustomFieldNames(args.customFields) : undefined;
+    let customFields = args.customFields ? resolveCustomFieldNames(args.customFields) : undefined;
+    if (customFields && customFieldsNeedRouting(customFields)) {
+        // createmeta-based resolution needs the issue's type; the project key is the key prefix.
+        const probe = await jiraClient.getIssue(args.issueKey, false, false);
+        const projectKey = projectKeyFromIssueKey(args.issueKey);
+        try {
+            customFields = await applyRouteResolutions(jiraClient, customFields, projectKey, probe.issueType);
+        }
+        catch (e) {
+            throw new McpError(ErrorCode.InvalidParams, e instanceof Error ? e.message : String(e));
+        }
+    }
     await jiraClient.updateIssue({
         issueKey: args.issueKey,
         summary: args.summary,
@@ -305,13 +442,15 @@ async function handleUpdateIssue(jiraClient, args) {
         customFields,
     });
     // Get the updated issue and render to markdown
-    const updatedIssue = await jiraClient.getIssue(args.issueKey, false, false);
-    const markdown = MarkdownRenderer.renderIssue(updatedIssue);
+    const updatedIssue = await jiraClient.getIssue(args.issueKey, false, false, getCatalogFieldMeta(), false, !!args.customFields);
+    // ADR-214: post-write — `Applied:` is the read-out; drop the custom-fields block entirely.
+    const markdown = MarkdownRenderer.renderIssue(updatedIssue, undefined, { customFields: 'none' });
+    const applied = renderAppliedFields(args, updatedIssue);
     return {
         content: [
             {
                 type: 'text',
-                text: `# Issue Updated\n\n${markdown}${issueGuidance('update', args.issueKey)}`,
+                text: `# Issue Updated\n\n${markdown}${applied}${issueGuidance('update', args.issueKey)}`,
             },
         ],
     };
@@ -319,8 +458,10 @@ async function handleUpdateIssue(jiraClient, args) {
 async function handleTransitionIssue(jiraClient, args) {
     await jiraClient.transitionIssue(args.issueKey, args.transitionId, args.comment);
     // Get the updated issue and render to markdown
-    const updatedIssue = await jiraClient.getIssue(args.issueKey, false, false);
-    const markdown = MarkdownRenderer.renderIssue(updatedIssue);
+    const updatedIssue = await jiraClient.getIssue(args.issueKey, false, false, getCatalogFieldMeta());
+    // ADR-214: post-write — transition has no `Applied:` section, but the custom-fields dump still
+    // adds ~600 tokens of noise unrelated to the state change. Drop it.
+    const markdown = MarkdownRenderer.renderIssue(updatedIssue, undefined, { customFields: 'none' });
     return {
         content: [
             {
@@ -334,7 +475,8 @@ async function handleCommentIssue(jiraClient, args) {
     await jiraClient.addComment(args.issueKey, args.comment);
     // Get the updated issue with comments and render to markdown
     const updatedIssue = await jiraClient.getIssue(args.issueKey, true, false);
-    const markdown = MarkdownRenderer.renderIssue(updatedIssue);
+    // ADR-214: post-write — the new comment is the read-out; custom-field block is noise.
+    const markdown = MarkdownRenderer.renderIssue(updatedIssue, undefined, { customFields: 'none' });
     return {
         content: [
             {
@@ -350,7 +492,8 @@ async function handleLinkIssue(jiraClient, args) {
     await jiraClient.linkIssues(args.issueKey, args.linkedIssueKey, args.linkType, args.comment);
     // Get the updated issue and render to markdown
     const updatedIssue = await jiraClient.getIssue(args.issueKey, false, false);
-    const markdown = MarkdownRenderer.renderIssue(updatedIssue);
+    // ADR-214: post-write — the new link is the read-out; custom-field block is noise.
+    const markdown = MarkdownRenderer.renderIssue(updatedIssue, undefined, { customFields: 'none' });
     return {
         content: [
             {
@@ -372,7 +515,8 @@ async function handleWorklogIssue(jiraClient, args) {
     });
     // Get the updated issue and render to markdown
     const updatedIssue = await jiraClient.getIssue(args.issueKey, false, false);
-    const markdown = MarkdownRenderer.renderIssue(updatedIssue);
+    // ADR-214: post-write — the logged worklog is the read-out; custom-field block is noise.
+    const markdown = MarkdownRenderer.renderIssue(updatedIssue, undefined, { customFields: 'none' });
     return {
         content: [
             {

package/build/handlers/resource-handlers.js

@@ -3,6 +3,7 @@ import { setupToolResourceHandlers } from './tool-resource-handlers.js';
 import { fieldDiscovery } from '../client/field-discovery.js';
 import { categoryLabel } from '../client/field-type-map.js';
 import { searchGoals } from '../client/graphql-goals.js';
+import { allFieldRoutes, moduleStatuses } from '../extensions/index.js';
 /**
  * Sets up resource handlers for the Jira MCP server
  * @param jiraClient The Jira client instance
@@ -49,6 +50,12 @@ export function setupResourceHandlers(jiraClient, graphqlClient) {
                         mimeType: 'text/markdown',
                         description: 'Composition patterns for analyze_jira_issues — how to combine summary counts, groupBy, and JQL for PM dashboards'
                     },
+                    {
+                        uri: 'jira://capabilities',
+                        name: 'Connection Capabilities',
+                        mimeType: 'application/json',
+                        description: 'What this connection can do — custom-field catalog mode, Plans availability, and fields that need special handling (Sprint, Epic Link, Tempo Account, …)'
+                    },
                     // Add tool resources
                     ...toolResources.resources
                 ]
@@ -103,6 +110,9 @@ export function setupResourceHandlers(jiraClient, graphqlClient) {
                 if (uri === 'jira://analysis/recipes') {
                     return getAnalysisRecipes();
                 }
+                if (uri === 'jira://capabilities') {
+                    return await getCapabilities(graphqlClient);
+                }
                 // Handle resource templates
                 const projectMatch = uri.match(/^jira:\/\/projects\/([^/]+)\/overview$/);
                 if (projectMatch) {
@@ -321,12 +331,56 @@ async function getBoardOverview(jiraClient, boardId) {
         throw error;
     }
 }
+/** In unscored mode the catalog can be large; the resource truncates past this many fields. */
+const MAX_UNSCORED_RESOURCE_FIELDS = 200;
 /**
- * Gets the master custom fields catalog
+ * Gets the master custom fields catalog (ADR-201, ADR-213 §A1).
+ *
+ * Three states (see {@link CatalogMode}):
+ * - `scored` — curated, ranked catalog with descriptions, screen counts, and recency
+ * - `unscored` — admin field API returned 403; flat id/name/type list of every custom field
+ *   (no descriptions — the basic field API doesn't carry them), truncated for size with a
+ *   pointer to the project-scoped resource for richer per-field detail
+ * - `unavailable` / `loading` — no catalog yet
  */
 function getCustomFieldsCatalog() {
+    const state = fieldDiscovery.getState();
     const catalog = fieldDiscovery.getCatalog();
     const stats = fieldDiscovery.getStats();
+    const error = fieldDiscovery.getError();
+    if (state === 'loading') {
+        return jsonResource('jira://custom-fields', { status: 'loading', fields: [], count: 0 });
+    }
+    if (state === 'unavailable') {
+        return jsonResource('jira://custom-fields', {
+            status: 'unavailable',
+            fields: [],
+            count: 0,
+            error: error ?? 'Custom field discovery failed.',
+        });
+    }
+    if (state === 'unscored') {
+        const total = catalog.length;
+        const truncated = total > MAX_UNSCORED_RESOURCE_FIELDS;
+        const fields = (truncated ? catalog.slice(0, MAX_UNSCORED_RESOURCE_FIELDS) : catalog).map(f => ({
+            id: f.id,
+            name: f.name,
+            type: categoryLabel(f.category),
+            writable: f.writable,
+        }));
+        return jsonResource('jira://custom-fields', {
+            status: 'ready',
+            mode: 'unscored',
+            fields,
+            count: total,
+            ...(truncated ? { truncated: true, shown: fields.length } : {}),
+            note: (error ? error + ' ' : '') +
+                'Fields are not ranked by screen usage or recency, and descriptions are not available in this mode. ' +
+                'For descriptions and allowed values on the fields relevant to a specific project and issue type, read ' +
+                'jira://custom-fields/{projectKey}/{issueType}.',
+        });
+    }
+    // scored
     const fields = catalog.map(f => ({
         id: f.id,
         name: f.name,
@@ -338,7 +392,8 @@ function getCustomFieldsCatalog() {
         score: f.score,
     }));
     const response = {
-        status: fieldDiscovery.isReady() ? 'ready' : 'loading',
+        status: 'ready',
+        mode: 'scored',
         fields,
         count: fields.length,
     };
@@ -353,17 +408,52 @@ function getCustomFieldsCatalog() {
             undescribedRatio: Math.round(stats.undescribedRatio * 100),
         };
     }
-    if (fieldDiscovery.getError()) {
-        response.error = fieldDiscovery.getError();
-    }
+    return jsonResource('jira://custom-fields', response);
+}
+/** Wrap an object as a single JSON resource content entry. */
+function jsonResource(uri, body) {
     return {
         contents: [{
-                uri: 'jira://custom-fields',
+                uri,
                 mimeType: 'application/json',
-                text: JSON.stringify(response, null, 2),
+                text: JSON.stringify(body, null, 2),
             }],
     };
 }
+/**
+ * What this connection can actually do (ADR-213 §B): the custom-field catalog mode, whether the
+ * Plans/GraphQL surface is reachable, the loaded extension modules and their detection state, and
+ * the field routes those modules contribute (fields that need handling beyond a plain customFields
+ * write — Sprint, Epic Link, Tempo Account, …). `resolves: true` on a route means this server can
+ * transform the value for you (e.g. an account name → id); otherwise the route's guidance names the
+ * path to use.
+ */
+async function getCapabilities(graphqlClient) {
+    const catalogState = fieldDiscovery.getState();
+    const catalog = fieldDiscovery.getCatalog();
+    const catalogError = fieldDiscovery.getError();
+    const fieldRouting = allFieldRoutes().map(r => ({
+        names: r.names,
+        resolves: !!r.resolveWrite,
+        reason: r.unhandled.reason,
+        guidance: r.unhandled.message,
+        ...(r.unhandled.suggestedTool ? { suggestedTool: r.unhandled.suggestedTool } : {}),
+    }));
+    return jsonResource('jira://capabilities', {
+        customFieldCatalog: {
+            mode: catalogState,
+            count: catalog.length,
+            ...(catalogState !== 'scored' && catalogError ? { note: catalogError } : {}),
+        },
+        plans: { available: graphqlClient != null },
+        extensions: await moduleStatuses(),
+        fieldRouting,
+        note: 'Extension modules + capability-aware field routing (ADR-213 §B). Each fieldRouting entry ' +
+            'describes a field that needs handling beyond a plain customFields write; `resolves: true` ' +
+            'means this server transforms the value for you (pass a name or an id), otherwise `guidance` ' +
+            'names the right path. Read jira://custom-fields for the field catalog.',
+    });
+}
 /**
  * Gets custom fields available for a specific project + issue type (context intersection)
  */
@@ -385,7 +475,7 @@ async function getContextCustomFields(jiraClient, projectKey, issueType) {
                     issueType,
                     fields: result,
                     count: result.length,
-                    catalogReady: fieldDiscovery.isReady(),
+                    catalogMode: fieldDiscovery.getState(),
                 }, null, 2),
             }],
     };

package/build/index.js

@@ -21,6 +21,7 @@ import { handleWorkspaceRequest } from './handlers/workspace-handler.js';
 import { promptDefinitions } from './prompts/prompt-definitions.js';
 import { getPrompt } from './prompts/prompt-messages.js';
 import { toolSchemas } from './schemas/tool-schemas.js';
+import { classifyFieldErrors } from './utils/field-error-classification.js';
 import { normalizeArgs } from './utils/normalize-args.js';
 // Jira credentials from environment variables
 const JIRA_EMAIL = process.env.JIRA_EMAIL;
@@ -248,6 +249,11 @@ class JiraServer {
                         for (const [field, msg] of Object.entries(fieldErrors)) {
                             lines.push(`- \`${field}\`: ${msg}`);
                         }
+                        // Distinguish the failure modes Jira's message conflates (ADR-213 §A5, #49 / #52c).
+                        const guidance = classifyFieldErrors(fieldErrors);
+                        if (guidance.length > 0) {
+                            lines.push('', '**What to do:**', ...guidance);
+                        }
                     }
                     // On create failures, invalidate cache and append required fields guidance
                     const reqArgs = request.params.arguments;

package/build/mcp/markdown-renderer.js

@@ -89,13 +89,10 @@ function stripHtml(html) {
         .replace(/\s+/g, ' ')
         .trim();
 }
-// ============================================================================
-// Issue Rendering
-// ============================================================================
 /**
  * Render a single issue as markdown
  */
-export function renderIssue(issue, transitions) {
+export function renderIssue(issue, transitions, opts = {}) {
     const lines = [];
     lines.push(`# ${issue.key}: ${issue.summary}`);
     lines.push('');
@@ -170,17 +167,33 @@ export function renderIssue(issue, transitions) {
             lines.push(`[${startIdx + i}/${issue.comments.length}] ${comment.author} (${formatDate(comment.created)}): ${truncate(preview, 200)}`);
         }
     }
-    // Custom fields (from catalog discovery)
-    if (issue.customFieldValues && issue.customFieldValues.length > 0) {
+    // Custom fields — progressive reveal (ADR-214). Default is a breadcrumb pointing at the
+    // opt-in expand and the scoped resource; the full dump is gated behind `customFields: 'dump'`.
+    // Zero populated → silent in every mode.
+    const customFieldsMode = opts.customFields ?? 'breadcrumb';
+    const cfs = issue.customFieldValues ?? [];
+    const populatedCount = cfs.length;
+    if (customFieldsMode === 'dump' && populatedCount > 0) {
         lines.push('');
         lines.push('Custom Fields:');
-        for (const cf of issue.customFieldValues) {
+        for (const cf of cfs) {
             const displayValue = Array.isArray(cf.value)
                 ? cf.value.join(', ')
                 : String(cf.value);
             lines.push(`${cf.name} (${cf.type}): ${displayValue}`);
         }
     }
+    else if (customFieldsMode === 'breadcrumb' && populatedCount > 0) {
+        lines.push('');
+        // Issue-type names can contain spaces ("User Story", "Service Request") — the catalog
+        // resource emitter encodes the type and the resolver decodes it (resource-handlers.ts:148, 533),
+        // so the breadcrumb URI has to encode too or the link round-trips wrong.
+        const uri = opts.projectKey && opts.issueTypeName
+            ? ` For what's settable on this issue type: read \`jira://custom-fields/${opts.projectKey}/${encodeURIComponent(opts.issueTypeName)}\`.`
+            : '';
+        lines.push(`📋 ${populatedCount} populated custom field${populatedCount === 1 ? '' : 's'} not shown. ` +
+            `To view: \`expand: ["custom_fields"]\`.${uri}`);
+    }
     // Status history (if requested via expand: ["history"])
     if (issue.statusHistory && issue.statusHistory.length > 0) {
         lines.push('');

package/build/schemas/tool-schemas.js

@@ -142,7 +142,7 @@ export const toolSchemas = {
     },
     manage_jira_issue: {
         name: 'manage_jira_issue',
-        description: 'Get, create, update, delete, move, transition, comment on, link, log work on, or explore hierarchy of Jira issues',
+        description: 'Get, create, update, delete, move, transition, comment on, link, log work on, or explore hierarchy of Jira issues. For custom-field writes, consult `jira://capabilities` (field routing) and `jira://custom-fields/{projectKey}/{issueType}` (what is settable here) — some fields need dedicated tools and others auto-resolve names to ids.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -186,7 +186,7 @@ export const toolSchemas = {
                 },
                 customFields: {
                     type: 'object',
-                    description: 'Custom field values as key-value pairs.',
+                    description: 'Custom field values as { name | id : value }. Names auto-resolve to customfield_NNNNN. Read `jira://capabilities` for the field-routing table (which fields need a dedicated tool or have value-resolution) and `jira://custom-fields/{projectKey}/{issueType}` for what is settable on a given screen, with types and clearing semantics.',
                 },
                 dueDate: {
                     type: ['string', 'null'],
@@ -265,9 +265,9 @@ export const toolSchemas = {
                     type: 'array',
                     items: {
                         type: 'string',
-                        enum: ['comments', 'transitions', 'attachments', 'related_issues', 'history'],
+                        enum: ['comments', 'transitions', 'attachments', 'related_issues', 'history', 'custom_fields'],
                     },
-                    description: 'Additional fields to include in the response.',
+                    description: 'Additional fields to include in the response. Populated custom fields are NOT shown by default — `get` emits a one-line breadcrumb with the count and the opt-in. Pass "custom_fields" to render the full populated dump. For what is *settable* on this issue type (with usage hints), read the scoped resource `jira://custom-fields/{projectKey}/{issueType}` instead.',
                 },
             },
             required: ['operation'],

package/build/utils/field-error-classification.js

@@ -0,0 +1,65 @@
+/**
+ * Field-rejection error classification (ADR-213 §A5, issues #49 and #52c).
+ *
+ * Jira rejects a `customFields` write with one opaque message —
+ *   "Field 'X' cannot be set. It is not on the appropriate screen, or unknown."
+ * — that conflates several failure modes, each needing a different recovery. Given Jira's
+ * field-error map (keyed by field id or name), this returns extra guidance lines that pull
+ * those modes apart:
+ *
+ *   - field has a dedicated path (Sprint, Epic Link, Parent, Rank) → point at the right tool/param
+ *   - field exists in the catalog but isn't writable here → "editable inline in the UI, or via the
+ *     owning app — not reachable through the standard edit endpoint"
+ *   - field isn't in the catalog → "not a field this instance exposes — see jira://custom-fields"
+ *   - catalog unavailable → say so; the name may be right but can't be verified here
+ */
+import { fieldDiscovery } from '../client/field-discovery.js';
+import { routeForField } from '../extensions/index.js';
+/** Looks like a Connect/Forge app field key (e.g. `io.tempo.jira__account`) rather than a
+ *  `customfield_NNNNN` id or a plain field name — Jira sometimes reports field errors this way. */
+function looksLikeAppFieldKey(key) {
+    return !key.startsWith('customfield_') && (key.includes('__') || /^[a-z][\w-]*(\.[\w-]+){2,}/i.test(key));
+}
+export function classifyFieldErrors(fieldErrors) {
+    const out = [];
+    const catalogState = fieldDiscovery.getState();
+    for (const fieldKey of Object.keys(fieldErrors)) {
+        const catalogEntry = fieldKey.startsWith('customfield_')
+            ? fieldDiscovery.getFieldById(fieldKey)
+            : undefined;
+        const humanName = catalogEntry?.name ?? fieldKey;
+        const resolvedId = fieldKey.startsWith('customfield_')
+            ? fieldKey
+            : fieldDiscovery.resolveNameToId(fieldKey);
+        const isKnownField = !!catalogEntry || !!resolvedId;
+        const route = routeForField(fieldKey) ?? routeForField(humanName);
+        if (route) {
+            out.push(`  → \`${humanName}\`: ${route.unhandled.message}`);
+            continue;
+        }
+        if (isKnownField) {
+            out.push(`  → \`${humanName}\` exists on this instance but the write was rejected — it may be off ` +
+                `the Edit screen for this issue type, hidden by a field configuration, or an app-managed ` +
+                `field that wants a different value format (e.g. a numeric id rather than a name). It may ` +
+                `still be editable inline in the Jira UI.`);
+            continue;
+        }
+        if (looksLikeAppFieldKey(fieldKey)) {
+            out.push(`  → \`${fieldKey}\` is a field registered by a Connect/Forge app — the write was rejected ` +
+                `(see the message above). App-managed fields often expect a specific value format ` +
+                `(e.g. a numeric account/option id rather than a name) or must be set through the app's own ` +
+                `interface; setting it inline in the Jira UI usually works.`);
+            continue;
+        }
+        if (catalogState === 'unavailable') {
+            out.push(`  → \`${fieldKey}\`: couldn't verify this field name — the custom-field catalog is ` +
+                `unavailable (the admin field API returned 403 and the basic fallback also failed). The ` +
+                `name may be correct but can't be checked here.`);
+            continue;
+        }
+        out.push(`  → \`${fieldKey}\` isn't a custom field this instance exposes (checked the ${catalogState} ` +
+            `catalog). Read jira://custom-fields for available names, or ` +
+            `jira://custom-fields/{projectKey}/{issueType} for the fields on a specific issue type.`);
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaronsb/jira-cloud-mcp",
-  "version": "0.10.0",
+  "version": "0.11.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",