@aaronsb/jira-cloud-mcp 0.10.0 → 0.11.1

package/build/client/field-discovery.js

@@ -6,6 +6,7 @@
  * pass through unfiltered (no regression from pre-discovery behavior).
  */
 import { classifyFieldType } from './field-type-map.js';
+import { routeForField } from '../extensions/index.js';
 // ── Constants ──────────────────────────────────────────────────────────
 const HARD_CAP = 30;
 const SPREAD_RATIO_THRESHOLD = 10;
@@ -14,6 +15,18 @@ const SCREEN_WEIGHT = 10;
 const RECENCY_WEIGHT = 5;
 const RECENCY_HALF_LIFE_DAYS = 30;
 // ── Field Discovery ────────────────────────────────────────────────────
+/**
+ * True if an extension route owns a value-resolving write handler for this field (ADR-213 §B).
+ * Used to mark `writable: true` on a field whose Jira type our classifier can't map — e.g. Tempo
+ * Account reports an opaque schema (→ `unsupported` category) but `resolveTempoAccountWrite` turns
+ * a name into the numeric id the standard issue-edit endpoint accepts. Matches the route by field
+ * name first, then by schema-custom key. (#45 follow-up: keeps the catalog `writable` flag in
+ * step with what the write path actually does.)
+ */
+function extensionCanWrite(fieldName, schemaCustom) {
+    const route = routeForField(fieldName) ?? (schemaCustom ? routeForField(schemaCustom) : undefined);
+    return route?.resolveWrite != null;
+}
 /** Well-known locked fields identified by schema custom type */
 const WELL_KNOWN_FIELDS = {
     'com.pyxis.greenhopper.jira:gh-sprint': 'sprint',
@@ -27,13 +40,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';
+    }
+    /** Granular catalog state — see {@link CatalogMode}. */
+    getState() {
+        return this.mode;
     }
-    /** Error message if startup discovery failed */
+    /** Error message if discovery failed (or degraded). */
     getError() {
         return this.error;
     }
@@ -67,7 +84,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 +207,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 +284,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 {
-            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)
+            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 {
+            // 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 +326,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 +403,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 || extensionCanWrite(f.name, f.schemaCustom),
+                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).
      */
@@ -318,6 +486,10 @@ export class FieldDiscovery {
                 continue;
             }
             // Filter: supported type
+            // NOTE: this also drops extension-handled fields whose Jira type our classifier can't map
+            // (e.g. Tempo Account on an admin tenant) — the unscored fallback keeps them and flags them
+            // writable via `extensionCanWrite`, but the scored path doesn't. Retaining them here is a
+            // larger change (it shifts what's in the curated catalog, not just a flag). See #45 / #57.
             const typeInfo = classifyFieldType(field.schemaType, field.schemaCustom || undefined, field.schemaItems || undefined);
             if (typeInfo.category === 'unsupported') {
                 excludedUnsupportedType++;
@@ -387,6 +559,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.`);
+}