@aaronsb/jira-cloud-mcp 0.9.0 → 0.11.0

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/media-handler.js

@@ -0,0 +1,130 @@
+/**
+ * Handler for manage_jira_media tool.
+ * See ADR-211: Attachment and Workspace Management.
+ */
+import * as fs from 'node:fs/promises';
+import { mediaNextSteps } from '../utils/next-steps.js';
+import { ensureWorkspaceDir, formatSize, resolveWorkspacePath, ensureParentDir, verifyPathSafety, sanitizeFilename, } from '../workspace/index.js';
+export async function handleMediaRequest(client, args) {
+    switch (args.operation) {
+        case 'list': {
+            if (!args.issueKey) {
+                return { content: [{ type: 'text', text: 'issueKey is required for list operation' }], isError: true };
+            }
+            const attachments = await client.getIssueAttachments(args.issueKey);
+            if (attachments.length === 0) {
+                let text = `No attachments on ${args.issueKey}.`;
+                text += mediaNextSteps('list', { issueKey: args.issueKey });
+                return { content: [{ type: 'text', text }] };
+            }
+            const lines = attachments.map(a => `- ${a.filename} | ${a.mimeType} | ${formatSize(a.size)} | id:${a.id} | ${a.author} | ${a.created}`);
+            let text = `Attachments on ${args.issueKey} (${attachments.length}):\n${lines.join('\n')}`;
+            text += mediaNextSteps('list', { issueKey: args.issueKey });
+            return { content: [{ type: 'text', text }] };
+        }
+        case 'upload': {
+            if (!args.issueKey || !args.filename || !args.mediaType) {
+                return {
+                    content: [{ type: 'text', text: 'issueKey, filename, and mediaType are required for upload' }],
+                    isError: true,
+                };
+            }
+            let buffer;
+            if (args.workspaceFile) {
+                const filePath = resolveWorkspacePath(args.workspaceFile);
+                await verifyPathSafety(filePath);
+                try {
+                    buffer = await fs.readFile(filePath);
+                }
+                catch {
+                    return { content: [{ type: 'text', text: `Workspace file not found: ${args.workspaceFile}` }], isError: true };
+                }
+            }
+            else if (args.content) {
+                buffer = Buffer.from(args.content, 'base64');
+            }
+            else {
+                return {
+                    content: [{ type: 'text', text: 'Either content (base64) or workspaceFile is required for upload' }],
+                    isError: true,
+                };
+            }
+            const safeFilename = sanitizeFilename(args.filename);
+            const attachment = await client.uploadAttachment(args.issueKey, safeFilename, buffer, args.mediaType);
+            let text = `Uploaded: ${attachment.filename} | ${attachment.mimeType} | ${formatSize(attachment.size)} | id:${attachment.id}`;
+            text += mediaNextSteps('upload', { issueKey: args.issueKey });
+            return { content: [{ type: 'text', text }] };
+        }
+        case 'delete': {
+            if (!args.attachmentId) {
+                return { content: [{ type: 'text', text: 'attachmentId is required for delete operation' }], isError: true };
+            }
+            await client.deleteAttachment(args.attachmentId);
+            return { content: [{ type: 'text', text: `Permanently deleted attachment ${args.attachmentId} from Jira. This cannot be undone.` }] };
+        }
+        case 'view': {
+            if (!args.attachmentId) {
+                return { content: [{ type: 'text', text: 'attachmentId is required for view operation' }], isError: true };
+            }
+            const info = await client.getAttachmentInfo(args.attachmentId);
+            if (!info.mimeType.startsWith('image/')) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `${info.filename} | ${info.mimeType} | ${formatSize(info.size)}\n\nNot an image — cannot display inline. Use download to fetch raw content.`,
+                        }],
+                };
+            }
+            const MAX_IMAGE_SIZE = 5 * 1024 * 1024; // 5MB
+            if (info.size > MAX_IMAGE_SIZE) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `${info.filename} | ${info.mimeType} | ${formatSize(info.size)}\n\nImage too large to display inline (${(info.size / 1024 / 1024).toFixed(1)}MB, max 5MB). Use download instead.`,
+                        }],
+                };
+            }
+            const bytes = await client.downloadAttachment(args.attachmentId);
+            return {
+                content: [
+                    { type: 'text', text: `${info.filename} | ${info.mimeType}` },
+                    { type: 'image', data: bytes.toString('base64'), mimeType: info.mimeType },
+                ],
+            };
+        }
+        case 'get_info': {
+            if (!args.attachmentId) {
+                return { content: [{ type: 'text', text: 'attachmentId is required for get_info operation' }], isError: true };
+            }
+            const attachInfo = await client.getAttachmentInfo(args.attachmentId);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `${attachInfo.filename} | ${attachInfo.mimeType} | ${formatSize(attachInfo.size)} | id:${attachInfo.id} | ${attachInfo.author} | ${attachInfo.created}`,
+                    }],
+            };
+        }
+        case 'download': {
+            if (!args.attachmentId) {
+                return { content: [{ type: 'text', text: 'attachmentId is required for download operation' }], isError: true };
+            }
+            const dlInfo = await client.getAttachmentInfo(args.attachmentId);
+            const dlBytes = await client.downloadAttachment(args.attachmentId);
+            const status = await ensureWorkspaceDir();
+            if (!status.valid) {
+                return { content: [{ type: 'text', text: `Workspace invalid: ${status.warning}` }], isError: true };
+            }
+            const dlFilename = args.filename || sanitizeFilename(dlInfo.filename);
+            const dlPath = resolveWorkspacePath(dlFilename);
+            await verifyPathSafety(dlPath);
+            await ensureParentDir(dlPath);
+            await fs.writeFile(dlPath, dlBytes);
+            let text = `Downloaded: ${dlFilename} | ${dlInfo.mimeType} | ${formatSize(dlBytes.length)}\nPath: ${dlPath}`;
+            text += `\n\nUse manage_workspace read or manage_jira_media upload with workspaceFile:"${dlFilename}" to use it.`;
+            text += mediaNextSteps('download', {});
+            return { content: [{ type: 'text', text }] };
+        }
+        default:
+            return { content: [{ type: 'text', text: `Unknown media operation: ${args.operation}` }], isError: true };
+    }
+}

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),
             }],
     };