@aaronsb/jira-cloud-mcp 0.10.0 → 0.11.0

package/build/client/field-discovery.js

@@ -27,13 +27,17 @@ export class FieldDiscovery {
     idToField = new Map();
     wellKnown = new Map(); // logical name → field ID
     stats = null;
-    ready = false;
+    mode = 'loading';
     error = null;
-    /** Whether the catalog has been built */
+    /** Whether a usable catalog exists (scored or unscored). */
     isReady() {
-        return this.ready;
+        return this.mode === 'scored' || this.mode === 'unscored';
     }
-    /** Error message if startup discovery failed */
+    /** Granular catalog state — see {@link CatalogMode}. */
+    getState() {
+        return this.mode;
+    }
+    /** Error message if discovery failed (or degraded). */
     getError() {
         return this.error;
     }
@@ -67,7 +71,7 @@ export class FieldDiscovery {
      * Falls back to the full writable catalog if the createmeta call fails.
      */
     async getContextFields(client, projectKey, issueTypeName) {
-        if (!this.ready || this.catalog.length === 0) {
+        if (!this.isReady() || this.catalog.length === 0) {
             return [];
         }
         try {
@@ -190,11 +194,70 @@ export class FieldDiscovery {
     }
     /** Clear required fields cache for a project (on 400 errors, cache may be stale). */
     invalidateRequiredFields(projectKey) {
+        const prefix = projectKey.toLowerCase() + ':';
         for (const key of this.requiredFieldsCache.keys()) {
-            if (key.startsWith(projectKey.toLowerCase() + ':')) {
+            if (key.startsWith(prefix))
                 this.requiredFieldsCache.delete(key);
+        }
+        for (const key of this.fieldOptionsCache.keys()) {
+            if (key.startsWith(prefix))
+                this.fieldOptionsCache.delete(key);
+        }
+    }
+    // ── Field Options (createmeta allowedValues) ─────────────────────────
+    fieldOptionsCache = new Map();
+    /**
+     * Enumerable allowed values (`{id, value}`) for a field on a project + issue type, read from
+     * createmeta. Returns `[]` if the field isn't on that issue type's create screen or has no
+     * enumerable options. Cached per project/issue-type — one createmeta walk covers every field.
+     * Used to resolve a human-friendly option name to the id the issue-edit endpoint expects
+     * (e.g. the Tempo Account field — see ADR-213 §B / field-routing.ts).
+     */
+    async getFieldAllowedValues(client, projectKey, issueTypeName, fieldId) {
+        const cacheKey = `${projectKey}:${issueTypeName}`.toLowerCase();
+        let perField = this.fieldOptionsCache.get(cacheKey);
+        if (!perField) {
+            perField = new Map();
+            try {
+                const issueTypes = await this.getIssueTypes(client, projectKey);
+                const matchingType = issueTypes.find(t => t.name.toLowerCase() === issueTypeName.toLowerCase());
+                if (matchingType) {
+                    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.fieldId || !Array.isArray(f.allowedValues) || f.allowedValues.length === 0)
+                                continue;
+                            const opts = [];
+                            for (const v of f.allowedValues) {
+                                const id = v?.id ?? v?.value;
+                                const value = v?.value ?? v?.name ?? (typeof v === 'string' ? v : undefined);
+                                if (id !== undefined && value !== undefined)
+                                    opts.push({ id, value: String(value) });
+                            }
+                            if (opts.length > 0)
+                                perField.set(f.fieldId, opts);
+                        }
+                        if (fields.length < maxResults)
+                            hasMore = false;
+                        startAt += fields.length;
+                    }
+                }
+            }
+            catch (err) {
+                console.error(`[field-discovery] Field options fetch failed for ${projectKey}/${issueTypeName}: ${err instanceof Error ? err.message : err}`);
             }
+            this.fieldOptionsCache.set(cacheKey, perField);
         }
+        return perField.get(fieldId) ?? [];
     }
     /**
      * Start discovery in the background. Does not block.
@@ -208,13 +271,41 @@ export class FieldDiscovery {
     }
     /**
      * Build the master catalog from Jira's field metadata.
+     *
+     * Tries the admin-only paginated field-search API first (full metadata → `scored` mode).
+     * On any failure (typically a 403 for non-admin users — see issue #43) falls back to the
+     * basic field list, which any authenticated user can read, and builds an `unscored` catalog.
+     * If even that fails, the catalog stays empty (`unavailable`) and custom fields pass through
+     * unfiltered, as before.
      */
     async discover(client) {
+        console.error('[field-discovery] Starting custom field discovery...');
+        let rawFields;
+        let degraded = false;
+        try {
+            rawFields = await this.fetchAllCustomFields(client);
+            console.error(`[field-discovery] Fetched ${rawFields.length} custom fields (full metadata)`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // Keep the underlying cause around — it explains the degraded mode in the resource.
+            this.error = `The admin field-search API is unavailable (${msg}) — likely because this user lacks the Administer Jira global permission. Running custom-field discovery in unscored mode.`;
+            console.error(`[field-discovery] Admin field-search API unavailable (${msg}); falling back to the basic field list`);
+            try {
+                rawFields = await this.fetchCustomFieldsBasic(client);
+                degraded = true;
+                console.error(`[field-discovery] Fetched ${rawFields.length} custom fields (basic list — no screen/recency metadata)`);
+            }
+            catch (err2) {
+                const msg2 = err2 instanceof Error ? err2.message : String(err2);
+                this.error = `Custom field discovery failed. Admin field-search API: ${msg}. Basic field list: ${msg2}.`;
+                this.mode = 'unavailable';
+                console.error(`[field-discovery] ${this.error}`);
+                return;
+            }
+        }
         try {
-            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)
+            // Detect well-known locked fields by schema custom type (works in both modes)
             for (const field of rawFields) {
                 const logicalName = WELL_KNOWN_FIELDS[field.schemaCustom];
                 if (logicalName) {
@@ -222,31 +313,48 @@ export class FieldDiscovery {
                     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);
-            const finalCatalog = this.applyCutoff(scored);
-            this.catalog = finalCatalog;
-            this.stats = { ...stats, catalogSize: finalCatalog.length };
-            this.buildIndexes();
-            this.ready = true;
-            console.error(`[field-discovery] Catalog ready: ${finalCatalog.length} fields`);
-            if (stats.undescribedRatio > 0.5) {
-                console.error(`[field-discovery] WARNING: ${Math.round(stats.undescribedRatio * 100)}% of on-screen custom fields lack descriptions. ` +
-                    `Encourage your Jira admin to add descriptions for better AI support.`);
+            if (degraded) {
+                this.catalog = this.buildUnscoredCatalog(rawFields);
+                this.stats = {
+                    totalCustomFields: rawFields.length,
+                    excludedNoDescription: 0,
+                    excludedNoScreens: 0,
+                    excludedUnsupportedType: 0,
+                    excludedLocked: 0,
+                    catalogSize: this.catalog.length,
+                    undescribedRatio: 0,
+                };
+                this.buildIndexes();
+                this.mode = 'unscored';
+                console.error(`[field-discovery] Catalog ready (unscored): ${this.catalog.length} fields`);
+            }
+            else {
+                const { qualified, stats } = this.filterAndClassify(rawFields);
+                console.error(`[field-discovery] ${qualified.length} fields passed filters`);
+                const scored = this.scoreFields(qualified);
+                const finalCatalog = this.applyCutoff(scored);
+                this.catalog = finalCatalog;
+                this.stats = { ...stats, catalogSize: finalCatalog.length };
+                this.buildIndexes();
+                this.mode = 'scored';
+                console.error(`[field-discovery] Catalog ready (scored): ${finalCatalog.length} fields`);
+                if (stats.undescribedRatio > 0.5) {
+                    console.error(`[field-discovery] WARNING: ${Math.round(stats.undescribedRatio * 100)}% of on-screen custom fields lack descriptions. ` +
+                        `Encourage your Jira admin to add descriptions for better AI support.`);
+                }
+                this.logExclusions(rawFields, finalCatalog);
             }
-            // Log excluded fields at debug level
-            this.logExclusions(rawFields, finalCatalog);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             this.error = msg;
-            console.error(`[field-discovery] Discovery failed: ${msg}`);
-            // Don't re-throw — catalog stays empty, fields pass through unfiltered
+            this.mode = 'unavailable';
+            console.error(`[field-discovery] Catalog build failed: ${msg}`);
         }
     }
     /**
-     * Fetch all custom fields with metadata via paginated API.
+     * Fetch all custom fields with full metadata via the admin paginated field-search API.
+     * Requires the Administer Jira global permission — throws (typically 403) otherwise.
      */
     async fetchAllCustomFields(client) {
         const allFields = [];
@@ -282,6 +390,53 @@ export class FieldDiscovery {
         }
         return allFields;
     }
+    /**
+     * Fetch custom fields via the basic field list (`GET /rest/api/3/field`), which any
+     * authenticated user can read. Carries id / name / schema / `custom` flag but **not**
+     * `description`, `screensCount`, `lastUsed`, or `isLocked` — so the resulting catalog is
+     * `unscored` (no ranking, no cutoff). Used as the non-admin fallback for issue #43.
+     */
+    async fetchCustomFieldsBasic(client) {
+        const all = await client.issueFields.getFields();
+        return (all || [])
+            .filter(f => f?.id && (f.custom === true || f.id.startsWith('customfield_')))
+            .map(f => ({
+            id: f.id,
+            name: f.name || f.id,
+            description: '',
+            isLocked: false,
+            screensCount: 0,
+            lastUsed: null,
+            lastUsedType: 'NO_INFORMATION',
+            schemaType: f.schema?.type || '',
+            schemaCustom: f.schema?.custom || '',
+            schemaItems: f.schema?.items || '',
+        }));
+    }
+    /**
+     * Build an unscored catalog: every custom field, no exclusions, no ranking, sorted by name.
+     * Type classification still runs (drives the `writable` flag and `category`), but unsupported
+     * types are kept rather than dropped — name→ID resolution should cover every field.
+     */
+    buildUnscoredCatalog(rawFields) {
+        return rawFields
+            .map(f => {
+            const typeInfo = classifyFieldType(f.schemaType, f.schemaCustom || undefined, f.schemaItems || undefined);
+            return {
+                id: f.id,
+                name: f.name,
+                description: f.description,
+                category: typeInfo.category,
+                writable: typeInfo.writable,
+                jsonSchema: typeInfo.jsonSchema,
+                schemaCustom: f.schemaCustom,
+                screensCount: 0,
+                lastUsed: null,
+                score: 0,
+            };
+        })
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
     /**
      * Apply qualification filters (ADR-201 §Qualification Criteria).
      */
@@ -387,6 +542,7 @@ export class FieldDiscovery {
             category: f.typeInfo.category,
             writable: f.typeInfo.writable,
             jsonSchema: f.typeInfo.jsonSchema,
+            schemaCustom: f.schemaCustom,
             screensCount: f.screensCount,
             lastUsed: f.lastUsed,
             score: Math.round(f.score * 100) / 100,

package/build/client/jira-client.js

@@ -1,5 +1,10 @@
 import { Version3Client, AgileClient } from 'jira.js';
 import { TextProcessor } from '../utils/text-processing.js';
+/**
+ * Above this many catalog custom fields, `getIssue` requests `*navigable` instead of
+ * enumerating every field ID — keeps the request small in unscored-catalog mode (ADR-213 §A2).
+ */
+const CUSTOM_FIELD_ID_REQUEST_LIMIT = 50;
 export class JiraClient {
     client;
     agileClient;
@@ -160,16 +165,25 @@ export class JiraClient {
             people: people.length > 0 ? people : undefined,
         };
     }
-    async getIssue(issueKey, includeComments = false, includeAttachments = false, customFieldMeta, includeHistory = false) {
+    async getIssue(issueKey, includeComments = false, includeAttachments = false, customFieldMeta, includeHistory = false, includeAllCustomFields = false) {
         const fields = [...this.issueFields];
         if (includeAttachments) {
             fields.push('attachment');
         }
-        // Include discovered custom field IDs in the fetch
+        // Decide how to fetch custom fields:
+        // - small catalog (scored mode, ≤ ~30 fields) → request the catalog's IDs explicitly
+        // - large catalog (unscored mode) or explicit `custom_fields` expand → request all navigable
+        //   fields once (`*navigable`) and label whatever populated custom fields come back
+        const useNavigableWildcard = !!customFieldMeta && (includeAllCustomFields || customFieldMeta.length > CUSTOM_FIELD_ID_REQUEST_LIMIT);
         if (customFieldMeta) {
-            for (const cf of customFieldMeta) {
-                if (!fields.includes(cf.id)) {
-                    fields.push(cf.id);
+            if (useNavigableWildcard) {
+                fields.push('*navigable');
+            }
+            else {
+                for (const cf of customFieldMeta) {
+                    if (!fields.includes(cf.id)) {
+                        fields.push(cf.id);
+                    }
                 }
             }
         }
@@ -199,21 +213,41 @@ export class JiraClient {
             })))
                 .sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
         }
-        // Extract custom field values using catalog metadata
+        // Extract custom field values, labeled via the catalog metadata.
         if (customFieldMeta) {
             const rawFields = issue.fields;
+            const metaById = new Map(customFieldMeta.map(m => [m.id, m]));
             const customValues = [];
-            for (const cf of customFieldMeta) {
-                const value = rawFields[cf.id];
-                if (value !== undefined && value !== null) {
+            const isPopulated = (v) => v !== undefined && v !== null
+                && !(Array.isArray(v) && v.length === 0)
+                && !(typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0);
+            if (useNavigableWildcard) {
+                // The response carries every navigable custom field; surface the populated ones.
+                for (const [key, value] of Object.entries(rawFields)) {
+                    if (!/^customfield_\d+$/.test(key) || !isPopulated(value))
+                        continue;
+                    const meta = metaById.get(key);
                     customValues.push({
-                        name: cf.name,
+                        name: meta?.name ?? key,
                         value: this.formatCustomFieldValue(value),
-                        type: cf.type,
-                        description: cf.description,
+                        type: meta?.type ?? 'unknown',
+                        description: meta?.description ?? '',
                     });
                 }
             }
+            else {
+                for (const cf of customFieldMeta) {
+                    const value = rawFields[cf.id];
+                    if (isPopulated(value)) {
+                        customValues.push({
+                            name: cf.name,
+                            value: this.formatCustomFieldValue(value),
+                            type: cf.type,
+                            description: cf.description,
+                        });
+                    }
+                }
+            }
             if (customValues.length > 0) {
                 issueDetails.customFieldValues = customValues;
             }
@@ -593,6 +627,27 @@ export class JiraClient {
             throw error;
         }
     }
+    /**
+     * Validate a JQL query's structure and field references via POST /rest/api/3/jql/parse
+     * (ADR-213 §A3, #44). The enhanced search endpoint silently returns zero results for an
+     * unknown field, so this is the only way to distinguish "field doesn't exist" from "field
+     * is empty across all issues". Returns the list of syntax/validation errors — empty if valid.
+     * If the parse endpoint itself fails, returns [] (don't block the search on a flaky validator).
+     */
+    async parseJqlErrors(jql) {
+        try {
+            const cleanJql = jql.replace(/\\"/g, '"');
+            const result = await this.client.jql.parseJqlQueries({
+                queries: [cleanJql],
+                validation: 'warn',
+            });
+            return result?.queries?.[0]?.errors ?? [];
+        }
+        catch (err) {
+            console.error(`[jql-parse] validation skipped: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+    }
     async searchIssues(jql, startAt = 0, maxResults = 25) {
         try {
             // Remove escaped quotes from JQL

package/build/docs/tool-documentation.js

@@ -33,7 +33,7 @@ function generateIssueToolDocumentation(schema) {
                 description: "Retrieves issue details",
                 required_parameters: ["issueKey"],
                 optional_parameters: ["expand"],
-                expand_options: ["comments", "transitions", "attachments", "related_issues", "history"],
+                expand_options: ["comments", "transitions", "attachments", "related_issues", "history", "custom_fields"],
                 examples: [
                     {
                         description: "Get basic issue details",
@@ -162,11 +162,14 @@ function generateIssueToolDocumentation(schema) {
             }
         ],
         custom_fields: {
-            description: "Custom fields are discovered automatically at startup. Use field names (not IDs) in the customFields parameter.",
-            discovery: "Read jira://custom-fields to see the master catalog of discovered fields with types and descriptions.",
-            context: "Read jira://custom-fields/{projectKey}/{issueType} to see fields valid for a specific project and issue type.",
-            name_resolution: "Field names are resolved to IDs automatically — use human-readable names like 'Story Points', not 'customfield_10035'.",
-            requirement: "Only fields with descriptions in Jira are discoverable. Fields without descriptions must use raw field IDs.",
+            description: "Custom fields are discovered automatically. Pass values in customFields as { name | customfield_NNNNN : value } — names are preferred.",
+            discovery: "Read jira://custom-fields for the master catalog of discovered fields with types and descriptions.",
+            context: "Read jira://custom-fields/{projectKey}/{issueType} for fields settable on a specific screen, with jsonSchema hints.",
+            capabilities: "Read jira://capabilities for the fieldRouting table — flags fields that need a dedicated tool or special handling. Examples: Sprint goes through manage_jira_sprint (operation: manage_issues); Epic Link / Parent Link / Parent go through the `parent` parameter on update, not customFields; Rank (backlog order) is not settable through this server; Tempo Account auto-resolves a name or numeric id via the project's account options.",
+            name_resolution: "Field names resolve to ids automatically — prefer 'Story Points' over 'customfield_10035'. Catalog lookup is case-insensitive.",
+            clear_semantics: "Pass null to clear a field. Empty string ('') may collide with name-resolution on extension-routed fields (e.g., Tempo Account: '' matches all account names ambiguously) — null is the safe path.",
+            view_after_write: "Populated custom fields are NOT rendered on `get` by default — a one-line breadcrumb names the count and the opt-in. Pass `expand: [\"custom_fields\"]` to render the full block. Post-write renders drop the block entirely; the `Applied:` section is the read-out.",
+            requirement: "Only fields with descriptions in Jira are discoverable. Fields without descriptions must be referenced by raw customfield_NNNNN id.",
         },
         related_resources: [
             { name: "Project Overview", uri: "jira://projects/{projectKey}/overview", description: "Get detailed information about a project" },

package/build/extensions/atlassian-special-fields.js

@@ -0,0 +1,42 @@
+/**
+ * Atlassian special-field handling (ADR-213 §B).
+ *
+ * Sprint, Epic Link / Parent Link / Parent, and Rank are Jira-native fields that can't be set
+ * through a plain `customFields` write — each has a dedicated path. This module owns the routes that
+ * say so; `classifyFieldErrors` surfaces the guidance when Jira rejects such a write. There's no
+ * `detect()` — these fields are intrinsic to Jira, always "present".
+ */
+export const atlassianSpecialFields = {
+    id: 'atlassian-special-fields',
+    displayName: 'Atlassian special fields (Sprint, Epic Link, Rank)',
+    routes: [
+        {
+            names: ['sprint'],
+            unhandled: {
+                reason: 'sprint_requires_agile_api',
+                message: 'The Sprint field is managed through the Agile API, not customFields. Use ' +
+                    'manage_jira_sprint with operation "manage_issues" to add the issue to a sprint (find the ' +
+                    'sprint id via manage_jira_sprint list / list_boards).',
+                suggestedTool: 'manage_jira_sprint',
+            },
+        },
+        {
+            names: ['epic link', 'parent link', 'parent'],
+            unhandled: {
+                reason: 'parent_via_parent_param',
+                message: 'Epic Link / Parent Link / Parent are set via the "parent" parameter on ' +
+                    'manage_jira_issue update (pass the parent issue key) — not customFields. Use ' +
+                    'manage_jira_issue hierarchy to see the current parent/child structure.',
+                suggestedTool: 'manage_jira_issue',
+            },
+        },
+        {
+            names: ['rank'],
+            unhandled: {
+                reason: 'rank_not_exposed',
+                message: 'Issue Rank (backlog ordering) is not settable through this server — reorder issues on a ' +
+                    'board in the Jira UI.',
+            },
+        },
+    ],
+};

package/build/extensions/index.js

@@ -0,0 +1,52 @@
+/**
+ * Extension-module registry (ADR-213 §B).
+ *
+ * `MODULES` is the *explicit, hand-curated* list of extension modules — there is no auto-discovery
+ * or glob. Adding a module = importing it here and adding it to the list = a reviewed edit, justified
+ * by a common user flow. This is the composition point: the rest of the server asks here for the
+ * field routes (issue create/update + error classification) and for the per-module status
+ * (jira://capabilities).
+ */
+import { atlassianSpecialFields } from './atlassian-special-fields.js';
+import { tempo } from './tempo.js';
+const MODULES = [atlassianSpecialFields, tempo];
+export function allModules() {
+    return MODULES;
+}
+/** Every field route contributed by every module. */
+export function allFieldRoutes() {
+    return MODULES.flatMap(m => m.routes);
+}
+/** Find the route claiming a given field name, catalog name, or Connect field key, if any. */
+export function routeForField(nameOrKey) {
+    const lower = nameOrKey.toLowerCase();
+    for (const m of MODULES) {
+        const r = m.routes.find(rt => rt.names.some(n => n.toLowerCase() === lower));
+        if (r)
+            return r;
+    }
+    return undefined;
+}
+/**
+ * Per-module status for jira://capabilities. Runs each module's `detect()` (cheap in-memory checks
+ * against the field catalog) fresh each call — fail-open. Not cached: detection only reads state
+ * that may still be warming up at startup, and re-running it is microseconds.
+ */
+export async function moduleStatuses() {
+    const out = [];
+    for (const m of MODULES) {
+        const fields = m.routes.flatMap(r => r.names);
+        if (!m.detect) {
+            out.push({ id: m.id, displayName: m.displayName, fields });
+            continue;
+        }
+        try {
+            const d = await m.detect();
+            out.push({ id: m.id, displayName: m.displayName, present: d.present, notes: d.notes, fields });
+        }
+        catch {
+            out.push({ id: m.id, displayName: m.displayName, notes: 'detection skipped (error)', fields });
+        }
+    }
+    return out;
+}

package/build/extensions/tempo.js

@@ -0,0 +1,64 @@
+/**
+ * Tempo extension module (ADR-213 §B).
+ *
+ * Bounds: the Tempo **Account** field. The standard Jira issue-edit endpoint accepts it, but
+ * expects the numeric Tempo account id — not the account name. `resolveWrite` turns a name string
+ * into that id using the field's allowed values from createmeta (project-scoped) — so no Tempo API
+ * token is needed. `detect()` reports whether a Tempo-managed field is present in the field catalog.
+ *
+ * (Tempo Team and worklog attributes are deliberately out of scope for now — see the ADR. The
+ * modern Tempo Cloud API at api.tempo.io has its own token; if a future handler needs it, that's
+ * when a `TEMPO_API_TOKEN` mechanism gets added — the `requires` hook on a route is for that case.)
+ */
+import { matchAllowedValue } from './types.js';
+import { fieldDiscovery } from '../client/field-discovery.js';
+/** Tempo's Connect/Forge field-key marker — appears in schema `custom` types and in Jira's
+ *  field-error keys for Tempo-managed fields (e.g. `io.tempo.jira__account`). */
+const TEMPO_FIELD_MARKER = /io\.tempo\./i;
+/** Resolve the Account field's `customFields` value to the numeric id Jira expects. */
+async function resolveTempoAccountWrite(ctx, fieldId, value) {
+    if (typeof value === 'number')
+        return value;
+    if (value !== null && typeof value === 'object')
+        return value; // already `{id: ...}` or similar
+    if (typeof value !== 'string')
+        return value; // unknown shape — let Jira reject it
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed); // bare numeric string → the id
+    const options = await fieldDiscovery.getFieldAllowedValues(ctx.client, ctx.projectKey, ctx.issueTypeName, fieldId);
+    if (options.length === 0) {
+        throw new Error(`Couldn't resolve the Account value "${value}" — the Account field exposes no enumerable ` +
+            `options on ${ctx.projectKey}/${ctx.issueTypeName} (it may not be on that issue type's screen, ` +
+            `or no Tempo accounts are linked to this project). Pass the numeric Tempo account id directly ` +
+            `(customFields: {"Account": <id>}), or set it in the Jira UI.`);
+    }
+    return matchAllowedValue(value, options, 'Account', ctx.projectKey);
+}
+const accountRoute = {
+    names: ['account', 'tempo account', 'io.tempo.jira__account'],
+    resolveWrite: resolveTempoAccountWrite,
+    unhandled: {
+        reason: 'tempo_account_value_format',
+        message: 'The Account field is provided by the Tempo app. Pass the account *name* (e.g. ' +
+            '"OpEx - Praecipio AI Dev") or its numeric id — this server resolves a name to the id via the ' +
+            'project\'s field options. If it still fails, the account may not be linked to this project, ' +
+            'or the field may not be on this issue type\'s screen; setting it inline in the Jira UI works.',
+    },
+};
+export const tempo = {
+    id: 'tempo',
+    displayName: 'Tempo (Account field)',
+    routes: [accountRoute],
+    async detect() {
+        try {
+            const hits = fieldDiscovery.getCatalog().filter(f => TEMPO_FIELD_MARKER.test(f.schemaCustom));
+            if (hits.length === 0)
+                return { present: false };
+            return { present: true, notes: `Tempo-managed field(s): ${hits.map(f => `${f.name} (${f.id})`).join(', ')}` };
+        }
+        catch {
+            return { present: false, notes: 'detection skipped (field catalog unavailable)' };
+        }
+    },
+};

package/build/extensions/types.js

@@ -0,0 +1,32 @@
+/**
+ * Extension modules (ADR-213 §B).
+ *
+ * An *extension module* bundles the handling for one thing that needs treatment beyond a plain
+ * `customFields` write — Atlassian's own special fields (Sprint, Epic Link, Rank), the Tempo
+ * Account field, and so on. A module declares its **bounds** (the field routes it owns — it touches
+ * those fields and nothing else) and, optionally, a cheap read-only `detect()` so jira://capabilities
+ * can report whether the extension's target is present on this tenant.
+ *
+ * This is deliberately *not* a generic plugin SDK: modules are composed by an explicit, hand-curated
+ * list in `index.ts` — no auto-discovery, no glob. Adding one is a reviewed edit, justified by a
+ * common user flow.
+ */
+/**
+ * Match a human-friendly value against a field's allowed options. Exact (case-insensitive) wins;
+ * otherwise a single substring match; ambiguity / no match throws with the available options. Shared
+ * by modules that resolve a name to an option id.
+ */
+export function matchAllowedValue(value, options, fieldLabel, scope) {
+    const norm = (s) => s.trim().toLowerCase();
+    const target = norm(value);
+    const exact = options.filter(o => norm(o.value) === target);
+    const matches = exact.length > 0 ? exact : options.filter(o => norm(o.value).includes(target));
+    if (matches.length === 1)
+        return matches[0].id;
+    const list = options.map(o => `${o.value} (${o.id})`).join(', ');
+    if (matches.length === 0) {
+        throw new Error(`"${value}" doesn't match any ${fieldLabel} option on ${scope}. Available: ${list}.`);
+    }
+    throw new Error(`"${value}" is ambiguous on ${scope} — matches: ${matches.map(o => `${o.value} (${o.id})`).join(', ')}. ` +
+        `Use the exact name or the numeric id.`);
+}

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