@aaronsb/jira-cloud-mcp 0.2.6 → 0.3.0

package/README.md

@@ -4,8 +4,6 @@ A Model Context Protocol server for interacting with Jira Cloud instances.
 
 ## Quick Start
 
-### Installation
-
 Add to your MCP settings:
 
 ```json
@@ -30,40 +28,34 @@ Or install globally:
 npm install -g @aaronsb/jira-cloud-mcp
 ```
 
-For detailed installation instructions, see the [Getting Started Guide](./docs/getting-started.md).
-
-## Key Features
-
-- **Issue Management**: Create, retrieve, update, and comment on Jira issues
-- **Search Capabilities**: JQL search with filtering
-- **Project & Board Management**: List and manage projects, boards, and sprints
-- **MCP Resources**: Access Jira data as context through MCP resources
-- **Tool Documentation**: Comprehensive documentation for each tool available as MCP resources
-- **Customization**: Support for custom fields and workflows
+### Credentials
 
-## Architecture
+Generate an API token at [Atlassian Account Settings](https://id.atlassian.com/manage/api-tokens).
 
-The server is built with a modular architecture:
+## Tools
 
-```
-src/
-├── client/       # Core Jira API client
-├── handlers/     # MCP tool handlers
-├── schemas/      # JSON schemas for tools
-├── types/        # TypeScript definitions
-├── utils/        # Utility functions
-└── index.ts      # Server entry point
-```
+| Tool | Description |
+|------|-------------|
+| `manage_jira_issue` | Get, create, update, delete, move, transition, comment on, or link Jira issues |
+| `manage_jira_filter` | Search for issues using JQL queries, or manage saved filters |
+| `manage_jira_project` | List projects or get project details including status counts |
+| `manage_jira_board` | List boards or get board details and configuration |
+| `manage_jira_sprint` | Manage sprints: create, start, close, and assign issues to sprints |
+| `queue_jira_operations` | Execute multiple operations in one call with result references and error strategies |
 
-## Documentation
+Each tool accepts an `operation` parameter (except `queue_jira_operations` which takes an `operations` array). Detailed documentation is available as MCP resources at `jira://tools/{tool_name}/documentation`.
 
-Essential documentation is available in the `docs/` directory:
+## MCP Resources
 
-- [Getting Started](./docs/getting-started.md) - Setup and installation
-- [API Reference](./docs/api-reference.md) - Available tools and usage
-- [Resources](./docs/resources.md) - Available MCP resources
-- [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
-- [Development](./docs/development.md) - Development guide
+| Resource | Description |
+|----------|-------------|
+| `jira://instance/summary` | Instance-level statistics |
+| `jira://projects/{key}/overview` | Project overview with status counts |
+| `jira://boards/{id}/overview` | Board overview with sprint info |
+| `jira://issue-link-types` | Available issue link types |
+| `jira://custom-fields` | Custom field catalog (auto-discovered at startup) |
+| `jira://custom-fields/{project}/{issueType}` | Context-specific custom fields |
+| `jira://tools/{name}/documentation` | Tool documentation |
 
 ## License
 

package/build/client/field-discovery.js

@@ -0,0 +1,346 @@
+/**
+ * Dynamic custom field discovery (ADR-201).
+ *
+ * Builds a master catalog of interesting custom fields at startup.
+ * Runs asynchronously — before the catalog is ready, custom fields
+ * pass through unfiltered (no regression from pre-discovery behavior).
+ */
+import { classifyFieldType } from './field-type-map.js';
+// ── Constants ──────────────────────────────────────────────────────────
+const HARD_CAP = 30;
+const SPREAD_RATIO_THRESHOLD = 10;
+// Scoring weights
+const SCREEN_WEIGHT = 10;
+const RECENCY_WEIGHT = 5;
+const RECENCY_HALF_LIFE_DAYS = 30;
+// ── Field Discovery ────────────────────────────────────────────────────
+export class FieldDiscovery {
+    catalog = [];
+    nameToId = new Map();
+    idToField = new Map();
+    stats = null;
+    ready = false;
+    error = null;
+    /** Whether the catalog has been built */
+    isReady() {
+        return this.ready;
+    }
+    /** Error message if startup discovery failed */
+    getError() {
+        return this.error;
+    }
+    /** The master catalog of discovered fields */
+    getCatalog() {
+        return this.catalog;
+    }
+    /** Discovery stats (available after catalog build) */
+    getStats() {
+        return this.stats;
+    }
+    /** Resolve a human-readable field name to its Jira field ID */
+    resolveNameToId(name) {
+        return this.nameToId.get(name.toLowerCase()) ?? null;
+    }
+    /** Look up a catalog field by ID */
+    getFieldById(id) {
+        return this.idToField.get(id);
+    }
+    /**
+     * Get fields valid for a specific project + issue type, intersected with the master catalog.
+     * Returns only writable catalog fields that are also valid for this context.
+     * Falls back to the full writable catalog if the createmeta call fails.
+     */
+    async getContextFields(client, projectKey, issueTypeName) {
+        if (!this.ready || this.catalog.length === 0) {
+            return [];
+        }
+        try {
+            // Step 1: Get issue types for this project
+            const issueTypes = await client.issues.getCreateIssueMetaIssueTypes({
+                projectIdOrKey: projectKey,
+            });
+            const matchingType = (issueTypes.issueTypes || issueTypes.createMetaIssueType || [])
+                .find(t => t.name?.toLowerCase() === issueTypeName.toLowerCase());
+            if (!matchingType?.id) {
+                console.error(`[field-discovery] Issue type "${issueTypeName}" not found in project ${projectKey}`);
+                return this.catalog.filter(f => f.writable);
+            }
+            // Step 2: Get fields for this project + issue type (paginated)
+            const contextFieldIds = new Set();
+            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)
+                        contextFieldIds.add(f.fieldId);
+                }
+                if (fields.length < maxResults) {
+                    hasMore = false;
+                }
+                startAt += fields.length;
+            }
+            // Step 3: Intersect with master catalog (writable fields only)
+            return this.catalog.filter(f => f.writable && contextFieldIds.has(f.id));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`[field-discovery] Context field fetch failed for ${projectKey}/${issueTypeName}: ${msg}`);
+            // Fall back to all writable catalog fields
+            return this.catalog.filter(f => f.writable);
+        }
+    }
+    /**
+     * Start discovery in the background. Does not block.
+     * Returns a promise that resolves when done (for testing).
+     */
+    startAsync(client) {
+        const promise = this.discover(client);
+        // Fire-and-forget for the server — errors are logged and stored
+        promise.catch(() => { });
+        return promise;
+    }
+    /**
+     * Build the master catalog from Jira's field metadata.
+     */
+    async discover(client) {
+        try {
+            console.error('[field-discovery] Starting custom field discovery...');
+            const rawFields = await this.fetchAllCustomFields(client);
+            console.error(`[field-discovery] Fetched ${rawFields.length} custom fields`);
+            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.`);
+            }
+            // 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
+        }
+    }
+    /**
+     * Fetch all custom fields with metadata via paginated API.
+     */
+    async fetchAllCustomFields(client) {
+        const allFields = [];
+        let startAt = 0;
+        const maxResults = 50;
+        let hasMore = true;
+        while (hasMore) {
+            const page = await client.issueFields.getFieldsPaginated({
+                type: ['custom'],
+                expand: ['lastUsed', 'screensCount', 'isLocked'],
+                startAt,
+                maxResults,
+            });
+            const values = page.values || [];
+            for (const f of values) {
+                allFields.push({
+                    id: f.id,
+                    name: f.name,
+                    description: f.description || '',
+                    isLocked: f.isLocked || false,
+                    screensCount: f.screensCount || 0,
+                    lastUsed: f.lastUsed?.value || null,
+                    lastUsedType: f.lastUsed?.type || 'NO_INFORMATION',
+                    schemaType: f.schema?.type || '',
+                    schemaCustom: f.schema?.custom || '',
+                    schemaItems: f.schema?.items || '',
+                });
+            }
+            if (page.isLast || values.length < maxResults) {
+                hasMore = false;
+            }
+            startAt += values.length;
+        }
+        return allFields;
+    }
+    /**
+     * Apply qualification filters (ADR-201 §Qualification Criteria).
+     */
+    filterAndClassify(rawFields) {
+        const qualified = [];
+        let excludedNoDescription = 0;
+        let excludedNoScreens = 0;
+        let excludedUnsupportedType = 0;
+        let excludedLocked = 0;
+        // Count on-screen custom fields without descriptions for the nag ratio
+        let onScreenTotal = 0;
+        let onScreenNoDescription = 0;
+        for (const field of rawFields) {
+            // Track nag ratio across all on-screen fields
+            if (field.screensCount > 0) {
+                onScreenTotal++;
+                if (!field.description.trim()) {
+                    onScreenNoDescription++;
+                }
+            }
+            // Filter: not locked
+            if (field.isLocked) {
+                excludedLocked++;
+                continue;
+            }
+            // Filter: has description (hard gate)
+            if (!field.description.trim()) {
+                excludedNoDescription++;
+                continue;
+            }
+            // Filter: on at least 1 screen
+            if (field.screensCount < 1) {
+                excludedNoScreens++;
+                continue;
+            }
+            // Filter: supported type
+            const typeInfo = classifyFieldType(field.schemaType, field.schemaCustom || undefined, field.schemaItems || undefined);
+            if (typeInfo.category === 'unsupported') {
+                excludedUnsupportedType++;
+                continue;
+            }
+            qualified.push({ ...field, typeInfo });
+        }
+        const undescribedRatio = onScreenTotal > 0 ? onScreenNoDescription / onScreenTotal : 0;
+        return {
+            qualified,
+            stats: {
+                totalCustomFields: rawFields.length,
+                excludedNoDescription,
+                excludedNoScreens,
+                excludedUnsupportedType,
+                excludedLocked,
+                undescribedRatio,
+            },
+        };
+    }
+    /**
+     * Score fields by composite score (screens × weight + recency × weight).
+     */
+    scoreFields(fields) {
+        const now = Date.now();
+        return fields.map(field => {
+            const screenScore = field.screensCount * SCREEN_WEIGHT;
+            let recencyScore = 0;
+            if (field.lastUsed && field.lastUsedType === 'TRACKED') {
+                const lastUsedMs = new Date(field.lastUsed).getTime();
+                const daysSinceUse = Math.max(0, (now - lastUsedMs) / (1000 * 60 * 60 * 24));
+                // Exponential decay: recently used fields score higher
+                recencyScore = Math.exp(-daysSinceUse / RECENCY_HALF_LIFE_DAYS) * RECENCY_WEIGHT;
+            }
+            const score = screenScore + recencyScore;
+            return { ...field, score };
+        });
+    }
+    /**
+     * Apply tail-curve cutoff (ADR-201 §Ranking and Tail-Curve Cutoff).
+     */
+    applyCutoff(fields) {
+        if (fields.length === 0)
+            return [];
+        // Sort descending by score
+        const sorted = [...fields].sort((a, b) => b.score - a.score);
+        // Check spread ratio
+        const maxScore = sorted[0].score;
+        const medianIndex = Math.floor(sorted.length / 2);
+        const medianScore = sorted[medianIndex].score;
+        let cutFields;
+        if (medianScore === 0 || maxScore / medianScore < SPREAD_RATIO_THRESHOLD) {
+            // Flat distribution — include all
+            cutFields = sorted;
+        }
+        else {
+            // Steep distribution — find the knee
+            const kneeIndex = this.findKnee(sorted);
+            cutFields = sorted.slice(0, kneeIndex + 1);
+        }
+        // Apply hard cap
+        const capped = cutFields.slice(0, HARD_CAP);
+        return capped.map(f => ({
+            id: f.id,
+            name: f.name,
+            description: f.description,
+            category: f.typeInfo.category,
+            writable: f.typeInfo.writable,
+            jsonSchema: f.typeInfo.jsonSchema,
+            screensCount: f.screensCount,
+            lastUsed: f.lastUsed,
+            score: Math.round(f.score * 100) / 100,
+        }));
+    }
+    /**
+     * Find the knee in a descending-sorted score list.
+     * The knee is where the largest relative drop between adjacent scores occurs.
+     */
+    findKnee(sorted) {
+        if (sorted.length <= 2)
+            return sorted.length - 1;
+        let maxRatio = 0;
+        let kneeIndex = sorted.length - 1;
+        for (let i = 0; i < sorted.length - 1; i++) {
+            const current = sorted[i].score;
+            const next = sorted[i + 1].score;
+            if (next === 0) {
+                kneeIndex = i;
+                break;
+            }
+            const ratio = current / next;
+            if (ratio > maxRatio) {
+                maxRatio = ratio;
+                kneeIndex = i;
+            }
+        }
+        return kneeIndex;
+    }
+    buildIndexes() {
+        this.nameToId.clear();
+        this.idToField.clear();
+        for (const field of this.catalog) {
+            // First wins — catalog is sorted by score descending, so higher-scored field takes precedence
+            // when multiple Jira custom fields share the same name
+            if (!this.nameToId.has(field.name.toLowerCase())) {
+                this.nameToId.set(field.name.toLowerCase(), field.id);
+            }
+            this.idToField.set(field.id, field);
+        }
+    }
+    logExclusions(rawFields, catalog) {
+        const catalogIds = new Set(catalog.map(f => f.id));
+        const excluded = rawFields.filter(f => !catalogIds.has(f.id));
+        for (const field of excluded) {
+            const reasons = [];
+            if (field.isLocked)
+                reasons.push('locked');
+            if (!field.description.trim())
+                reasons.push('no description');
+            if (field.screensCount < 1)
+                reasons.push('not on any screen');
+            const typeInfo = classifyFieldType(field.schemaType, field.schemaCustom || undefined, field.schemaItems || undefined);
+            if (typeInfo.category === 'unsupported')
+                reasons.push(`unsupported type (${field.schemaCustom || field.schemaType})`);
+            if (reasons.length === 0)
+                reasons.push('below cutoff');
+            console.error(`[field-discovery] Excluded: ${field.name} (${field.id}) — ${reasons.join(', ')}`);
+        }
+    }
+}
+// ── Singleton ──────────────────────────────────────────────────────────
+/** Singleton instance — lives for the MCP server process lifetime */
+export const fieldDiscovery = new FieldDiscovery();

package/build/client/field-type-map.js

@@ -0,0 +1,106 @@
+/**
+ * Maps Jira custom field schema types to JSON Schema representations (ADR-201 §Schema Type Mapping).
+ *
+ * v1 supported types: string, number, date, single-select, multi-select, user picker, labels, URL.
+ * Cascading selects and exotic types (assets, objects) are unsupported for writes.
+ */
+/** Suffix after the last ':' in the Jira custom field type URI */
+const CUSTOM_TYPE_SUFFIX = {
+    textfield: 'string',
+    textarea: 'string',
+    float: 'number',
+    datepicker: 'date',
+    datetime: 'datetime',
+    select: 'single-select',
+    radiobuttons: 'single-select',
+    multiselect: 'multi-select',
+    multicheckboxes: 'multi-select',
+    userpicker: 'user',
+    multiuserpicker: 'multi-user',
+    labels: 'labels',
+    url: 'url',
+    // Unsupported — recognized so we can label them explicitly
+    cascadingselect: 'unsupported',
+};
+/** Fallback mapping from the schema `type` field when the custom URI isn't recognized */
+const SCHEMA_TYPE_FALLBACK = {
+    string: 'string',
+    number: 'number',
+    date: 'date',
+    datetime: 'datetime',
+    user: 'user',
+    option: 'single-select',
+};
+const JSON_SCHEMAS = {
+    string: { type: 'string' },
+    number: { type: 'number' },
+    date: { type: 'string', format: 'date' },
+    datetime: { type: 'string', format: 'date-time' },
+    'single-select': { type: 'string', description: 'Select from allowed values' },
+    'multi-select': { type: 'array', items: { type: 'string', description: 'Select from allowed values' } },
+    user: { type: 'string', description: 'Atlassian accountId' },
+    'multi-user': { type: 'array', items: { type: 'string', description: 'Atlassian accountId' } },
+    labels: { type: 'array', items: { type: 'string' } },
+    url: { type: 'string', format: 'uri' },
+    unsupported: {},
+};
+/**
+ * Classify a Jira field schema into our type system.
+ *
+ * @param schemaType - The `schema.type` value (e.g. "string", "number", "array", "option")
+ * @param customUri  - The `schema.custom` URI (e.g. "com.atlassian.jira.plugin.system.customfieldtypes:float")
+ * @param items      - The `schema.items` value for array types
+ */
+export function classifyFieldType(schemaType, customUri, items) {
+    // Try the custom URI suffix first — most specific signal
+    if (customUri) {
+        const suffix = customUri.split(':').pop() || '';
+        const category = CUSTOM_TYPE_SUFFIX[suffix];
+        if (category) {
+            return {
+                category,
+                writable: category !== 'unsupported',
+                jsonSchema: JSON_SCHEMAS[category],
+            };
+        }
+    }
+    // For array types, check the items type
+    if (schemaType === 'array' && items) {
+        if (items === 'option')
+            return typeInfo('multi-select');
+        if (items === 'user')
+            return typeInfo('multi-user');
+        if (items === 'string')
+            return typeInfo('labels');
+    }
+    // Fall back to schema type
+    const fallback = SCHEMA_TYPE_FALLBACK[schemaType];
+    if (fallback) {
+        return typeInfo(fallback);
+    }
+    // Unrecognized — treat as unsupported (read-only on get, not suggested for writes)
+    return typeInfo('unsupported');
+}
+function typeInfo(category) {
+    return {
+        category,
+        writable: category !== 'unsupported',
+        jsonSchema: JSON_SCHEMAS[category],
+    };
+}
+/** Human-readable label for a field category */
+export function categoryLabel(category) {
+    switch (category) {
+        case 'string': return 'text';
+        case 'number': return 'number';
+        case 'date': return 'date';
+        case 'datetime': return 'date-time';
+        case 'single-select': return 'select';
+        case 'multi-select': return 'multi-select';
+        case 'user': return 'user';
+        case 'multi-user': return 'multi-user';
+        case 'labels': return 'labels';
+        case 'url': return 'URL';
+        case 'unsupported': return 'unsupported';
+    }
+}